Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ECLAT(1)		     Eclat User	Reference		      ECLAT(1)

NAME
       eclat - EC2 Command Line	Administrator Tool

SYNOPSIS
       eclat [OPTIONS] command [ARGS]

DESCRIPTION
       Eclat  is  a  tool that makes it	possible to manage Amazon EC2 services
       from the	command	line.  In contrast to the tools	provided by Amazon it-
       self, Eclat does	not require tons of resource-consuming libraries (Java
       madness), is very fast and efficient.

       All administrative tasks	are invoked through the	single binary,	eclat.
       The task	is identified by command given to it in	the command line.  Op-
       tions preceding the command configure the general behavior of the  tool
       itself.	 Any options and arguments following the command alter the be-
       havior of that particular command.

       Upon invocation eclat reads its configuration file eclat.conf.  The de-
       fault  location	of this	file is	determined when	compiling the package.
       Normally	it is /etc or /usr/local/etc.  This file provides the  default
       configuration  settings for the program,	such as	the location of	Amazon
       endpoints, default availability region, etc.  See eclat.conf(5),	for  a
       detailed	 description  of  its syntax.  By default this file is prepro-
       cessed using m4(1).  A set of command line options is provided to  con-
       trol this feature (see subsection Preprocessor control, below).

       Once  the  configuration	 file  is read,	the tool processes its command
       line options.  These options, when present, modify the default settings
       read from the configuration file.

       Finally,	 the  program uses its command argument	to identify the	action
       to be performed.	 It then forms an Amazon request using the rest	 argu-
       ments supplied to the command, and sends	it to the selected endpoint.

       Availability region specifies the region	in the AWS where the requested
       resource	is located.  It	can be set either in  the  configuration  file
       (the  default-region  statement),  or in	the command line (the --region
       option).

       If avaialbility region is not set, eclat	attempts to get	 it  from  the
       instance	 store.	  This attempt will succeed only if it is run on a EC2
       instance.

       An endpoint is a	URI of the Amazon server which is supposed  to	handle
       the request.  It	is selected according to the availability region.  The
       default value is	provided in the	 configuration	file  (using  the  de-
       fault-endpoint statement).

       Upon  completion	 of  the  action, Amazon sends back a response:	an XML
       document	containing details about the  result  of  the  operation  per-
       formed.	 This  document	is displayed using a special format, expressed
       in eclat	formatting language (forlan for	short).	 A set of default for-
       mats for	each request is	shipped	with the package.

       The  format  to	use  for each particular request is selected using the
       following algorithm.  If	the --format-expression	option is  given,  its
       argument	is treated as a	forlan text to use as a	format.	 Otherwise, if
       the --format-file option	is supplied, the format	to use	is  read  from
       the file	given as an argument to	that option.  Otherwise, if the	--for-
       mat option is used, the format is searched among	the user-defined  for-
       mats,  using the	option argument	as its name.  User-defined formats are
       declared	in the configuration file using	the define-format statement.

       If none of these	options	is given, the request action name is  used  to
       look  up	the default format to use.  A default format is	defined	in the
       configuration file using	the format statement.

       Finally,	if the default format is not defined as	well,  the  format  is
       read  from  the	file  specified	 by the	format-file configuration file
       statement.

       If eclat	fails to select	appropriate format using  this	procedure,  it
       dumps  the  contents  of	the response on	the standard output using path
       notation, where each tag	is identified by its name  and	the  names  of
       parent tags, separated by dots.

