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 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 sup- plied to the command, and sends it to the selected endpoint. Availability region specifies the region in the AWS where the requested re- source is located. It can be set either in the configuration file (the de- fault-region statement), or in the command line (the --region option). If avaialbility region is not set, eclat attempts to get it from the in- stance store. This attempt will succeed only if it is run on a EC2 in- stance. 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 docu- ment 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 follow- ing algorithm. If the --format-expression option is given, its argument is treated as a forlan text to use as a format. Otherwise, if the --for- mat-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 ar- gument 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 configu- ration 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, sep- arated 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 configura- tion 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 char- acters following the #: marker up to the first whitespace character (new- line 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 de- bugging level main.1 or higher is requested). This allows you to have dif- ferent 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.ama- zon.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 op- erate 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-under- standable resource names to their corresponding identifiers. Various back- ends 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 compi- lation options. The mapping feature is enabled when the --translate (-x) command line op- tion 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 re- source in question. For example, when operating on an instance, the In- stanceId 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 ob- tained 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 con- venient 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: de- scribe-instance-attribute, describe-instance-status and describe-instances. If an ambiguous abbreviation is supplied, eclat will print a list of match- ing 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 facil- ity 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 pkg- datadir. For example, if your package is installed to the /usr prefix, in- clude 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 imple- mented: 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 setsubnetattrmodify-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 ter- minated 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 sup- plies the suffix string, which is printed after the expansion. If the expansion is empty, neither prefix nor suffix appear in the out- put. Escape sequences are two-character sequences beginning with a back- slash. They are replaced in the output according to the table be- low: 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 list- ings. 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 identi- fiers 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 po- tentially 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 po- tentially 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 cor- responding 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-parame- ter=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 is- suing a diagnostic message and returning exit code to the shell. The fol- lowing 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 CONFIR- MATION 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 en- countered, 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 configura- tion 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 op- tions for eclat. These options are processed before the actual command line options. SEE ALSO eclat.conf(5), eclat-assocaddr(1), eclat-assocrtab(1), eclat-atigw(1), eclat-atvol(1), eclat-chvol(1), eclat-clrsattr(1), eclat-cpimg(1), eclat-cpsnap(1), eclat-deigw(1), eclat-deimg(1), eclat-devol(1), eclat-dis- asaddr(1), eclat-disasrtab(1), eclat-dmesg(1), eclat-lsaattr(1), eclat-lsaddr(1), eclat-lsattr(1), eclat-lschvol(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-rm- subnet(1), eclat-rmtag(1), eclat-rmvol(1), eclat-rmvpc(1), eclat-route(1), eclat-setaattr(1), eclat-setiattr(1), eclat-setsattr(1), eclat-setsubne- tattr(1), eclat-setvpcattr(1), eclat-sg(1), eclat-start(1), eclat-stop(1), eclat-terminate(1), forlan(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+Ports+15.1.quarterly>