heat cli : Manpage updates

The heat cli tool manpage had very little information,
this adds detail to the existing page and copies a version
of this page to cover the heat-boto version of the tool.

Change-Id: I5b64466878b719b49a9084f301b2c177ddef9a91
Signed-off-by: Steven Hardy <shardy@redhat.com>

diff --git a/docs/man/man1/heat-boto.1 b/docs/man/man1/heat-boto.1
new file mode 100644 (file)
index 0000000..851982b
--- /dev/null
+++ b/docs/man/man1/heat-boto.1
@@ -0,0 +1,198 @@
+'\" t
+.\"     Title: heat-boto
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: 03/31/2012
+.\"    Manual: System administration commands
+.\"    Source: Heat 0.0.1
+.\"  Language: English
+.\"
+.TH "HEAT" "1" "03/31/2012" "HEAT 0\&.0\&.1" "System administration commands"
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+heat-boto \- perform a heat action via the heat API
+.SH "SYNOPSIS"
+.sp
+heat-boto COMMAND [OPTIONS]
+.SH "DESCRIPTION"
+.sp
+\fBheat-boto\fR is a tool to orchestrate the setup of multiple cloud applications\&.
+
+\fBheat-boto\fR is port a of the \fBheat\fR tool to use the boto client library\&.
+
+.SH CONFIGURATION FILES
+
+heat-boto uses the boto client library, which looks for configuration in /etc/boto.cfg
+
+heat installs a default version of this file, but you will need to update the
+aws_access_key_id and aws_secret_access_key values with your real keystone credentials\&.
+
+Use keystone ec2-credentials-list to retrieve your keystone ec2 access keys\&.
+
+.SH "COMMANDS"
+
+.PP
+\fBcreate\fP
+.RS 4
+Create stack as defined in template file
+.RE
+.PP
+\fBdelete\fP
+.RS 4
+Delete specified stack
+.RE
+.PP
+\fBdescribe\fP
+.RS 4
+Provide detailed information about the specified stack, or if no arguments are given all stacks
+.RE
+.PP
+\fBestimate-template-cost\fP
+.RS 4
+Currently not implemented
+.RE
+.PP
+\fBevent-list\fP
+.RS 4
+List events related to specified stacks, or if no arguments are given all stacks
+.RE
+.PP
+\fBgettemplate\fP
+.RS 4
+Get the template for a running stack
+.RE
+.PP
+\fBhelp\fP
+.RS 4
+Provide help/usage information
+.RE
+.PP
+\fBlist\fP
+.RS 4
+List summary information for all stacks
+.RE
+.PP
+\fBresource\fP
+.RS 4
+List information about a specific resource
+.RE
+.PP
+\fBresource-list\fP
+.RS 4
+List all resources for a specified stack
+.RE
+.PP
+\fBresource-list-details\fP
+.RS 4
+List details of all resources for a specified stack or physical resource ID, optionally filtered by a logical resource ID
+.RE
+.PP
+\fBupdate\fP
+.RS 4
+Update a running stack with a modified template or template parameters - currently not implemented
+.RE
+.PP
+\fBvalidate\fP
+.RS 4
+Validate a template file syntax
+.RE
+
+.SH "OPTIONS"
+.PP
+\fB\-d\fR, \fB\-\-debug\fR
+.RS 4
+Enable verbose debug level output
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host\fR
+.RS 4
+Specify the hostname running the heat API service
+.RE
+.PP
+\fB\-k\fR, \fB\-\-insecure\fR
+.RS 4
+Use plain HTTP instead of HTTPS
+.RE
+.PP
+\fB\-P\fR, \fB\-\-parameters\fR
+.RS 4
+Stack input parameters
+.RE
+.PP
+\fB\-p\fR, \fB\-\-port\fR
+.RS 4
+Specify the port to connect to for the heat API service
+.RE
+.PP
+\fB\-R\fR, \fB\-\-region\fR
+.RS 4
+Region name. When using keystone authentication "version 2.0 or later this identifies the region
+.RE
+.PP
+\fB\-f\fR, \fB\-\-template\fR-file
+.RS 4
+Path to file containing the stack template
+.RE
+.PP
+\fB\-u\fR, \fB\-\-template\fR-url
+.RS 4
+URL to stack template
+.RE
+.PP
+\fB\-t\fR, \fB\-\-timeout\fR
+.RS 4
+Stack creation timeout (default is 60 minutes)
+.RE
+.PP
+\fB\-v\fR, \fB\-\-verbose\fR
+.RS 4
+Enable verbose output
+.RE
+.PP
+\fB\-y\fR, \fB\-\-yes\fR
+.RS 4
+Do not prompt for confirmation, assume yes
+.RE
+
+
+.PP
+.SH "USAGE EXAMPLES"
+.sp
+
+heat-boto -d create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
+
+heat-boto list
+
+heat-boto describe wordpress
+
+heat-boto resource-list wordpress
+
+heat-boto resource-list-details wordpress
+
+heat-boto resource-list-details wordpress WikiDatabase
+
+heat-boto resource wordpress WikiDatabase
+
+heat-boto event-list
+
+heat-boto delete wordpress
+
+.SH "AUTHOR"
+.sp
+See the AUTHORS file for a complete list of contributors\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2012, Red Hat Inc
+.sp
+Heat is released under the terms of the ASL 2 License\&.
+.sp
+Extensive documentation as well as IRC and mailing list info is available on the heat home page: https://heat\&-api\&.org/

