diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 19 | ||||
-rw-r--r-- | doc/eclat-associate-address.1 | 95 | ||||
-rw-r--r-- | doc/eclat.1 | 300 |
3 files changed, 414 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..1a230e0 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,19 @@ +# This file is part of Eclat +# Copyright (C) 2012 Sergey Poznyakoff +# +# Eclat is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3, or (at your option) +# any later version. +# +# Eclat is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Eclat. If not, see <http://www.gnu.org/licenses/>. + +dist_man_MANS=\ + eclat.1\ + eclat-associate-address.1
\ No newline at end of file diff --git a/doc/eclat-associate-address.1 b/doc/eclat-associate-address.1 new file mode 100644 index 0000000..866e914 --- /dev/null +++ b/doc/eclat-associate-address.1 @@ -0,0 +1,95 @@ +.\" This file is part of Eclat +.\" Copyright (C) 2012 Sergey Poznyakoff +.\" +.\" Eclat is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Eclat is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with Eclat. If not, see <http://www.gnu.org/licenses/>. +.TH ECLAT 1 "October 1, 2012" "ECLAT" "Eclat User Reference" +.SH NAME +eclat associate-address \- associate an IP address with an instance +.SH SYNOPSIS +eclat associate-address [\fIOPTIONS\fR] \fIINSTANCE\fR \fIIP\fR + +eclat associate-address [\fIOPTIONS\fR] \fIINSTANCE\fR \fIALLOC-ID\fR + +eclat associate-address \-\-help +.SH DESCRIPTION +The +.B associate-address +command associates an Elastic IP address with an non-VPC instance or +associates a VPC Elastic IP address with an instance in your VPC. +.PP +The first argument is always the ID of the instance to operate upon. +The meaning of the second argument depends on the \fB\-\-vpc\fR command +line option. If that option is given, the second argument supplies the +allocation ID that AWS returned when you allocated the Elastic IP +address for use with Amazon VPC. Otherwise, it is the Elastic IP to +assign to the non-VPC instance. +.SH OPTIONS +.TP +\fB\-A\fR, \fB\-\-allow\-reassociation\fR +Allows an already associated address to be re-associated with the +specified instance (VPC only). +.TP +\fB\-i\fR, \fB\-\-interface\fR=\fIIFACE\fR +A network interface ID to associate with the instance (vpc only). +.TP +\fB\-p\fR, \fB\-\-private\-address\fR=\fIADDRESS\fR +Private IP address to associate with the Elastic IP address (vpc +only). +.TP +\fB\-v\fR, \fB\-\-vpc\fR +Assign VPC addresses. +.SH "OUTPUT AND RETURN VALUE" +The default output format does not display anything if the operation +succeeds. Otherwise it prints on the standard error the diagnostic +message returned by the Amazon, and returns code 1 to the shell. +.PP +The code 2 is returned if +.B eclat +is unable to recognize the response. +.SH EXAMPLES +.SS 1. +Assign an Elastic IP to the instance: +.P +.nf +.B eclat associate-address i-2ea64347 192.0.2.1 +.fi +.SS 2. +Associate an IP address with an instance in the VPC: +.P +.nf +.B eclat associate-address --vpc i-4fd2431a eipalloc-5723d13e +.fi +.SH "SEE ALSO" +.BR eclat (1). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to <bug-eclat@gnu.org.ua>. +.SH COPYRIGHT +Copyright \(co 2012 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: + diff --git a/doc/eclat.1 b/doc/eclat.1 new file mode 100644 index 0000000..9481e0b --- /dev/null +++ b/doc/eclat.1 @@ -0,0 +1,300 @@ +.\" This file is part of Eclat +.\" Copyright (C) 2012 Sergey Poznyakoff +.\" +.\" Eclat is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Eclat is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with Eclat. If not, see <http://www.gnu.org/licenses/>. +.TH ECLAT 1 "October 1, 2012" "ECLAT" "Eclat User Reference" +.SH NAME +eclat \- EC2 Command Line Administrator Tool +.SH SYNOPSIS +.B eclat +[\fIOPTIONS\fR] +.B command +[\fIARGS\fR] +.SH DESCRIPTION +.B 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, +.B Eclat +does not require tons of resource-consuming libraries (\fBJava +madness\fR), is very fast and efficient. +.PP +All administrative tasks are invoked through the single binary, +.BR eclat . +The task is identified by +.B 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. +.PP +Upon invocation +.B eclat +reads its configuration file +.BR eclat.conf . +The default location of this file is determined when compiling the +package. Normally it is +.BR /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 +.BR eclat.conf (5), +for a detailed description of its syntax. By default this file is +preprocessed using +.BR m4 (1). +A set of command line options is provided to control this +feature (see subsection +.BR "Preprocessor control" , +below). +.PP +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. +.PP +Finally, the program uses its +.B 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. +.PP +An \fBendpoint\fR is a URI of the Amazon server which is supposed to +handle the request. It is selected according to availability region, +as set in the configuration file (the \fBdefault-region\fR statement), +or in the command line (the \fB\-\-region\fR option). If neither of +these is set, the endpoint specified by the \fBdefault-endpoint\fR +configuration statement is used. +.PP +Upon completion of the action, Amazon sends back a +.BR 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 (\fBforlan\fR for short). A set of +default formats for each request is shipped with the package. +.PP +The format to use for each particular request is selected using the +following algorithm. If the \fB\-\-format-expression\fR option is +given, its argument is treated as a +.B forlan +text to use as a format. Otherwise, if the \fB\-\-format-file\fR +option is supplied, the format to use is read from the file given as +an argument to that option. Otherwise, if the \fB\-\-format\fR 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 \fBdefine-format\fR statement. +.PP +If none of these options is given, the request +.B action name +is used to look up the default format to use. A default format is +defined in the configuration file using the \fBformat\fR statement. +.PP +Finally, if the default format is not defined as well, the format is +read from the file specified by the \fBformat-file\fR configuration +file statement. +.PP +If +.B eclat +fails to select appropriate format using this procedure, it dumps the +contents of the response on the standard output using +.BR "path notation" , +where each tag is identified by its name and the names of parent tags, +separated by dots. +.SH 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. Both keys can be specified in the +command line, but such usage is insecure as the arguments can easily +be seen by other users (e.g. in the +.BR ps (1) +output). The preferred way is to store them in a file protected by +appropriate permissions. Each line in such a file (named for short +\fBaccess-file\fR) lists access-key and the corresponding secret-key, +separated by a semicolon. Empty lines are ignored, as well as lines +starting with a \fB#\fR sign, except as immediately followed by a +semicolon. 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 \fB#:\fR marker up to the first whitespace +character (newline being counted as a white space). +.PP +The access file is set up using the \fBaccess-file\fR configuration +file statement. The argument to this statement 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 +\fBmain.1\fR or higher is requested). This allows you to have different +access files for use by different groups of users. +.PP +If the \fB\-\-access\-key\fR option is used, its argument is the +access-key or tag to look for in the access file. Otherwise, +.B eclat +selects the first available key pair. +.SH COMMANDS +To get a help on a particular command, refer to \fBeclat-\fIcommand\fR +(1), where \fIcommand\fR is the command name. Currently the following +commands are implemented: +.BR associate-address , +.BR describe-addresses , +.BR describe-instance-status , +.BR describe-instances , +.BR describe-tags , +.BR describe-volumes , +.BR disassociate-address , +.BR get-console-output , +.BR reboot-instances , +.BR start-instances , +.BR stop-instances . +.PP +Each command understands a \fB\-\-help\fR (\fB\-h\fR) command line +option which outputs a terse summary on using this particular command. +.SH OPTIONS +.SS Selecting program mode +.TP +\fB\-E\fR +Preprocess configuration and exit. +.TP +\fB\-c\fR, \fB\-\-config\-file\fR=\fIFILE\fR +Use \fIFILE\fR instead of the default configuration. +.SS Configuration and Format Selection +.TP +\fB\-t\fR, \fB\-\-lint\fR +Parse configuration file and exit. +.TP +\fB\-F\fR, \fB\-\-format\-file\fR, \fB\-\-formfile\fR=\fIFILE\fR +Use \fIFILE\fR to format the output. +.TP +\fB\-H\fR, \fB\-\-format\fR=\fINAME\fR +Use the user-defined format \fINAME\fR for output. +.TP +\fB\-e\fR, \fB\-\-format\-expression\fR=\fIEXPR\fR +Format expression. +.SS Access credentials +.TP +\fB\-O\fR, \fB\-\-access\-key\fR=\fISTRING\fR +Set access key to use. +.TP +\fB\-W\fR, \fB\-\-secret\-key\fR=\fISTRING\fR +Set secret key to use. +.TP +\fB\-a\fR, \fB\-\-access\-file\fR=\fINAME\fR +Set access file. +.TP +\fB\-\-region\fR=\fINAME\fR +Set AWS region (availability zone). +.SS Modifiers +.TP +\fB\-s\fR, \fB\-\-sort\fR +Sort the returned XML teee prior to outputting it. +.TP +\fB\-\-ssl\fR +Use SSL (HTTPS) connection +.SS Preprocessor control +.TP +\fB\-D\fR, \fB\-\-define\fR=\fISYMBOL\fR[=\fIVALUE\fB] +Define a preprocessor symbol. +.TP +\fB\-I\fR, \fB\-\-include\-directory\fR=\fIDIR\fR +Add include directory. +.TP +\fB\-\-no\-preprocessor\fR +Disable preprocessing. +.TP +\fB\-\-preprocessor\fR=\fICOMMAND\fR +Use \fICOMMAND\fR instead of the default preprocessor. +.SS Debugging +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +Do nothing, print almost everything. +.TP +\fB\-d\fR, \fB\-\-debug\fR=\fICAT\fR[.\fILEVEL\fR] +Set debugging level. +.TP +\fB\-\-dump\-grammar\-trace\fR +Dump configuration grammar traces. +.TP +\fB\-\-dump\-lex\-trace\fR +Dump lexical analyzer traces. +.SS Help and additional information +.TP +\fB\-\-config\-help +Show configuration file summary. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print program version. +.TP +\fB\-h\fR, \fB\-\-help\fR +Give a concise help summary. +.TP +\fB\-\-usage\fR +Give a short usage message. +.SH "EXIT CODES" +The +.B 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: +.TP +.BR 0 " (" EX_OK ")" +Success. +.TP +.BR 70 " (" EX_SOFTWARE ")" +Internal software error occurred. +.TP +.BR 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. +.TP +.BR 69 " (" EX_UNAVAILABLE ")" +Something went wrong. This is a catch-all error code, used when no +other exit code is deemed suitable. +.TP +.BR 72 " (" EX_OSFILE ")" +Cannot open configuration or format file. +.TP +.BR 77 " (" EX_NOPERM ")" +Permission denied. This code usually indicates that the configuration +file cannot be opened because of insufficient permissions. +.TP +.BR 78 " (" EX_CONFIG ")" +Error in the configuration file. +.PP +Another exit code means it has been set as a result of the +.B exit() +call in the format file. +.SH EXAMPLE +.SH "SEE ALSO" +.BR eclat.conf (5), +.BR forlan (5). +For a detailed description of a particular \fIcommand\fR, see +\fBeclat-\fIcommand\fR (1). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to <bug-eclat@gnu.org.ua>. +.SH COPYRIGHT +Copyright \(co 2012 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: + |