AUTHENTICATION
       Requests	 are authenticated using a pair	of strings: access key and se-
       cret key.  Their	function is similar to that  of	 username/password  in
       traditional authentication schemes.  These values are obtained from au-
       thentication  provider.	 There	are  three  types  of	authentication
       providers: immediate, file, and instance-store.

   Immediate Provider
       Both  keys  are	specified in the command line, using -O	(--access-key)
       and -W (--secret-key) options.  This usage is insecure as the arguments
       can easily be seen by other users (e.g. in the ps(1) output).

   File	Provider
       The  file  provider is requested	by the following statement in the con-
       figuration file:

       authentication-provider file FILENAME;

       The credentials are stored in a file protected by  appropriate  permis-
       sions.	Each  line  in such a file (named for short access-file) lists
       the access key and the corresponding secret key,	separated by a	colon.
       Empty  lines  are ignored, as well as lines starting with a # sign, ex-
       cept as immediately followed by a colon.	 In the	latter	case,  such  a
       line  introduces	 a  tag, which can be used to identify this line.  The
       tag consists of all the characters following the	#: marker  up  to  the
       first whitespace	character (newline being counted as a white space).

       The FILENAME argument is	treated	as a shell globbing pattern: all files
       matching	this pattern are attempted in turn, until a keypair is identi-
       fied, using the algorithm described below.  If an access	file cannot be
       opened due to insufficient privileges, no error message is issued  (un-
       less  the  debugging level main.1 or higher is requested).  This	allows
       you to have different access files  for	use  by	 different  groups  of
       users.

       If the -O (--access-key)	option is used,	its argument is	the access key
       or tag to look for in the access	file.  Otherwise,  eclat  selects  the
       first available key pair.

   Instance-store Provider
       The  program tries to obtain credentials	from the instance store, using
       the preconfigured IAM role name.

       This provider type is configured	by the following configuration	state-
       ment:

       authentication-provider instance-store ROLE;

       where ROLE is the name of a IAM role.

       This  provider  is recommended for use when you run eclat on an EC2 in-
       stance  which   is   assigned   a   role	  upon	 its   creation	  (see
       http://docs.aws.amazon.com/IAM/latest/UserGuide/roles-usingrole-ec2in-
       stance.html)

