aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am19
-rw-r--r--doc/eclat-associate-address.195
-rw-r--r--doc/eclat.1300
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:
+

Return to:

Send suggestions and report system problems to the System administrator.