Formatting cleanups, doc updates and whatnot

Change-Id: Ica8298353be22f947c8e8a03d8dc29ded9cb26dd

HACKING.rst

@@ -7,8 +7,8 @@ General
 
 DevStack is written in POSIX shell script.  This choice was made because
 it best illustrates the configuration steps that this implementation takes
-on setting up and interacting with OpenStack components.  DevStack specifies
+on setting up and interacting with OpenStack components.  DevStack specifically
-BASH and is compatible with Bash 3.
+uses Bash and is compatible with Bash 3.
 
 DevStack's official repository is located on GitHub at
 https://github.com/openstack-dev/devstack.git.  Besides the master branch that
@@ -30,9 +30,17 @@ work for DevStack's use cases.  There is a subscript ``functions`` that contains
 generally useful shell functions and is used by a number of the scripts in
 DevStack.
 
+The ``lib`` directory contains sub-scripts for projects or packages that ``stack.sh``
+sources to perform much of the work related to those projects.  These sub-scripts
+contain configuration defaults and functions to configure, start and stop the project
+or package.  These variables and functions are also used by related projects,
+such as Grenade, to manage a DevStack installation.
+
 A number of additional scripts can be found in the ``tools`` directory that may
-be useful in setting up special-case uses of DevStack. These include: bare metal
+be useful in supporting DevStack installations.  Of particular note are ``info.sh``
-deployment, ramdisk deployment and Jenkins integration.
+to collect and report information about the installed system, and ``instal_prereqs.sh``
+that handles installation of the prerequisite packages for DevStack.  It is
+suitable, for example, to pre-load a system for making a snapshot.
 
 
 Scripts
@@ -63,8 +71,8 @@ configuration of the user environment::
     source $TOP_DIR/openrc
 
 ``stack.sh`` is a rather large monolithic script that flows through from beginning
-to end.  The process of breaking it down into project-level sub-scripts is nearly
+to end.  It has been broken down into project-specific subscripts (as noted above)
-complete and should make ``stack.sh`` easier to read and manage.
+located in ``lib`` to make ``stack.sh`` more manageable and to promote code reuse.
 
 These library sub-scripts have a number of fixed entry points, some of which may
 just be stubs.  These entry points will be called by ``stack.sh`` in the
@@ -112,6 +120,7 @@ Also, variable declarations in ``stackrc`` do NOT allow overriding (the form
 ``FOO=${FOO:-baz}``); if they did then they can already be changed in ``localrc``
 and can stay in the project file.
 
+
 Documentation
 -------------
 

README.md

@@ -120,14 +120,16 @@ In order to enable Quantum a single node setup, you'll need the following settin
     # Optional, to enable tempest configuration as part of devstack
     enable_service tempest
 
-Then run stack.sh as normal.
+Then run `stack.sh` as normal.
+
+# Tempest
 
 If tempest has been successfully configured, a basic set of smoke tests can be run as follows:
 
     $ cd /opt/stack/tempest
     $ nosetests tempest/tests/network/test_network_basic_ops.py
 
-Multi-Node Setup
+# Multi-Node Setup
 
 A more interesting setup involves running multiple compute nodes, with Quantum networks connecting VMs on different compute nodes.
 You should run at least one "controller node", which should have a `stackrc` that includes at least:

exercise.sh

@@ -23,7 +23,7 @@ basenames=${RUN_EXERCISES:-""}
 
 EXERCISE_DIR=$TOP_DIR/exercises
 
-if [ -z "${basenames}" ] ; then
+if [[ -z "${basenames}" ]]; then
     # Locate the scripts we should run
     basenames=$(for b in `ls $EXERCISE_DIR/*.sh`; do basename $b .sh; done)
 else
@@ -69,6 +69,6 @@ for script in $failures; do
 done
 echo "====================================================================="
 
-if [ -n "$failures" ] ; then
+if [[ -n "$failures" ]]; then
     exit 1
 fi

exercises/client-args.sh

@@ -152,8 +152,9 @@ fi
 
 set +o xtrace
 
+
 # Results