MAPS
       Each amazon resource has	a unique string	associated with	it, called its
       identifier.  Identifiers	provide	a means	for indicating the resource to
       operate upon.  For example, the command

       eclat start i-1234beef

       would start the instance	i-1234beef.  It	can be noted, that identifiers
       are  rather  machine- than human-oriented.  If you have a number	of re-
       sources,	it is not easy to remember  which  identifier  corresponds  to
       which resource.	In the example above, one would	rather prefer to iden-
       tify the	instance to be started	by  its	 functional  name  (say,  "db-
       server")	or its DNS name, than by its ID.  To make this possible, eclat
       provides	a mapping feature.

       A map is	a kind of dictionary that can be used to  translate  human-un-
       derstandable  resource names to their corresponding identifiers.	 Vari-
       ous backends can	be used	for storing the	data.  Eclat is	 shipped  with
       the support for the following storage mechanisms: plaintext files, GDBM
       databases and LDAP databases.  The actual set of	supported backends de-
       pends on	the compilation	options.

       The  mapping  feature is	enabled	when the --translate (-x) command line
       option is used.

       Maps are	defined	in the configuration  file  and	 are  assigned	unique
       names.	When  running  a  command,  eclat will by default select a map
       named by	the resource in	question.  For example,	when operating	on  an
       instance, the InstanceId	map will be used.

       For commands that support the resource-id filter, identifiers listed in
       that filter can be prefixed with	the map	name in	order to request their
       translation.  For example,

       eclat -x	lstag resource-id=InstanceId:webserver

       will  first  translate the name "webserver" using the "InstanceId" map,
       and then	will replace the entier	"InstanceId:webserver" construct  with
       the obtained identifier.	 See also eclat-lstag(1).

       The  name  of the map to	use can	also be	supplied explicitly, using the
       --map (-M) option.

       For  a  detailed	 description  of  maps,	 see  the  section   MAPS   in
       eclat.conf(5).

COMMANDS
       Each command is associated with two identifiers,	by which it can	be in-
       voked: the eclat	command	name and the EC2 command name.	Eclat  command
       names  are  short strings of up to 10 letters, which are	selected to be
       convenient in use and consistent	with the UNIX  command	naming	tradi-
       tion.   EC2  command names are long descriptive identifiers, consisting
       of letters and dashes and corresponding to  the	EC2  operation	codes.
       These  are designed for use in such contexts where the typing shortcuts
       are not required, but the self-documenting commands are	preferred  in-
       stead, e.g. in shell scripts.  Nevertheless, any	non-ambiguous abbrevi-
       ation can be used in place of a full EC2	command	name.  Moreover,  each
       segment	(i.e.  the sequence of characters delimited by dashes),	can be
       abbreviated independently.  For	example,  d-t  matches	describe-tags,
       whereas	d-i  matches three command names: describe-instance-attribute,
       describe-instance-status	and describe-instances.	 If an	ambiguous  ab-
       breviation  is  supplied,  eclat	 will print a list of matching command
       names on	the standard error and exit with the code 64 (see the  section
       EXIT CODES).

       If you use bash(1), you might consider using the	command	completion fa-
       cility provided with the	package.  To do	so, source the	file  compl.sh
       from  your profile or bash startup file (either per-user	or system-wide
       one, at your option).  This file	is installed (along  with  the	format
       files) in pkgdatadir.  For example, if your package is installed	to the
       /usr prefix, include this line in your bash startup:

	. /usr/share/eclat/compl.sh

       With the	completion facility enabled, hitting TAB after a partial  com-
       mand  name will show you	the list of possible completions.  If there is
       only one	completion, it will be used in place of	the partial name.

       To get a	help on	a particular  command,	refer  to  eclat-command  (1),
       where  command  is  the command name.  Currently	the following commands
       are implemented:

	       Eclat name  EC2 name
	       assocaddr   associate-address
	       assocrtab   associate-route-table
	       atigw	   attach-internet-gateway
	       atvol	   attach-volume
	       clrsattr	   reset-snapshot-attribute
	       cpimg	   copy-image
	       cpsnap	   copy-snapshot
	       deigw	   detach-internet-gateway
	       deimg	   deregister-image
	       devol	   detach-volume
	       disasaddr   disassociate-address
	       disasrtab   disassociate-route-table
	       dmesg	   get-console-output
	       lsaattr	   describe-image-attribute
	       lsaddr	   describe-addresses
	       lsattr
	       lsiattr	   describe-instance-attribute
	       lsigw	   describe-internet-gateways
	       lsimg	   describe-images
	       lsinst	   describe-instances
	       lsistat	   describe-instance-status
	       lsreg	   describe-regions
	       lsrtab	   describe-route-tables
	       lssattr	   describe-snapshot-attribute
	       lssg	   describe-security-groups
	       lssnap	   describe-snapshots
	       lssubnet	   describe-subnets
	       lstag	   describe-tags
	       lsvol	   describe-volumes
	       lsvpc	   describe-vpcs
	       lsvpcattr   describe-vpc-attribute
	       lszon	   describe-availability-zones
	       mkaddr	   allocate-address
	       mkigw	   create-internet-gateway
	       mkimg	   create-image
	       mkinst	   run-instances
	       mkrtab	   create-route-table
	       mksg	   create-security-group
	       mksnap	   create-snapshot
	       mksubnet	   create-subnet
	       mktag	   create-tags
	       mkvol	   create-volume
	       mkvpc	   create-vpc
	       reboot	   reboot-instances
	       rmaddr	   release-address
	       rmigw	   delete-internet-gateway
	       rmrtab	   delete-route-table
	       rmsg	   delete-security-group
	       rmsnap	   delete-snapshot
	       rmsubnet	   delete-subnet
	       rmtag	   delete-tags
	       rmvol	   delete-volume
	       rmvpc	   delete-vpc
	       route
	       setaattr	   modify-image-attribute
	       setiattr	   modify-instance-attribute
	       setsattr	   modify-snapshot-attribute
	       setsubnetattrmodify-subnet-attribute
	       setvpcattr  modify-vpc-attribute
	       sg
	       start	   start-instances
	       stop	   stop-instances

       Each command understands	a --help (-h) command line option  which  out-
       puts a terse summary on using this particular command.

OPTIONS
   Selecting program mode
       -E     Preprocess configuration and exit.

       -c, --config-file=FILE
	      Use FILE instead of the default configuration.

       -l, --list-commands=FORMAT
	      List all available commands using	the supplied FORMAT.  The for-
	      mat specification	consists of conversion specifiers, escape  se-
	      quences and ordinary character sequences.

	      A	 conversion specifier is introduced by the % character and and
	      terminated by a conversion specifier  character.	 Depending  on
	      that character, conversion specifiers are	replaced in the	output
	      with:

		      Specifier	  Expansion
		      n		  Eclat	command	name
		      i		  EC2 command name

	      Up to two	additional character sequences delimited with a	 semi-
	      colon  may  appear  between  the	% and the conversion specifier
	      character.  A sequence before the	semicolon supplies the	prefix
	      string to	be printed before the expansion.  A sequence after the
	      semicolon	supplies the suffix string, which is printed after the
	      expansion.  If the expansion is empty, neither prefix nor	suffix
	      appear in	the output.

	      Escape sequences are two-character sequences  beginning  with  a
	      backslash.  They are replaced in the output according to the ta-
	      ble below:

		      Sequence	Expansion		ASCII
		      \\	\			134
		      \"	"			042
		      \a	audible	bell		007
		      \b	backspace		010
		      \f	form-feed		014
		      \n	new line		012
		      \r	charriage return	015
		      \t	horizontal tabulation	011
		      \v	vertical tabulation	013

	      Any other	character following a backslash	is output verbatim.

	      Finally, ordinary	characters are reproduced on the output	as is.

	      This option is intended  to  help	 in  generating	 documentation
	      listings.	  For  example,	the command listing above was produced
	      using the	following command:

		  eclat	-l '\t\\fB%n\\fR\t\\fB%i\\fR\n'	| sed 's/-/\\-/g'

       --match-commands, -m
	      Print matching command names and exit.  This option is  intended
	      for  use	in completion facilities, such as Programmable Comple-
	      tion Builtins in bash(1).

       --test-map=MAPNAME
	      Test the translation map.	 In this mode eclat  treats  arguments
	      as  symbolic  names  to be translated.  It attempts to translate
	      each name	using the map MAPNAME  and  prints  out	 corresponding
	      Amazon identifiers on the	standard output.

   Configuration and Format Selection
       -t, --lint
	      Parse configuration file and exit.

       -F, --format-file, --formfile=FILE
	      Use FILE to format the output.

       -H, --format=NAME
	      Use the user-defined format NAME for output.

       -e, --format-expression=EXPR
	      Format expression.

   Access credentials
       -O, --access-key=STRING
	      Set access key to	use.

       -W, --secret-key=STRING
	      Set secret key to	use.

       -a, --access-file=NAME
	      Set access file.

       --region=NAME
	      Set AWS region name.

   Modifiers
       -N, --no
	      Eclat can	be configured to ask for confirmation before running a
	      potentially dangerous and	unrecoverable operation	(see the  sec-
	      tion CONFIRMATION	in eclat.conf(5)).  This option	overrides this
	      setting, assuming	negative answer.  See also -Y option below.

       -s, --sort
	      Sort the returned	XML teee prior to outputting it.

       --ssl  Use SSL (HTTPS) connection

       -Y, --yes
	      Eclat can	be configured to ask for confirmation before running a
	      potentially  dangerous and unrecoverable operation (see the sec-
	      tion CONFIRMATION	in eclat.conf(5)).  This option	overrides this
	      setting, assuming	positive answer.  See also -N option above.

   Mapping
       -M, --map=MAPNAME
	      Use this map instead of the default one (implies --translate).

       -x, --translate
	      Translate	 symbolic names	encountered in the command line	to the
	      corresponding resource IDs.

   Preprocessor	control
       -D, --define=SYMBOL[=VALUE]
	      Define a preprocessor symbol.

       -I, --include-directory=DIR
	      Add include directory.

       --no-preprocessor
	      Disable preprocessing.

       --preprocessor=COMMAND
	      Use COMMAND instead of the default preprocessor.

   Debugging
       -n, --dry-run
	      Do nothing, print	almost everything.

       -d, --debug=CAT[.LEVEL]
	      Set debugging level.

       --dump-grammar-trace
	      Dump configuration grammar traces.

       --dump-lex-trace
	      Dump lexical analyzer traces.

       -p, --check-permissions
	      Check if you have	the required permissions for the action, with-
	      out   actually  making  the  request.   This  is	equivalent  to
	      --add-parameter=DryRun=true.

       -A, --add-parameter=NAME=VALUE
	      Add parameter to the AWS request.

   Help	and additional information
       --config-help
	      Show configuration file summary.

       -V, --version
	      Print program version.

       -h, --help
	      Give a concise help summary.

       --usage
	      Give a short usage message.

EXIT CODES
       The eclat utility indicates the success or failure of the operation  by
       issuing a diagnostic message and	returning exit code to the shell.  The
       following exit codes are	used:

       0 (EX_OK)
	      Success.

       16     Command cancelled.  This code is returned	 when  the  user  have
	      given  a	negative  answer  to the confirmation request (see the
	      section CONFIRMATION in eclat.conf(5)).

       70 (EX_SOFTWARE)
	      Internal software	error occurred.

       64 (EX_USAGE)
	      Command line usage error,	e.g. an	unrecognized option  has  been
	      encountered, the command given does not correspond to any	of the
	      known commands, or the like.

       69 (EX_UNAVAILABLE)
	      Something	went wrong.  This is a catch-all error code, used when
	      no other exit code is deemed suitable.

       72 (EX_OSFILE)
	      Cannot open configuration	or format file.

       77 (EX_NOPERM)
	      Permission denied.  This code usually indicates that the config-
	      uration file cannot be opened because  of	 insufficient  permis-
	      sions.

       78 (EX_CONFIG)
	      Error in the configuration file.

       Other exit codes	may be returned	as a result of calling exit() from the
       format file.

ENVIRONMENT
       The environment variable	ECLAT_OPTIONS can contain a  list  of  default
       options	for eclat.  These options are processed	before the actual com-
       mand line options.

SEE ALSO
       eclat.conf(5), eclat-assocaddr(1), eclat-assocrtab(1),  eclat-atigw(1),
       eclat-atvol(1),	 eclat-clrsattr(1),  eclat-cpimg(1),  eclat-cpsnap(1),
       eclat-deigw(1),	eclat-deimg(1),	 eclat-devol(1),   eclat-disasaddr(1),
       eclat-disasrtab(1),  eclat-dmesg(1), eclat-lsaattr(1), eclat-lsaddr(1),
       eclat-lsattr(1),	 eclat-lsiattr(1),   eclat-lsigw(1),   eclat-lsimg(1),
       eclat-lsinst(1),	  eclat-lsistat(1),  eclat-lsreg(1),  eclat-lsrtab(1),
       eclat-lssattr(1),  eclat-lssg(1),  eclat-lssnap(1),  eclat-lssubnet(1),
       eclat-lstag(1),	 eclat-lsvol(1),  eclat-lsvpc(1),  eclat-lsvpcattr(1),
       eclat-lszon(1),	 eclat-mkaddr(1),   eclat-mkigw(1),    eclat-mkimg(1),
       eclat-mkinst(1),	  eclat-mkrtab(1),   eclat-mksg(1),   eclat-mksnap(1),
       eclat-mksubnet(1),  eclat-mktag(1),   eclat-mkvol(1),   eclat-mkvpc(1),
       eclat-reboot(1),	  eclat-rmaddr(1),   eclat-rmigw(1),  eclat-rmrtab(1),
       eclat-rmsg(1),  eclat-rmsnap(1),	  eclat-rmsubnet(1),   eclat-rmtag(1),
       eclat-rmvol(1),	 eclat-rmvpc(1),   eclat-route(1),  eclat-setaattr(1),
       eclat-setiattr(1),      eclat-setsattr(1),      eclat-setsubnetattr(1),
       eclat-setvpcattr(1),  eclat-sg(1),  eclat-start(1), eclat-stop(1), for-
       lan(5), ispeek(1).

AUTHORS
       Sergey Poznyakoff

BUG REPORTS
       Report bugs to <bug-eclat@gnu.org.ua>.

COPYRIGHT
       Copyright (C) 2012-2015 Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li-
       censes/gpl.html>
       This  is	 free  software:  you  are free	to change and redistribute it.
       There is	NO WARRANTY, to	the extent permitted by	law.

ECLAT			       November	19, 2015		      ECLAT(1)

NAME | SYNOPSIS | DESCRIPTION | AUTHENTICATION | MAPS | COMMANDS | OPTIONS | EXIT CODES | ENVIRONMENT | SEE ALSO | AUTHORS | BUG REPORTS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=eclat&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help