aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2012-10-18 14:25:06 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2012-10-18 16:58:12 +0300
commit0e9392af1b684ce67230da5e2bfe4865ed69f055 (patch)
tree12d1b28cb21499ea47eaa5e166a179fbee3e0e98
parenta1591f2c2988826d5b4f476be125ffb2cd591b02 (diff)
downloadeclat-0e9392af1b684ce67230da5e2bfe4865ed69f055.tar.gz
eclat-0e9392af1b684ce67230da5e2bfe4865ed69f055.tar.bz2
Document all commands implemented so far.
* TODO: Update. * doc/Makefile.am: Update. * doc/eclat-describe-instance-status.1: New file. * doc/eclat-describe-security-groups.1: New file. * doc/eclat-describe-volumes.1: New file. * src/dscrsecgrps-cl.opt: Fix documentation. * src/dscrvols.c: Accept volume IDs in the command line.
-rw-r--r--TODO6
-rw-r--r--doc/Makefile.am3
-rw-r--r--doc/eclat-describe-instance-status.1182
-rw-r--r--doc/eclat-describe-security-groups.1134
-rw-r--r--doc/eclat-describe-volumes.1149
-rw-r--r--src/dscrsecgrps-cl.opt2
-rw-r--r--src/dscrvols.c5
7 files changed, 476 insertions, 5 deletions
diff --git a/TODO b/TODO
index 890ba0a..6c94507 100644
--- a/TODO
+++ b/TODO
@@ -80,7 +80,7 @@ DescribeImageAttribute DSCRIMGATTR [ ] [ ]
DescribeImages DSCRIMGS [ ] [ ]
DescribeInstanceAttribute DSCRINSTATTR [X] [X]
DescribeInstances DSCRINSTS [X] [X]
-DescribeInstanceStatus DSCRINSTSTAT [X] [ ]
+DescribeInstanceStatus DSCRINSTSTAT [X] [X]
DescribeInternetGateways DSCRINETGWS [ ] [ ]
DescribeKeyPairs DSCRKEYPAIRS [ ] [ ]
DescribeNetworkAcls DSCRNETACLS [ ] [ ]
@@ -92,7 +92,7 @@ DescribeReservedInstances DSCRRSRVDINSTS [ ] [ ]
DescribeReservedInstancesListings DSCRRSRVDINSTSLSTS [ ] [ ]
DescribeReservedInstancesOfferings DSCRRSRVDINSTSOFRS [ ] [ ]
DescribeRouteTables DSCRROUTTABS [ ] [ ]
-DescribeSecurityGroups DSCRSECGRPS [X] [ ]
+DescribeSecurityGroups DSCRSECGRPS [X] [X]
DescribeSnapshotAttribute DSCRSNAPATTR [ ] [ ]
DescribeSnapshots DSCRSNAPS [X] [X]
DescribeSpotDatafeedSubscription DSCRSPOTDFSSCR [ ] [ ]
@@ -100,7 +100,7 @@ DescribeSpotInstanceRequests DSCRSPOTINSTREQS [ ] [ ]
DescribeSpotPriceHistory DSCRSPOTPRICHIST [ ] [ ]
DescribeSubnets DSCRSUBS [ ] [ ]
DescribeTags DSCRTAGS [X] [X]
-DescribeVolumes DSCRVOLS [X] [ ]
+DescribeVolumes DSCRVOLS [X] [X]
DescribeVolumeAttribute DSCRVOLATTR [ ] [ ]
DescribeVolumeStatus DSCRVOLSTAT [ ] [ ]
DescribeVpcs DSCRVPCS [ ] [ ]
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 296a09f..bed3cfe 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -23,9 +23,12 @@ dist_man_MANS=\
eclat-delete-tags.1\
eclat-describe-addresses.1\
eclat-describe-instance-attribute.1\
+ eclat-describe-instance-status.1\
eclat-describe-instances.1\
+ eclat-describe-security-groups.1\
eclat-describe-snapshots.1\
eclat-describe-tags.1\
+ eclat-describe-volumes.1\
eclat-disassociate-address.1\
eclat-get-console-output.1\
eclat-start-instances.1\
diff --git a/doc/eclat-describe-instance-status.1 b/doc/eclat-describe-instance-status.1
new file mode 100644
index 0000000..0370432
--- /dev/null
+++ b/doc/eclat-describe-instance-status.1
@@ -0,0 +1,182 @@
+.\" This file is part of Eclat -*- nroff -*-
+.\" 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 DESCRIBE\-INSTANCE\-STATUS 1 "October 17, 2012" "ECLAT" "Eclat User Reference"
+.SH NAME
+eclat describe\-instance\-status \- describe status of EC2 instances
+.SH SYNOPSIS
+eclat describe\-instance\-status [\fB\-a\fR] [\fB\-\-all\fR] [\fBFILTER\fR...]
+
+eclat describe\-instance\-status \fB\-\-help\fR
+.SH DESCRIPTION
+Describes the status of selected EC2 instances including any scheduled
+events. This information includes:
+.nr step 1 1
+.IP \n[step].
+.B Instance state
+
+This describes the current state of the instance: \fBrunning\fR,
+\fBstopped\fR, etc.
+.IP \n+[step].
+.B System status
+
+The system status refers to the functionality depending on the systems
+that support the instance, such as the underlying hardware, network
+devices, etc.
+.IP \n+[step].
+.B Instance status
+
+The instance status describes those aspects of the functionality that
+depend on the instance itself (e.g. on its operating system, the
+services it runs, etc.)
+.SH OPTIONS
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+Return the status for all instances. By default, only running
+instances are described.
+.SH FILTERS
+The following filters are defined:
+.TP
+\fBavailability\-zone\fR=\fIstring\fR
+The Availability Zone of the instance.
+.TP
+\fBevent.code\fR=\fIvalue\fR
+The code identifying the type of event. Valid \fIvalue\fRs are:
+.BR instance\-reboot ,
+.BR system\-reboot ,
+.BR system\-maintenance ,
+.BR instance\-retirement .
+.TP
+\fBevent.description\fR=\fIstring\fR
+A description of the event.
+.TP
+\fBevent.not\-after\fR=\fIdate\fR
+The latest end time for the scheduled event.
+.TP
+\fBevent.not\-before\fR=\fIdate\fR
+The earliest start time for the scheduled event.
+.TP
+\fBinstance\-state\-name\fR=\fIvalue\fR
+The state of the instance. The valid \fIvalue\fRs are:
+.BR pending ,
+.BR running ,
+.BR shutting\-down ,
+.BR terminated ,
+.BR stopping ,
+.BR stopped .
+
+Note that unless \fIvalue\fR is \fBrunning\fR you have to use the
+\fB\-a\fR (\fB\-\-all\fR) option for this filter to take effect.
+.TP
+\fBinstance\-state\-code\fR=\fIcode\fR
+A code representing the state of the instance.
+Valid values are:
+.RS
+.TP
+.B 0
+pending
+.TP
+.B 16
+running
+.TP
+.B 32
+shutting\-down
+.TP
+.B 48
+terminated
+.TP
+.B 64
+stopping
+.TP
+.B 80
+stopped
+.RE
+.sp
+Note that unless \fIcode\fR is \fB0\fR you have to use the
+\fB\-a\fR (\fB\-\-all\fR) option for this filter to take effect.
+.TP
+\fBsystem\-status.status\fR=\fIvalue\fR
+The system status of the instance. Valid values are:
+.BR ok ,
+.BR impaired ,
+.BR initializing ,
+.BR insufficient\-data ,
+.BR not\-applicable .
+.TP
+\fBsystem\-status.reachability\fR=\fIstring\fR
+System reachability status, one of:
+.BR passed ,
+.BR failed ,
+.BR initializing ,
+.BR insufficient\-data .
+.TP
+\fBinstance\-status.status\fR=\fIstring\fR
+The status of the instance. One of:
+.BR ok ,
+.BR impaired ,
+.BR initializing ,
+.BR insufficient\-data ,
+.BR not\-applicable .
+.TP
+\fBinstance\-status.reachability\fR=\fIstring\fR
+The instance reachability status. One of:
+.BR passed ,
+.BR failed ,
+.BR initializing ,
+.BR insufficient\-data .
+.SH OUTPUT
+Each instance is described on a separate line. The fields are
+separated by single \fBTAB\fR characters. The fields displayed are
+(from left to right): instance ID, region, and instance state. If the
+instance is running, system and instance status are also displayed.
+If any events are reported, they are output on the standard error.
+.SH EXAMPLE
+In the example below the long lines are split for readability:
+.sp
+.nf
+.in +2
+$ eclat describe\-instance\-status \-a
+i\-283f9f47 us\-east\-1d running impaired\
+ Sys.reachability=failed Inst.reachability=failed
+i\-283f9f47 Event: "The instance is running on degraded hardware"
+i\-d2e36dbd us\-east\-1d running ok\
+ Sys.reachability=passed Inst.reachability=passed
+.in
+.fi
+.SH "SEE ALSO"
+.BR eclat (1),
+.BR eclat\-describe\-instances (1),
+.BR eclat\-describe\-instance\-attribute (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-describe-security-groups.1 b/doc/eclat-describe-security-groups.1
new file mode 100644
index 0000000..36632a3
--- /dev/null
+++ b/doc/eclat-describe-security-groups.1
@@ -0,0 +1,134 @@
+.\" This file is part of Eclat -*- nroff -*-
+.\" 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 DESCRIBE\-SECURITY\-GROUPS 1 "October 18, 2012" "ECLAT" "Eclat User Reference"
+.SH NAME
+eclat describe\-security\-groups \- return information about security groups
+.SH SYNOPSIS
+eclat describe\-security\-groups [\fB\-n\fR] [\fB\-\-name\fR]\
+ [\fBFILTER\fR...] [\fBID\fR]
+
+eclat describe\-security\-groups \fB\-\-help\fR
+.SH DESCRIPTION
+This command returns information about security groups. By default,
+all security groups pertaining to your account will be described.
+Particular groups can be selected by specifying their IDs (or names,
+if the \fB\-n\fR (\fB\-\-name\fR) option is used) in the command
+line. The set of groups can further be abridged by using filters.
+.PP
+If ID mapping is enabled (see the section \fBMAPS\fR
+in
+.BR eclat (1)),
+this command translates \fBID\fR supplied in the command line
+using the \fBGroupId\fR map or \fBGroupName\fR map, if the \fB\-n\fR
+(\fB\-\-name\fR) option is used.
+.SH OPTIONS
+.TP
+\fB\-n\fR, \fB\-\-name\fR
+Treat group identifiers supplied in the command line as group names.
+By default they are treated as group IDs.
+.SH FILTERS
+.TP
+\fBdescription\fR=\fIstring\fR
+The description of the security group.
+.TP
+\fBgroup\-id\fR=\fIstring\fR
+The ID of the security group.
+.TP
+\fBgroup\-name\fR=\fIstring\fR
+The name of the security group.
+.TP
+\fBip\-permission.cidr\fR=\fBstring\fR
+The CIDR range that has been granted the permission. See the note below.
+.TP
+\fBip\-permission.from\-port\fR=\fIstring\fR
+For the TCP and UDP, the start of port range, for ICMP -- the ICMP type
+number.
+.TP
+\fBip\-permission.group\-name\fR=\fIstring\fR
+The name of security group that has been granted the permission.
+.TP
+\fBip\-permission.protocol\fR=\fIvalue\fB
+The IP protocol for the permission. One of:
+.BR tcp ,
+.BR udp ,
+.BR icmp ,
+or a protocol number.
+.TP
+\fBip\-permission.to\-port\fR=\fIstring\fR
+The end of port range for the TCP and UDP protocols, or an ICMP code.
+.TP
+\fBip\-permission.user\-id\fR=\fIstring\fR
+The ID of an AWS account that has been granted the permission.
+.TP
+\fBowner\-id\fR=\fIstring\fR
+The AWS account ID of the owner of the security group.
+.TP
+\fBtag\-key\fR=\fIstring\fR
+The key of a tag assigned to the security group.
+.TP
+\fBtag\-value\fR=\fIstring\fR
+The value of a tag assigned to the security group.
+.PP
+Notice, that all filters use literal matching only. This means that
+you cannot use, e.g., \fBip\-permission.cidr\fR to check for a
+particular IP address. Instead, the argument to
+\fBip\-permission.cidr\fR must be the CIDR exactly as stored in the
+group description. The same holds true for other filters as well.
+.SH OUTPUT
+The output is multi-line. Each group begins with a \fBGroup\fR line,
+containing the group ID, name and description. Following lines
+describe the VPC ID and tags (if any). Tags are listed in as
+\fBkey\fB=\fBvalue\fR pairs, each on a separate line and indented by
+one tabstop. The lines that follow list the rules for incoming and
+outgoing traffic. E.g.:
+.sp
+.nf
+.in +2
+Group sg\-443d0a12 WebServers "Web Servers"
+VPC ID:
+Incoming:
+tcp 0.0.0.0/0 80
+Outgoing:
+Group sg\-5ff8a023 RangedPortsBySource "Group A"
+VPC ID:
+Incoming:
+user 111122223333, group sg\-99gh4012 ("Group B") 6000\-7000
+Outgoing:
+.in
+.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-describe-volumes.1 b/doc/eclat-describe-volumes.1
new file mode 100644
index 0000000..89e8dc1
--- /dev/null
+++ b/doc/eclat-describe-volumes.1
@@ -0,0 +1,149 @@
+.\" This file is part of Eclat -*- nroff -*-
+.\" 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 DESCRIBE\-VOLUMES 1 "October 18, 2012" "ECLAT" "Eclat User Reference"
+.SH NAME
+eclat describe\-volumes \- list EBS volumes
+.SH SYNOPSIS
+eclat describe\-volumes [\fBFILTER\fR...] [\fBID\fR...]
+
+eclat describe\-volumes \fB\-\-help\fR
+.SH DESCRIPTION
+This command displays the EBS volumes in your account. By default,
+all volumes are shown. To select particular volumes, give their IDs
+in the command line.
+.PP
+If ID mapping is enabled (see the section \fBMAPS\fR
+in
+.BR eclat (1)),
+this command treats the IDs as volume names and translates them to the
+AWS IDs using the \fBVolumeId\fR map.
+.SH FILTERS
+Filters allow you to select only volumes matching particular
+criteria. The following filters are defined:
+.TP
+\fBattachment.attach\-time\fR=\fIdate\fR
+The time stamp when the attachment initiated.
+.TP
+\fBattachment.delete\-on\-termination\fR=\fIboolean\fR
+Whether the volume is deleted on instance termination.
+.TP
+\fBattachment.device\fR=\fBstring\fR
+The device name that is exposed to the instance (for example, /dev/sda1).
+.TP
+\fBattachment.instance\-id\fR=\fIstring\fR
+.TP
+\fBattachment.status\fR=\fIvalue\fR
+The attachment state. Valid \fIvalue\fRs are:
+.BR attaching ,
+.BR attached ,
+.BR detaching ,
+.BR detached .
+.TP
+\fBavailability\-zone\fR=\fIstring\fR
+The availability zone in which the volume was created.
+.TP
+\fBcreate\-time\fR=\fIdate\fR
+.TP
+\fBsize\fR=\fIinteger\fB
+The size of the volume, in GiB.
+.TP
+\fBsnapshot\-id\fR=\fIstring\fR
+The snapshot from which the volume was created.
+.TP
+\fBstatus\fR=\fIvalue\fR
+The status of the volume. Allowed \fIvalue\fR is one of:
+.BR creating ,
+.BR available ,
+.BR in\-use ,
+.BR deleting ,
+.BR deleted ,
+.BR error .
+.TP
+\fBtag\-key\fR=\fIstring\fR
+The key of a tag assigned to the resource, regardless of its value. Note,
+that this filter works independently of the \fBtag\-value\fR filter, i.e.
+\fBtag\-key=foo tag\-value=bar\fR will return all snapshots that have the tag
+\fBfoo\fR defined and all snapshots that have \fBbar\fR as a value of any
+of their tags. To request a snapshot that has the tag \fBfoo\fR set to the
+value \fBbar\fR see the \fBtag\fR:\fIKEY\fR filter below.
+.TP
+\fBtag\-value\fR=\fIstring\fR
+The value of a tag assigned to the resource, regardless of the tag's key.
+See the comment above.
+.TP
+\fBtag\fR:\fIKEY\fR=\fIVAL\fR
+Selects the snapshots having the specified tag \fIKEY\fR set to the value
+\fIVAL\fR. For example:
+.sp
+.nf
+.in +2
+tag:Name="root partition"
+.in
+.fi
+.TP
+\fBvolume\-id\fR=\fIID\fR
+The volume ID. This filter has the same effect as specifying \fIID\fR
+as the command line argument. It is needed mostly when you use ID
+mapping but wish to identify some modules by their IDs and another by
+their symbolic name, e.g.:
+.sp
+.nf
+.in +2
+eclat \-x describe\-volumes root volume\-id=vol\-1aeb5008 srv
+.in
+.fi
+.TP
+\fBvolume\-type\fR=\fIvalue\fR
+The Amazon EBS volume type. Valid values are
+.B standard
+and
+.BR io1 .
+.SH OUTPUT
+Each volume is listed on a separate line. Output fields are separated
+by horizontal tab characters. The fields are: the volume ID, its size
+in GiB, and status. Following this, volume attachments are
+described. Each attachment consists of four fields: the volume ID,
+the ID of the instance it is attached to, the device name it is known
+as, and the attachment status. For example:
+.sp
+.nf
+.in +2
+vol\-4282672b 80 in\-use vol\-4282672b i\-6058a509 /dev/sdh attached
+.in
+.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/src/dscrsecgrps-cl.opt b/src/dscrsecgrps-cl.opt
index 67f953c..e242301 100644
--- a/src/dscrsecgrps-cl.opt
+++ b/src/dscrsecgrps-cl.opt
@@ -16,7 +16,7 @@
OPTIONS_BEGIN("eclat describe-security-groups",
[<returns information about security groups>],
- [<[FILTER...]>],
+ [<[FILTER...] [ID...]>],
[<gnu>],
[<nousage>],
[<noversion>])
diff --git a/src/dscrvols.c b/src/dscrvols.c
index f7d8087..e54c506 100644
--- a/src/dscrvols.c
+++ b/src/dscrvols.c
@@ -51,12 +51,15 @@ eclat_describe_volumes(CURL *curl, int argc, char **argv)
available_filters = filters;
generic_proginfo->print_help_hook = list_filters;
+ generic_proginfo->args_doc = "[FILTER...] [ID...]";
generic_parse_options("eclat describe-volumes",
"describe Amazon EBS volumes",
argc, argv, &i);
argv += i;
argc -= i;
+ translate_ids(argc, argv, "VolumeId");
- q = describe_query_create(curl, "DescribeVolumes", argc, argv, NULL);
+ q = describe_query_create(curl, "DescribeVolumes", argc, argv,
+ "VolumeId");
return eclat_send_query(curl, q);
}

Return to:

Send suggestions and report system problems to the System administrator.