diff --git a/docs/man/man1/heat.1 b/docs/man/man1/heat.1
index 727b428fcb398b0f90bef36cd68c165f952b9a42..d143a6941589316d2ec3299efcf25249a38748d5 100644 (file)
--- a/docs/man/man1/heat.1
+++ b/docs/man/man1/heat.1
@@ -1,5 +1,5 @@
 '\" t
-.\"     Title: heat 
+.\"     Title: heat
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 .\"      Date: 03/31/2012
@@ -19,29 +19,218 @@
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
 .SH "NAME"
-heat \- run a command somewhere else
+heat \- perform a heat action via the heat API
 .SH "SYNOPSIS"
 .sp
-heat <command>
+heat COMMAND [OPTIONS]
 .SH "DESCRIPTION"
 .sp
-\fBHeat\fR is a tool to orchestrate the setup of multiple cloud applications\&.
-.SH "ARGUMENTS"
+\fBheat\fR is a tool to orchestrate the setup of multiple cloud applications\&.
+
+.SH CONFIGURATION
+
+heat uses keystone authentication, and expects some variables to be set in
+your environment, without these heat will not be able to establish an
+authenticated connection with the heat API server.
+
+Example:
+.br
+export ADMIN_TOKEN=<keystone admin token>
+.br
+export OS_USERNAME=admin
+.br
+export OS_PASSWORD=verybadpass
+.br
+export OS_TENANT_NAME=admin
+.br
+export OS_AUTH_URL=http://127.0.0.1:5000/v2.0/
+.br
+export OS_AUTH_STRATEGY=keystone
+.br
+
+.SH "COMMANDS"
+
 .PP
-\fBcommand\fR
+\fBcreate\fP
 .RS 4
-heat command\&.
+Create stack as defined in template file
 .RE
