diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2012-10-18 14:25:06 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2012-10-18 16:58:12 +0300 |
commit | 0e9392af1b684ce67230da5e2bfe4865ed69f055 (patch) | |
tree | 12d1b28cb21499ea47eaa5e166a179fbee3e0e98 | |
parent | a1591f2c2988826d5b4f476be125ffb2cd591b02 (diff) | |
download | eclat-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-- | TODO | 6 | ||||
-rw-r--r-- | doc/Makefile.am | 3 | ||||
-rw-r--r-- | doc/eclat-describe-instance-status.1 | 182 | ||||
-rw-r--r-- | doc/eclat-describe-security-groups.1 | 134 | ||||
-rw-r--r-- | doc/eclat-describe-volumes.1 | 149 | ||||
-rw-r--r-- | src/dscrsecgrps-cl.opt | 2 | ||||
-rw-r--r-- | src/dscrvols.c | 5 |
7 files changed, 476 insertions, 5 deletions
@@ -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); } |