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 itself, 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. Options preceding the command configure the general behavior of the tool itself. Any options and arguments following the command alter the behavior of that particular command.

Upon invocation eclat reads its configuration file eclat.conf. The default 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 preprocessed using m4(1). A set of command line options is provided to control 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 arguments 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 default-endpoint statement).

Upon completion of the action, Amazon sends back a response: an XML document containing details about the result of the operation performed. This document is displayed using a special format, expressed in eclat formatting language (forlan for short). A set of default formats 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 --format option is used, the format is searched among the user-defined formats, 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 secret key. Their function is similar to that of username/password in traditional authentication schemes. These values are obtained from authentication 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 configuration file:

authentication-provider file FILENAME;

The credentials are stored in a file protected by appropriate permissions. 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, except 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 identified, using the algorithm described below. If an access file cannot be opened due to insufficient privileges, no error message is issued (unless 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 statement:

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 instance which is assigned a role upon its creation (see http://docs.aws.amazon.com/IAM/latest/UserGuide/roles-usingrole-ec2instance.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 resources, it is not easy to remember which identifier corresponds to which resource. In the example above, one would rather prefer to identify the instance to be started by its functional name (say, "dbserver") 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-understandable resource names to their corresponding identifiers. Various 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 depends 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 invoked: 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 tradition. 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 instead, e.g. in shell scripts. Nevertheless, any non-ambiguous abbreviation 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 abbreviation 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 facility 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 command 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
	chvol	modify-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
	lschvol	describe-volumes-modifications
	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
	setsubnetattr	modify-subnet-attribute
	setvpcattr	modify-vpc-attribute
	sg
	start	start-instances
	stop	stop-instances
	terminate	terminate-instances

Each command understands a --help (-h) command line option which outputs 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 format specification consists of conversion specifiers, escape sequences 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 semicolon 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 table 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 Completion 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 section 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 section 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, without 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 configuration file cannot be opened because of insufficient permissions.
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 command line options.

AUTHORS

Sergey Poznyakoff

BUG REPORTS

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

COPYRIGHT

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