Jenkins checking in autogenerated rST files

autogenerated_rst_docs/Automatic_Clustering_Config_Sharing.rst

@@ -19,16 +19,20 @@ decentralized data store, a ``clearwater-cluster-manager`` service to
 handle automatic clustering, and a ``clearwater-config-manager`` to
 handle configuration sharing.
 
-Is my Deployment Using Automatic Clustering and Configuration Sharing?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Etcd masters and proxies
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-To tell if your deployment is using this feature, log onto one of the
-nodes in your deployment and run ``dpkg --list | grep clearwater-etcd``.
-If this does not give any output the feature is not in use.
+Clearwater nodes can run either as an etcd master or an etcd proxy. When
+deploying a node, you can chose whether it acts as a master or proxy by
+filling in either the ``etcd_cluster`` or ``etcd_proxy`` config option
+in ``/etc/clearwater/local_config`` (see the `configuration options
+reference <Clearwater_Configuration_Options_Reference.html>`__ for more
+details).
 
-Migrating to Automatic Clustering and Configuration Sharing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There are some restrictions on which nodes can be masters or proxies: \*
+There must always be at least 3 etcd masters in the cluster \* The first
+node to be deployed in a site must be an etcd master
 
-Deployments that are not using the feature may be migrated so they start
-using it. To perform this migration, follow these
-`instructions <Migrating_To_etcd.html>`__.
+The `automated <Automated_Install.html>`__ and
+`manual <Manual_Install.html>`__ install instructions will both create a
+deployment with all nodes running as etcd masters.

autogenerated_rst_docs/Backups.rst

@@ -1,10 +1,10 @@
 Backups
 =======
 
-Within a Clearwater deployment, Ellis, Homestead, Homer and Memento all
-store persistent data (Bono and Sprout do not). To prevent data loss in
-disaster scenarios, Ellis, Homestead, Homer and Memento all have data
-backup and restore mechanisms. Specifically, all support
+Within a Clearwater deployment, Ellis and Vellum store persistent data
+(Bono, Sprout, Homer and Dime do not). To prevent data loss in disaster
+scenarios, Ellis and Vellum have data backup and restore mechanisms.
+Specifically, they support
 
 -  manual backup
 -  periodic automated local backup
@@ -17,16 +17,22 @@ This document describes
 -  the periodic automated local backup behavior
 -  how to restore from a backup.
 
-Note that if your Clearwater deployment is `integrated with an external
-HSS <External_HSS_Integration.html>`__, the HSS is the master of Ellis and
-Homestead's data, and those nodes do not need to be backed up. However,
-Homer's data still needs to be backed up.
+Note that Vellum has 4 databases: \* ``homestead_provisioning`` and
+``homestead_cache`` for Homestead's data \* ``homer`` for Homer's data
+\* ``memento`` for Memento's data (if using the Memento AS)
+
+Depending on your deployment scenario, you may not need to back up all
+of the data of Ellis and Vellum: \* If your Clearwater deployment is
+`integrated with an external HSS <External_HSS_Integration.html>`__, the
+HSS is the master of Ellis' and some of Vellum's data, so you only need
+to backup/restore data in the ``homer`` and ``memento`` databases on
+Vellum \* If you are not using a Memento AS, you do not need to
+backup/restore the ``memento`` database on Vellum
 
 Listing Backups
 ---------------
 
-The process for listing backups varies between Ellis and Homestead,
-Homer and Memento.
+The process for listing backups differs between Ellis and Vellum.
 
 Ellis
 ~~~~~
@@ -42,25 +48,15 @@ To list the backups that have been taken on Ellis, run
     1372294621  /usr/share/clearwater/ellis/backup/backups/1372294621
     1372294561  /usr/share/clearwater/ellis/backup/backups/1372294561
 
-Homestead, Homer and Memento
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Homestead actually contains two databases (``homestead_provisioning``
-and ``homestead_cache``) and these must be backed up together. This is
-why there are two commands for each Homestead operation. Homer and
-Memento only contain one database and so there is only one command for
-each operation.
+Vellum
+~~~~~~
 