+.PP
+\fBdelete\fP
+.RS 4
+Delete specified stack
+.RE
+.PP
+\fBdescribe\fP
+.RS 4
+Provide detailed information about the specified stack, or if no arguments are given all stacks
+.RE
+.PP
+\fBestimate-template-cost\fP
+.RS 4
+Currently not implemented
+.RE
+.PP
+\fBevent-list\fP
+.RS 4
+List events related to specified stacks, or if no arguments are given all stacks
+.RE
+.PP
+\fBgettemplate\fP
+.RS 4
+Get the template for a running stack
+.RE
+.PP
+\fBhelp\fP
+.RS 4
+Provide help/usage information
+.RE
+.PP
+\fBlist\fP
+.RS 4
+List summary information for all stacks
+.RE
+.PP
+\fBresource\fP
+.RS 4
+List information about a specific resource
+.RE
+.PP
+\fBresource-list\fP
+.RS 4
+List all resources for a specified stack
+.RE
+.PP
+\fBresource-list-details\fP
+.RS 4
+List details of all resources for a specified stack or physical resource ID, optionally filtered by a logical resource ID
+.RE
+.PP
+\fBupdate\fP
+.RS 4
+Update a running stack with a modified template or template parameters - currently not implemented
+.RE
+.PP
+\fBvalidate\fP
+.RS 4
+Validate a template file syntax
+.RE
+
 .SH "OPTIONS"
 .PP
-\fB\-f\fR, \fB\-\-template\fR
+\fB\-S\fR, \fB\-\-auth_strategy\fR
+.RS 4
+Authentication strategy
+.RE
+.PP
+\fB\-A\fR, \fB\-\-auth_token\fR
+.RS 4
+Authentication token to use to identify the client to the heat server
+.RE
+.PP
+\fB\-N\fR, \fB\-\-auth_url\fR
+.RS 4
+Authentication URL for keystone authentication
+.RE
+.PP
+\fB\-d\fR, \fB\-\-debug\fR
+.RS 4
+Enable verbose debug level output
+.RE
+.PP
+\fB\-H\fR, \fB\-\-host\fR
+.RS 4
+Specify the hostname running the heat API service
+.RE
+.PP
+\fB\-k\fR, \fB\-\-insecure\fR
+.RS 4
+Use plain HTTP instead of HTTPS
+.RE
+.PP
+\fB\-P\fR, \fB\-\-parameters\fR
+.RS 4
+Stack input parameters
+.RE
+.PP
+\fB\-K\fR, \fB\-\-password\fR
+.RS 4
+Password used to acquire an authentication token
+.RE
+.PP
+\fB\-p\fR, \fB\-\-port\fR
+.RS 4
+Specify the port to connect to for the heat API service
+.RE
+.PP
+\fB\-R\fR, \fB\-\-region\fR
+.RS 4
+Region name. When using keystone authentication "version 2.0 or later this identifies the region
+.RE
+.PP
+\fB\-f\fR, \fB\-\-template\fR-file
+.RS 4
+Path to file containing the stack template
+.RE
+.PP
+\fB\-u\fR, \fB\-\-template\fR-url
+.RS 4
+URL to stack template
+.RE
+.PP
+\fB\-T\fR, \fB\-\-tenant\fR
+.RS 4
+Tenant name used for Keystone authentication
+.RE
+.PP
+\fB\-t\fR, \fB\-\-timeout\fR
+.RS 4
+Stack creation timeout (default is 60 minutes)
+.RE
+.PP
+\fB\-U\fR, \fB\-\-url\fR
+.RS 4
+URL of heat service
+.RE
+.PP
+\fB\-I\fR, \fB\-\-username\fR
+.RS 4
+User name used to acquire an authentication token
+.RE
+.PP
+\fB\-v\fR, \fB\-\-verbose\fR
+.RS 4
+Enable verbose output
+.RE
+.PP
+\fB\-y\fR, \fB\-\-yes\fR
 .RS 4
-The template to use set up a stack\&.
+Do not prompt for confirmation, assume yes
 .RE
+
+
 .PP
-.SH "INVENTORY"
+.SH "USAGE EXAMPLES"
 .sp
-Heat orchestrates the setup of multiple cloud applications\&.
+
+heat -d create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
+
+heat list
+
+heat describe wordpress
+
+heat resource-list wordpress
+
+heat resource-list-details wordpress
+
+heat resource-list-details wordpress WikiDatabase
+
+heat resource wordpress WikiDatabase
+
+heat event-list
+
+heat delete wordpress
+
 .SH "AUTHOR"
 .sp
 See the AUTHORS file for a complete list of contributors\&.