-# -------
+# =======
 
 function report() {
     if [[ -n "$2" ]]; then

exercises/client-env.sh

@@ -161,8 +161,9 @@ fi
 
 set +o xtrace
 
+
 # Results
-# -------
+# =======
 
 function report() {
     if [[ -n "$2" ]]; then

lib/baremetal

@@ -53,6 +53,7 @@
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
 # Sub-driver settings
 # -------------------
 

lib/ceilometer

@@ -37,12 +37,16 @@ CEILOMETER_API_LOG_DIR=/var/log/ceilometer-api
 CEILOMETER_AUTH_CACHE_DIR=${CEILOMETER_AUTH_CACHE_DIR:-/var/cache/ceilometer}
 
 # Support potential entry-points console scripts
-if [ -d $CEILOMETER_DIR/bin ] ; then
+if [[ -d $CEILOMETER_DIR/bin ]]; then
     CEILOMETER_BIN_DIR=$CEILOMETER_DIR/bin
 else
     CEILOMETER_BIN_DIR=$(get_python_exec_prefix)
 fi
 
+
+# Functions
+# ---------
+
 # cleanup_ceilometer() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up
 function cleanup_ceilometer() {
@@ -135,6 +139,7 @@ function stop_ceilometer() {
     done
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/cinder

@@ -64,6 +64,10 @@ VOLUME_GROUP=${VOLUME_GROUP:-stack-volumes}
 VOLUME_GROUP2=${VOLUME_GROUP2:-stack-volumes2}
 VOLUME_NAME_PREFIX=${VOLUME_NAME_PREFIX:-volume-}
 
+
+# Functions
+# ---------
+
 # _clean_volume_group removes all cinder volumes from the specified volume group
 # _clean_volume_group $VOLUME_GROUP $VOLUME_NAME_PREFIX
 function _clean_volume_group() {
@@ -432,6 +436,7 @@ function stop_cinder() {
     fi
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/database

@@ -20,14 +20,18 @@
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
 # Register a database backend
 #  $1 The name of the database backend
+# This is required to be defined before the specific database scripts are sourced
 function register_database {
     [ -z "$DATABASE_BACKENDS" ] && DATABASE_BACKENDS=$1 || DATABASE_BACKENDS+=" $1"
 }
 
 # Sourcing the database libs sets DATABASE_BACKENDS with the available list
-for f in $TOP_DIR/lib/databases/*; do source $f; done
+for f in $TOP_DIR/lib/databases/*; do
+    source $f;
+done
 
 # ``DATABASE_BACKENDS`` now contains a list of the supported databases
 # Look in ``ENABLED_SERVICES`` to see if one has been selected
@@ -42,6 +46,9 @@ done
 # This is not an error as multi-node installs will do this on the compute nodes
 
 
+# Functions
+# ---------
+
 # Get rid of everything enough to cleanly change database backends
 function cleanup_database {
     cleanup_database_$DATABASE_TYPE
@@ -112,6 +119,7 @@ function database_connection_url {
     database_connection_url_$DATABASE_TYPE $var $db
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/databases/mysql

@@ -8,8 +8,13 @@
 MY_XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
 register_database mysql
 
+
+# Functions
+# ---------
+
 # Get rid of everything enough to cleanly change database backends
 function cleanup_database_mysql {
     if is_ubuntu; then
@@ -137,6 +142,7 @@ function database_connection_url_mysql {
     echo "$BASE_SQL_CONN/$db?charset=utf8"
 }
 
+
 # Restore xtrace
 $MY_XTRACE
 

lib/databases/postgresql

@@ -8,8 +8,13 @@
 PG_XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
 register_database postgresql
 
+
+# Functions
+# ---------
+
 # Get rid of everything enough to cleanly change database backends
 function cleanup_database_postgresql {
     stop_service postgresql
@@ -88,6 +93,7 @@ function database_connection_url_postgresql {
     echo "$BASE_SQL_CONN/$db?client_encoding=utf8"
 }
 
+
 # Restore xtrace
 $PG_XTRACE
 

lib/glance

@@ -51,8 +51,8 @@ fi
 GLANCE_HOSTPORT=${GLANCE_HOSTPORT:-$SERVICE_HOST:9292}
 
 
-# Entry Points
+# Functions
-# ------------
+# ---------
 
 # cleanup_glance() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up
@@ -199,6 +199,7 @@ function stop_glance() {
     screen -S $SCREEN_NAME -p g-reg -X kill
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/heat

@@ -25,9 +25,14 @@ set +o xtrace
 
 # Defaults
 # --------
+
+# set up default directories
 HEAT_DIR=$DEST/heat
 HEATCLIENT_DIR=$DEST/python-heatclient
-# set up default directories
+
+
+# Functions
+# ---------
 
 # cleanup_heat() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up
@@ -182,6 +187,7 @@ function stop_heat() {
     done
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/horizon

@@ -38,6 +38,10 @@ HORIZON_SETTINGS=${HORIZON_SETTINGS:-$HORIZON_DIR/openstack_dashboard/local/loca
 APACHE_USER=${APACHE_USER:-$USER}
 APACHE_GROUP=${APACHE_GROUP:-$(id -gn $APACHE_USER)}
 
+
+# Functions
+# ---------
+
 # utility method of setting python option
 function _horizon_config_set() {
     local file=$1

lib/keystone

@@ -63,8 +63,8 @@ KEYSTONE_SERVICE_PROTOCOL=${KEYSTONE_SERVICE_PROTOCOL:-$SERVICE_PROTOCOL}
 SERVICE_TENANT_NAME=${SERVICE_TENANT_NAME:-service}
 
 
-# Entry Points
+# Functions
-# ------------
+# ---------
 
 # cleanup_keystone() - Remove residual data files, anything left over from previous
 # runs that a clean run would need to clean up

lib/ldap

@@ -1,13 +1,17 @@
 # lib/ldap
 # Functions to control the installation and configuration of **ldap**
 
-# ``stack.sh`` calls the entry points in this order:
+# ``lib/keystone`` calls the entry points in this order:
-#
+# install_ldap()
 
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
+
+# Functions
+# ---------
+
 # install_ldap
 # install_ldap() - Collect source and prepare
 function install_ldap() {

lib/nova

@@ -122,8 +122,8 @@ TEST_FLOATING_POOL=${TEST_FLOATING_POOL:-test}
 TEST_FLOATING_RANGE=${TEST_FLOATING_RANGE:-192.168.253.0/29}
 
 
-# Entry Points
+# Functions
-# ------------
+# ---------
 
 function add_nova_opt {
     echo "$1" >>$NOVA_CONF
@@ -673,6 +673,7 @@ function stop_nova() {
     done
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/quantum

@@ -53,7 +53,6 @@
 #
 # With Quantum networking the NETWORK_MANAGER variable is ignored.
 
-
 # Save trace setting
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
@@ -172,6 +171,7 @@ if is_service_enabled quantum; then
     OVS_ENABLE_TUNNELING=${OVS_ENABLE_TUNNELING:-$ENABLE_TENANT_TUNNELS}
 fi
 
+
 # Quantum plugin specific functions
 # ---------------------------------
 # Please refer to lib/quantum_plugins/README.md for details.
@@ -189,8 +189,9 @@ else
     Q_USE_SECGROUP=False
 fi
 
-# Entry Points
+
-# ------------
+# Functions
+# ---------
 
 # configure_quantum()
 # Set common config for all quantum server and agents.

lib/rpc_backend

@@ -17,8 +17,9 @@
 XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
-# Entry Points
+
-# ------------
+# Functions
+# ---------
 
 # Make sure we only have one rpc backend enabled.
 # Also check the specified rpc backend is available on your platform.
@@ -157,6 +158,7 @@ function qpid_is_supported() {
     ( ! ([[ "$DISTRO" = "oneiric" ]] || is_suse) )
 }
 
+
 # Restore xtrace
 $XTRACE
 

lib/swift

@@ -84,8 +84,8 @@ CONTAINER_PORT_BASE=${CONTAINER_PORT_BASE:-6011}
 ACCOUNT_PORT_BASE=${ACCOUNT_PORT_BASE:-6012}
 
 
-# Entry Points
+# Functions
-# ------------
+# ---------
 
 # cleanup_swift() - Remove residual data files
 function cleanup_swift() {

lib/tempest

@@ -50,8 +50,9 @@ BUILD_TIMEOUT=400
 
 BOTO_MATERIALS_PATH="$FILES/images/s3-materials/cirros-0.3.1"
 
-# Entry Points
+
-# ------------
+# Functions
+# ---------
 
 # configure_tempest() - Set config files, create data dirs, etc
 function configure_tempest() {

lib/tls

@@ -21,6 +21,9 @@
 # start_tls_proxy HOST_IP 5000 localhost 5000
 
 
+# Defaults
+# --------
+
 if is_service_enabled tls-proxy; then
     # TODO(dtroyer): revisit this below after the search for HOST_IP has been done
     TLS_IP=${TLS_IP:-$SERVICE_IP}
@@ -317,6 +320,7 @@ function start_tls_proxy() {
     stud $STUD_PROTO -f $f_host,$f_port -b $b_host,$b_port $DEVSTACK_CERT 2>/dev/null
 }
 
+
 # Local variables:
 # mode: shell-script
 # End:

stack.sh

@@ -12,7 +12,7 @@
 # developer install.
 
 # To keep this script simple we assume you are running on a recent **Ubuntu**
-# (11.10 Oneiric or newer) or **Fedora** (F16 or newer) machine.  It
+# (12.04 Precise or newer) or **Fedora** (F16 or newer) machine.  It
 # should work in a VM or physical server.  Additionally we put the list of
 # ``apt`` and ``rpm`` dependencies and other configuration files in this repo.
 
@@ -51,8 +51,8 @@ GetDistro
 # be overwritten by a DevStack update.
 #
 # DevStack distributes ``stackrc`` which contains locations for the OpenStack
-# repositories and branches to configure.  ``stackrc`` sources ``localrc`` to
+# repositories, branches to configure, and other configuration defaults.
-# allow you to safely override those settings.
+# ``stackrc`` sources ``localrc`` to allow you to safely override those settings.
 
 if [[ ! -r $TOP_DIR/stackrc ]]; then
     log_error $LINENO "missing $TOP_DIR/stackrc - did you grab more than just stack.sh?"
@@ -78,6 +78,19 @@ if [[ -r $TOP_DIR/.stackenv ]]; then
     rm $TOP_DIR/.stackenv
 fi
 
+# ``stack.sh`` keeps the list of ``apt`` and ``rpm`` dependencies and config
+# templates and other useful files in the ``files`` subdirectory
+FILES=$TOP_DIR/files
+if [ ! -d $FILES ]; then
+    log_error $LINENO "missing devstack/files"
+fi
+
+# ``stack.sh`` keeps function libraries here
+# Make sure ``$TOP_DIR/lib`` directory is present
+if [ ! -d $TOP_DIR/lib ]; then
+    log_error $LINENO "missing devstack/lib"
+fi
+
 # Import common services (database, message queue) configuration
 source $TOP_DIR/lib/database
 source $TOP_DIR/lib/rpc_backend
@@ -100,21 +113,9 @@ fi
 # and the specified rpc backend is available on your platform.
 check_rpc_backend
 
-# ``stack.sh`` keeps function libraries here
-# Make sure ``$TOP_DIR/lib`` directory is present
-if [ ! -d $TOP_DIR/lib ]; then
-    log_error $LINENO "missing devstack/lib"
-fi
-
-# ``stack.sh`` keeps the list of ``apt`` and ``rpm`` dependencies and config
-# templates and other useful files in the ``files`` subdirectory
-FILES=$TOP_DIR/files
-if [ ! -d $FILES ]; then
-    log_error $LINENO "missing devstack/files"
-fi
-
 SCREEN_NAME=${SCREEN_NAME:-stack}
 # Check to see if we are already running DevStack
+# Note that this may fail if USE_SCREEN=False
 if type -p screen >/dev/null && screen -ls | egrep -q "[0-9].$SCREEN_NAME"; then
     echo "You are already running a stack.sh session."
     echo "To rejoin this session type 'screen -x stack'."
@@ -230,6 +231,8 @@ fi
 
 # Allow the use of an alternate hostname (such as localhost/127.0.0.1) for service endpoints.
 SERVICE_HOST=${SERVICE_HOST:-$HOST_IP}
+
+# Allow the use of an alternate protocol (such as https) for service endpoints
 SERVICE_PROTOCOL=${SERVICE_PROTOCOL:-http}
 
 # Configure services to use syslog instead of writing to individual log files
@@ -241,7 +244,6 @@ SYSLOG_PORT=${SYSLOG_PORT:-516}
 SYSSTAT_FILE=${SYSSTAT_FILE:-"sysstat.dat"}
 SYSSTAT_INTERVAL=${SYSSTAT_INTERVAL:-"1"}
 
-
 # Use color for logging output (only available if syslog is not used)
 LOG_COLOR=`trueorfalse True $LOG_COLOR`
 
@@ -267,7 +269,6 @@ source $TOP_DIR/lib/baremetal
 source $TOP_DIR/lib/ldap
 
 # Set the destination directories for OpenStack projects
-HORIZON_DIR=$DEST/horizon
 OPENSTACKCLIENT_DIR=$DEST/python-openstackclient
 
 
@@ -719,10 +720,10 @@ if [[ -e $SCREENRC ]]; then
     echo -n > $SCREENRC
 fi
 
-
 # Initialize the directory for service status check
 init_service_check
 
+
 # Kick off Sysstat
 # ------------------------
 # run sysstat if it is enabled, this has to be early as daemon
@@ -735,6 +736,7 @@ if is_service_enabled sysstat;then
     fi
 fi
 
+
 # Keystone
 # --------
 

stackrc

@@ -49,6 +49,7 @@ if [ -f $RC_DIR/localrc ]; then
     source $RC_DIR/localrc
 fi
 
+
 # Repositories
 # ------------
 
@@ -156,7 +157,6 @@ BM_IMAGE_BUILD_BRANCH=${BM_IMAGE_BUILD_BRANCH:-master}
 BM_POSEUR_REPO=${BM_POSEUR_REPO:-${GIT_BASE}/tripleo/bm_poseur.git}
 BM_POSEUR_BRANCH=${BM_POSEUR_BRANCH:-master}
 
-
 # Nova hypervisor configuration.  We default to libvirt with **kvm** but will
 # drop back to **qemu** if we are unable to load the kvm module.  ``stack.sh`` can
 # also install an **LXC** or **OpenVZ** based system.