-To list the backups that have been taken on Homestead, Homer or Memento,
-run
+To list the backups that have been taken on Vellum, run
 
 -  ``sudo /usr/share/clearwater/bin/list_backups.sh homestead_provisioning``
-   and
-   ``sudo /usr/share/clearwater/bin/list_backups.sh homestead_cache``
-   for Homestead
--  ``sudo /usr/share/clearwater/bin/list_backups.sh homer`` for Homer
--  ``sudo /usr/share/clearwater/bin/list_backups.sh memento`` for
-   Memento.
+-  ``sudo /usr/share/clearwater/bin/list_backups.sh homestead_cache``
+-  ``sudo /usr/share/clearwater/bin/list_backups.sh homer``
+-  ``sudo /usr/share/clearwater/bin/list_backups.sh memento``
 
 This produces output of the following form, listing each of the
 available backups.
@@ -74,15 +70,15 @@ available backups.
     provisioning1372813143119
 
 You can also specify a directory to search in for backups, e.g. for
-Homestead:
+``homestead_provisioning``:
 
 ``sudo /usr/share/clearwater/bin/list_backups.sh homestead_provisioning <backup dir>``
 
 Taking a Manual Backup
 ----------------------
 
-The process for taking a manual backup varies between Ellis and
-Homestead, Homer and Memento. Note that in all cases,
+The process for taking a manual backup differs between Ellis and Vellum.
+Note that in both cases,
 
 -  the backup is stored locally and should be copied to a secure backup
    server to ensure resilience
@@ -122,20 +118,17 @@ user's home directory, run
 This file can, and should, be copied off the Ellis node to a secure
 backup server.
 
-Homestead, Homer and Memento
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Vellum
+~~~~~~
 
-To take a manual backup on Homestead, Homer or Memento, run
+To take a manual backup on Vellum, run
 
 -  ``sudo cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_provisioning``
-   and
-   ``sudo cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_cache``
-   on Homestead
+-  ``sudo cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_cache``
 -  ``sudo cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homer``
-   on Homer
--  ``sudo /usr/share/clearwater/bin/do_backup.sh memento`` on Memento.
+-  ``sudo cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh memento``
 
-This produces output of the following form, reporting the
+These each produce output of the following form, reporting the
 successfully-created backup.
 
 ::
@@ -147,11 +140,13 @@ successfully-created backup.
     Snapshot directory: 1372850637124
     Backups can be found at: /usr/share/clearwater/homestead/backup/backups/provisioning/
 
-Make a note of the snapshot directory - this will be referred to as
-``<snapshot>`` below.
+Note that Each of the Vellum databases will produce a different snapshot
+in a different directory.
 
-The backups are only stored locally - the resulting backup is stored in
-``/usr/share/clearwater/homestead/backup/backups/provisioning/<snapshot>``
+The backups are only stored locally - the resulting backup for each
+command is stored in the listed directory. Make a note of the snapshot
+directory for each database - these will be referred to as
+``<snapshot>`` below.
 
 These should be copied off the node to a secure backup server. For
 example, from a remote location execute
@@ -160,22 +155,22 @@ example, from a remote location execute
 Periodic Automated Local Backups
 --------------------------------
 
-Ellis, Homestead, Homer and Memento are all automatically configured to
-take daily backups if you've installed them through chef, at midnight
-local time every night.
+Ellis and Vellum are automatically configured to take daily backups if
+you've installed them through chef, at midnight local time every night.
 
 If you want to turn this on, edit your crontab by running
 ``sudo crontab -e`` and add the following lines if not already present:
 
--  ``0 0 * * * /usr/share/clearwater/ellis/backup/do_backup.sh`` on Elis
--  ``0 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_provisioning``
-   and
-   ``5 0 * * * cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_cache``
-   on Homestead
--  ``0 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homer``
-   on Homer
--  ``0 0 * * * /usr/share/clearwater/bin/do_backup.sh memento`` on
-   Memento.
+-  On Ellis:
+
+   -  ``0 0 * * * /usr/share/clearwater/ellis/backup/do_backup.sh``
+
+-  On Vellum:
+
+   -  ``0 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_provisioning``
+   -  ``5 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homestead_cache``
+   -  ``10 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh homer``
+   -  ``15 0 * * * /usr/bin/cw-run_in_signaling_namespace /usr/share/clearwater/bin/do_backup.sh memento``
 
 These backups are stored locally, in the same locations as they would be
 generated for a manual backup.
