FreeBSD Manual Pages
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://man.freebsd.org/cgi/man.cgi?query=eclat&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>