Merge pull request #104 from Metaswitch/revert-103-revert-102-crest-i…

…ss223-hsprov Revert "Revert "[Reviewer: Ellie] Install clearwater-prov-tools along…
Metaswitch · Sep 7, 2015 · a4f4dc6 · a4f4dc6
2 parents 3859838 + a260695
commit a4f4dc6
Show file tree

Hide file tree

Showing 5 changed files with 112 additions and 2 deletions.
diff --git a/docs/Exploring_Clearwater.md b/docs/Exploring_Clearwater.md
@@ -36,6 +36,7 @@ Clearwater is designed from the ground up to scale horizontally across multiple
 
 To help you manage your deployment, Clearwater provides:
 
+* [Command-line/scriptable provisioning tools](Provisioning_Subscribers.md)
 * [Support for separated management networks](Multiple_Network_Support.md)
 * [Deployment monitoring](Cacti.md)
 * [Backup](Backups.md)

diff --git a/docs/Manual_Install.md b/docs/Manual_Install.md
@@ -142,7 +142,7 @@ Install the Homer packages with:
 
 Install the Homestead packages with:
 
-    sudo DEBIAN_FRONTEND=noninteractive apt-get install homestead homestead-prov --yes
+    sudo DEBIAN_FRONTEND=noninteractive apt-get install homestead homestead-prov clearwater-prov-tools --yes
     sudo DEBIAN_FRONTEND=noninteractive apt-get install clearwater-management --yes
 
 ### Ralf

diff --git a/docs/Old_Manual_Install.md b/docs/Old_Manual_Install.md
@@ -185,7 +185,7 @@ Install the Homer and Cassandra packages with:
 Install the Homestead and Cassandra packages with:
 
     sudo DEBIAN_FRONTEND=noninteractive apt-get install clearwater-cassandra --yes
-    sudo DEBIAN_FRONTEND=noninteractive apt-get install homestead homestead-prov --yes
+    sudo DEBIAN_FRONTEND=noninteractive apt-get install homestead homestead-prov clearwater-prov-tools --yes
 
 ### Ralf
 

diff --git a/docs/Provisioning_Subscribers.md b/docs/Provisioning_Subscribers.md
@@ -0,0 +1,108 @@
+# Provisioning Subscribers
+
+Clearwater provides the Ellis web UI for easy provisioning of subscribers.  However, sometimes a more programmatic interface is desirable.
+
+Homestead provides a [provisioning API](https://github.com/Metaswitch/crest/blob/dev/docs/homestead_api.md) but, for convenience, Clearwater also provides some command-line provisioning tools.
+
+By default, the tools are installed on the Homestead servers only (as part of the clearwater-prov-tools package), in the `/usr/share/clearwater/bin` directory.
+
+There are 4 tools.
+
+*   `create_user` - for creating users
+*   `update_user` - for updating users' passwords
+*   `delete_user` - for deleting users
+*   `display_user` - for displaying users' details
+
+## Creating users
+
+New users can be created with the `create_user` tool.  As well as creating single users, it's also possible to create multiple users with a single command.  Note that this is not recommended for provisioning large numbers of users - for that, [bulk provisioning](https://github.com/Metaswitch/crest/blob/dev/docs/Bulk-Provisioning%20Numbers.md) is much quicker.
+
+```
+usage: create_user.py [-h] [-k] [-q] [--hsprov IP:PORT] [--plaintext]
+                      [--ifc iFC-FILE] [--prefix TWIN_PREFIX]
+                      <directory-number>[..<directory-number>] <domain>
+                      <password>
+
+Create user
+
+positional arguments:
+  <directory-number>[..<directory-number>]
+  <domain>
+  <password>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -k, --keep-going      keep going on errors
+  -q, --quiet           don't display the user
+  --hsprov IP:PORT      IP address and port of homestead-prov
+  --plaintext           store password in plaintext
+  --ifc iFC-FILE        XML file containing the iFC
+  --prefix TWIN_PREFIX  twin-prefix (default: 123)
+```
+
+## Update users
+
+Existing users' passwords can be updated with the `update_user` tool.
+
+```
+usage: update_user.py [-h] [-k] [-q] [--hsprov IP:PORT] [--plaintext]
+                      <directory-number>[..<directory-number>] <domain>
+                      <password>
+
+Update user
+
+positional arguments:
+  <directory-number>[..<directory-number>]
+  <domain>
+  <password>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -k, --keep-going      keep going on errors
+  -q, --quiet           don't display the user
+  --hsprov IP:PORT      IP address and port of homestead-prov
+  --plaintext           store password in plaintext
+```
+
+## Delete users
+
+Users can be deleted with the `delete_user` tool.
+
+```
+usage: delete_user.py [-h] [-f] [-q] [--hsprov IP:PORT]
+                      <directory-number>[..<directory-number>] <domain>
+
+Delete user
+
+positional arguments:
+  <directory-number>[..<directory-number>]
+  <domain>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -f, --force           proceed with delete in the face of errors
+  -q, --quiet           silence 'forced' error messages
+  --hsprov IP:PORT      IP address and port of homestead-prov
+```
+
+## Display users
+
+Users' details can be displayed with the `display_user` tool.
+
+```
+usage: display_user.py [-h] [-k] [-q] [-s] [--hsprov IP:PORT]
+                       <directory-number>[..<directory-number>] <domain>
+
+Display user
+
+positional arguments:
+  <directory-number>[..<directory-number>]
+  <domain>
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -k, --keep-going      keep going on errors
+  -q, --quiet           suppress errors when ignoring them
+  -s, --short           less verbose display
+  --hsprov IP:PORT      IP address and port of homestead-prov
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -57,6 +57,7 @@ pages:
 - ['IPv6.md', 'Features', 'IPv6']
 - ['SIP_Interface_Specifications.md', 'Features', 'SIP Interface Specifications']
 - ['Automatic_Clustering_Config_Sharing.md', 'Features', 'Automatic Clustering and Configuration Sharing']
+- ['Provisioning_Subscribers.md', 'Features', 'Provisioning Subscribers']
 
 # Failure Recovery:
 - ['Handling_Failed_Nodes.md', 'Failure Recovery', 'Permanent Node Failures']