@@ -187,8 +182,7 @@ There are three stages to restoring from a backup.
 
 1. Copying the backup files to the correct location.
 2. Running the restore backup script.
-3. Synchronizing Ellis, Homestead, Homer and Memento's views of the
-   system state.
+3. Synchronizing Ellis' and Vellum's views of the system state.
 
 **This process will impact service and overwrite data in your
 database.**
@@ -197,8 +191,8 @@ Copying Backup Files
 ~~~~~~~~~~~~~~~~~~~~
 
 The first step in restoring from a backup is getting the backup
-files/directories into the correct locations on the Ellis, Homer,
-Homestead or Memento node.
+files/directories into the correct locations on the Ellis or Vellum
+node.
 
 If you are restoring from a backup that was taken on the node on which
 you are restoring (and haven't moved it), you can just move onto the
@@ -208,7 +202,7 @@ If not, create a directory on your system that you want to put your
 backups into (we'll use ``~/backup`` in this example). Then copy the
 backups there. For example, from a remote location that contains your
 backup directory ``<snapshot>`` execute
-``scp -r <snapshot> ubuntu@<homestead node>:backup/<snapshot>``.
+``scp -r <snapshot> ubuntu@<vellum node>:backup/<snapshot>``.
 
 On Ellis, run the following commands.
 
@@ -219,33 +213,36 @@ On Ellis, run the following commands.
     sudo mkdir -p /usr/share/clearwater/ellis/backup/backups/$snapshot
     sudo mv ~/backup/$snapshot/db_backup.sql /usr/share/clearwater/ellis/backup/backups/$snapshot
 
-On Homestead/Homer/Memento there is no need to further move the files as
-the backup script takes a optional backup directory parameter.
+On Vellum there is no need to further move the files as the backup
+script takes a optional backup directory parameter.
 
-If you are restoring a Homestead/Homer/Memento backup onto a completely
-clean deployment, you must ensure that the new deployment has at least
-as many Homestead/Homer/Memento nodes as the one from which the backup
-was taken. Each backup should be restored onto only one node, and each
-node should have only one backup restored onto it. If your new
-deployment does not have enough Homestead/Homer/Memento nodes, you
-should add more nodes and then, once restoring backups is complete,
-scale down your deployment to the desired size.
+If you are restoring a Vellum backup onto a completely clean deployment,
+you must ensure that the new deployment has at least as many Vellum
+nodes as the one from which the backup was taken. Each backup should be
+restored onto only one node, and each node should have only one backup
+restored onto it. If your new deployment does not have enough Vellum
+nodes, you should add more nodes and then, once restoring backups is
+complete, scale down your deployment to the desired size.
 
 Running the Restore Backup Script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To actually restore from the backup file, run
+To actually restore from the backup file, run:
+
+-  On Ellis:
+
+   -  ``sudo /usr/share/clearwater/ellis/backup/restore_backup.sh <snapshot>``
 
--  ``sudo /usr/share/clearwater/ellis/backup/restore_backup.sh <snapshot>``
-   on Ellis
--  ``sudo /usr/share/clearwater/bin/restore_backup.sh homestead_provisioning <snapshot> <backup directory>``
-   and
-   ``sudo /usr/share/clearwater/bin/restore_backup.sh homestead_cache <snapshot> <backup directory>``
-   on Homestead
--  ``sudo /usr/share/clearwater/bin/restore_backup.sh homer <snapshot> <backup directory>``
-   on Homer
--  ``sudo /usr/share/clearwater/bin/restore_backup.sh memento <snapshot> <backup directory>``
-   on Memento.
+-  On Vellum:
+
+   -  ``sudo /usr/share/clearwater/bin/restore_backup.sh homestead_provisioning <hs-prov-snapshot> <backup directory>``
+   -  ``sudo /usr/share/clearwater/bin/restore_backup.sh homestead_cache <hs-cache-snapshot> <backup directory>``
+   -  ``sudo /usr/share/clearwater/bin/restore_backup.sh homer <homer-snapshot> <backup directory>``
+   -  ``sudo /usr/share/clearwater/bin/restore_backup.sh memento <memento-snapshot> <backup directory>``
+
+Note that, because the 4 Vellum databases are saved to different
+backups, the name of the snapshot used to restore each of the databases
+will be different.
 
 Ellis will produce output of the following form.
 
@@ -264,7 +261,7 @@ Ellis will produce output of the following form.
     /*!40111 SET SQL_NOTES=@OLD_SQL_NOTES */
     --------------
 
-Homestead, Homer or Memento will produce output of the following form.
+Vellum will produce output of the following form.
 
 ::
 
@@ -284,10 +281,10 @@ Homestead, Homer or Memento will produce output of the following form.
     sip_digests: Deleting old .db files...
     sip_digests: Restoring from backup: 1372336442947
 
-For Homestead, Homer or Memento, after restoring a backup you must also
-do the following: - wait until the Cassandra process has restarted by
-running ``sudo monit summary`` and verifying that the
-``cassandra_process`` is marked as ``Running`` - run
+For Vellum, after restoring the backups you must also do the following:
+- wait until the Cassandra process has restarted by running
+``sudo monit summary`` and verifying that the ``cassandra_process`` is
+marked as ``Running`` - run
 ``sudo cw-run_in_signaling_namespace nodetool repair``
 
 At this point, this node has been restored.
@@ -297,8 +294,8 @@ Synchronization
 
 It is possible (and likely) that when backups are taken on different
 boxes the data will be out of sync, e.g. Ellis will know about a
-subscriber, but there will no digest in Homestead. To restore the system
-to a consistent state we have a synchronization tool within Ellis, which
+subscriber, but there will no digest in Vellum. To restore the system to
+a consistent state we have a synchronization tool within Ellis, which
 can be run over a deployment to get the databases in sync. To run, log
 into an Ellis box and execute:
 
@@ -312,22 +309,22 @@ This will:
 -  Run through all the lines on Ellis that have an owner and verify that
    there is a private identity associated with the public identity
    stored in Ellis. If successful, it will verify that a digest exists
-   in Homestead for that private identity. If either of these checks
-   fail, the line is considered lost and is removed from Ellis. If both
-   checks pass, it will check that there is a valid IFC - if this is
-   missing, it will be replaced with the default IFC.
+   in Vellum for that private identity. If either of these checks fail,
+   the line is considered lost and is removed from Ellis. If both checks
+   pass, it will check that there is a valid IFC - if this is missing,
+   it will be replaced with the default IFC.
 -  Run through all the lines on Ellis without an owner and make sure
-   there is no orphaned data in Homestead and Homer, i.e. deleting the
-   simservs, IFC and digest for those lines.
+   there is no orphaned data in Vellum, i.e. deleting the simservs, IFC
+   and digest for those lines.
 
 Shared Configuration
 --------------------
 
-In addition to the data stored in Ellis, Homer, Homestead and Memento, a
-Clearwater deployment also has shared configuration that is
-`automatically shared between
-nodes <Automatic_Clustering_Config_Sharing.html>`__. This is stored in a
-distributed database, and mirrored to files on the disk of each node.
+In addition to the data stored in Ellis and Vellum, a Clearwater
+deployment also has shared configuration that is `automatically shared
+between nodes <Automatic_Clustering_Config_Sharing.html>`__. This is
+stored in a distributed database, and mirrored to files on the disk of
+each node.
 
 Backing Up
 ~~~~~~~~~~
@@ -341,8 +338,12 @@ To backup the shared configuration:
 -  Copy the following files to somewhere else for safe keeping (e.g.
    another directory on the node, or another node entirely).
 
-   /etc/clearwater/shared\_config /etc/clearwater/bgcf.json
-   /etc/clearwater/enum.json /etc/clearwater/s-cscf.json
+   ::
+
+       /etc/clearwater/shared_config
+       /etc/clearwater/bgcf.json
+       /etc/clearwater/enum.json
+       /etc/clearwater/s-cscf.json
 
 Restoring Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~