Document authentication provider configuration.

3 files changed, 73 insertions, 38 deletions

diff --git a/NEWS b/NEWS
index a666e4a..3400232 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-Eclat NEWS -- history of user-visible changes. 2015-01-19
+Eclat NEWS -- history of user-visible changes. 2015-01-20
 Copyright (C) 2012-2015 Sergey Poznyakoff
 See the end of file for copying conditions.
 
@@ -30,7 +30,7 @@ statement in the configuration file.  The syntax is:
 
   authentication-provider TYPE ARG;
 
-TYPE cane be one of:
+TYPE can be one of:
 
 - file
 Credentials are obtained from a disk file named by the second
diff --git a/doc/eclat.1man b/doc/eclat.1man
index 9560e81..5030d7f 100644
--- a/doc/eclat.1man
+++ b/doc/eclat.1man
@@ -13,7 +13,7 @@
 .\"
 .\" 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 "January 19, 2015" "ECLAT" "Eclat User Reference"
+.TH ECLAT 1 "January 20, 2015" "ECLAT" "Eclat User Reference"
 .SH NAME
 eclat \- EC2 Command Line Administrator Tool
 .SH SYNOPSIS
@@ -119,12 +119,32 @@ 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
+traditional authentication schemes.  These values are obtained from
+.IR authentication provider .
+There are three types of authentication providers:
+.IR immediate ,
+.IR file ,
+and
+.IR instance\-store .
+.SS Immediate Provider
+Both keys are specified in the command line, using
+.BR \-O " (" \-\-access\-key )
+and
+.BR \-W " (" \-\-secret\-key )
+options.  This 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
+output).
+.SS File Provider
+The \Ifile\fR provider is requested by the following statement in
+the configuration file:
+.PP
+.EX
+authentication\-provider file \fIFILENAME\fR;
+.EE
+.PP
+The credentials are stored 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 colon.  Empty lines are ignored, as well as lines
 starting with a \fB#\fR sign, except as immediately followed by a
@@ -133,24 +153,32 @@ 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,
+The \fIFILENAME\fR 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 \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\-O\fR (\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.
+.SS Instance\-store Provider
+The program tries to obtain credentials from the instance store, using
+the preconfigured IAM role name.
+.PP
+This provider type is configured by the following configuration statement:
+.PP
+.EX
+authentication\-provider instance\-store \fIROLE\fR;
+.EE
+.PP
+where \fIROLE\fR is the name of a IAM role.
 .PP
-If the access key is not found in the access file, it is assumed to be
-a name of the \IIAM\fR role.  The program then tries to obtain
-credentials from the instance store.  This attempt will succeed only
-if \fBeclat\fR is run on an EC2 instance which is assigned a role upon
+This provider is recommended for use when you run \fBeclat\fR on an
+EC2 instance which is assigned a role upon
 its creation (see
 .BR http://docs.aws.amazon.com/IAM/latest/UserGuide/roles-usingrole-ec2instance.html )
 .SH MAPS
diff --git a/doc/eclat.conf.5 b/doc/eclat.conf.5
index feb504f..adf3796 100644
--- a/doc/eclat.conf.5
+++ b/doc/eclat.conf.5
@@ -13,7 +13,7 @@
 .\"
 .\" 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.CONF 5 "July 9, 2014" "ECLAT" "Eclat User Reference"
+.TH ECLAT.CONF 5 "January 20, 2015" "ECLAT" "Eclat User Reference"
 .SH NAME
 eclat.conf \- configuration file for
 .BR eclat (1).
@@ -378,24 +378,31 @@ region  us\-east\-1       ec2.us\-east\-1.amazonaws.com;
 #  US West (Oregon) Region
 region  us\-west\-2       ec2.us\-west\-2.amazonaws.com;
 .EE
-.SS ACCESS CREDENTIALS
-Access credentials for Amazon accounts are stored in a so-called
-\fBaccess-file\fR.  See the section
-.B AUTHENTICATION
-in
+.SS AUTHENTICATION
+.TP
+\fBauthentication\-provider\fR \fITYPE\fR \fIARG\fB;\fR
+Defines authentication provider to use.  \fIAuthentication provider\fR
+is a service that supplies AWS access key ID and secret key.  See
 .BR eclat (1),
-for a detailed description of its syntax.
-.PP
-The access file is defined using the following statement:
+section
+.BR AUTHENTICATION ,
+for a detailed description.
+
+The \fITYPE\fR argument defines the provider.  Allowed values are
+.BR file ,
+and
+.BR instance\-store .
+
+If \fITYPE\fR is \fBfile\fR, the \fIARG\fR parameter is treated as a
+shell globbing pattern: all files matching this pattern are attempted
+in turn, until a keypair is found in one of them.
+
+If \fITYPE\fR is \fBinstance\-store\fR, \fIARG\fR is the name of the
+IAM role.  Credentials will be obtained from the instance store for
+that role.
 .TP
 \fBaccess\-file\fR \fIname\fR;
-Declares the access file to use.  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.
+This is a shortcut for \fBauthentication\-provider file \fIname\fR.
 .TP
 \fBsignature\-version\fR \fIN\fR;
 Declares the signature version.  Valid values for \fIN\fR are \fB2\fR,