Check in updated autogenerated files

autogenerated_rst_docs/All_in_one_EC2_AMI_Installation.rst

@@ -0,0 +1,45 @@
+All-in-one EC2 AMI Installation
+===============================
+
+This pages describes how to launch and run an `all-in-one
+image <All_in_one_Images.md>`__ in Amazon's EC2 environment.
+
+Launch Process
+--------------
+
+Project Clearwater's all-in-one node is already available as a pre-built
+AMI, which can be found in the Community AMIs list on the US East region
+of EC2. Launching this follows exactly the same process as for other EC2
+AMIs.
+
+Before you launch the node, you will need an EC2 keypair, and a security
+group configured to provide access to the `required
+ports <Clearwater_IP_Port_Usage.md>`__.
+
+To launch the node
+
+-  From the EC2 console, make sure you're in the US East region, then
+   select "Instances", "Launch instance" and then "Classic Wizard"
+-  Select the "Community AMIs" tab, and search for "Clearwater"
+-  Press "Select" for the Clearwater all-in-one AMI. Take the most
+   recent version unless you have a good reason not to.
+-  Choose the Instance Type you require (the node runs fine for basic
+   functional testing on an t2.small)
+-  From the remaining pages of parameters, the only ones that need to be
+   set are Name (give the node whatever convenient name you wish),
+   keypair and security group.
+
+On the last page, press "Launch", and wait for the node to be started by
+EC2.
+
+Running and Using the Image
+---------------------------
+
+Once the node has launched, you can SSH to it using the keypair you
+supplied at launch time, and username ``ubuntu``.
+
+You can then try `making your first call <Making_your_first_call.md>`__
+and `running the live tests <Running_the_live_tests.md>`__ - for these
+you will need the signup key, which is ``secret``. You will probably
+want to change this to a more secure value - see `"Modifying Clearwater
+settings" <Modifying_Clearwater_settings.md>`__ for how to do this.

autogenerated_rst_docs/All_in_one_Images.rst

@@ -0,0 +1,102 @@
+All-in-one Images
+=================
+
+While Clearwater is designed to be massively horizontally scalable, it
+is also possible to install all Clearwater components on a single node.
+This makes installation much simpler, and is useful for familiarizing
+yourself with Clearwater before moving up to a larger-scale deployment
+using one of the `other installation
+methods <Installation_Instructions.md>`__.
+
+This page describes the all-in-one images, their capabilities and
+restrictions and the installation options available.
+
+Images
+------
+
+All-in-one images consist of
+
+-  Ubuntu 14.04, configured to use DHCP
+-  bono, sprout, homestead, homer and ellis
+-  Clearwater auto-configuration scripts.
+
+On boot, the image retrieves its IP configuration over DHCP and the
+auto-configuration scripts then configure the bono, sprout, homestead,
+homer and ellis software to match.
+
+The image is designed to run on a virtual machine with a single core,
+2GB RAM and 8GB of disk space. On EC2, this is an t2.small.
+
+Capabilities and Restrictions
+-----------------------------
+
+Since the all-in-one images include all of bono, sprout, homestead,
+homer and ellis, they are capable of almost anything a full deployment
+is capable of.
+
+The key restrictions of all-in-one images are
+
+-  hard-coded realm - the all-in-one image uses a hard-coded realm of
+   ``example.com`` so your SIP URI might be
+   ``sip:6505551234@example.com`` - by default, SIP uses this realm for
+   routing but ``example.com`` won't resolve to your host so you need to
+   configure an outbound proxy on all your SIP clients (more details
+   later)
+-  performance - since all software runs on a single virtual machine,
+   performance is significantly lower than even the smallest scale
+   deployment
+-  scalability - there is no option to scale up and add more virtual
+   machines to boost capacity - for this, you must create a normal
+   deployment
+-  fault-tolerance - since everything runs on a single virtual machine,
+   if that virtual machine fails, the service as a whole fails.
+
+Installation Options
+--------------------
+
+All-in-one images can be installed on EC2 or on your own virtualization
+platform, as long as it supports `OVF (Open Virtualization
+Format) <http://dmtf.org/standards/ovf>`__.
+
+-  To install on EC2, follow the `all-in-one EC2 AMI installation
+   instructions <All_in_one_EC2_AMI_Installation.md>`__.
+-  To install on your own virtualization platform, follow the
+   `all-in-one OVF installation
+   instructions <All_in_one_OVF_Installation.md>`__.
+
+Manual Build
+------------
+
+If your virtualization platform is not EC2 and doesn't support OVF, you
+may still be able to manually build an all-in-one node. To do so,
+
+1. install `Ubuntu 14.04 - 64bit server
+   edition <http://releases.ubuntu.com/trusty/>`__
+2. find the ``preseed/late_command`` entry in the `all-in-one image's
+   install
+   script <https://github.com/Metaswitch/clearwater-vm-images/blob/master/ubuntu-ovf/ubuntu-server.seed>`__
+   - as of writing this is as follows, but please check the linked file
+   for the latest version
+
+   ::
+
+        d-i preseed/late_command string in-target bash -c '{ echo "#!/bin/bash" ; \
+                                                    echo "set -e" ; \
+                                                    echo "repo=... # filled in by make_ovf.sh" ; \
+                                                    echo "curl -L https://raw.githubusercontent.com/Metaswitch/clearwater-infrastructure/master/scripts/clearwater-aio-install.sh | sudo bash -s clearwater-auto-config-generic $repo" ; \
+                                                    echo "python create_numbers.py --start 6505550000 --count 1000" ; \
+                                                    echo "rm /etc/rc2.d/S99zclearwater-aio-first-boot" ; \
+                                                    echo "poweroff" ; } > /etc/rc2.d/S99zclearwater-aio-first-boot ; \
+                                                  chmod a+x /etc/rc2.d/S99zclearwater-aio-first-boot'
+
+3. run the command (stripping the
+   ``d-i preseed/late_command string in-target`` prefix, filling in the
+   repo variable - the default is ``http://repo.cw-ngv.com/stable``, and
+   stripping the ``\``) - this will create an
+   ``/etc/rc2.d/S99zclearwater-aio-first-boot`` script
+4. run the ``/etc/rc2.d/S99zclearwater-aio-first-boot`` script - this
+   will install the all-in-one software and then shutdown (ready for an
+   image to be taken)
+5. restart the node.
+
+

autogenerated_rst_docs/All_in_one_OVF_Installation.rst

@@ -0,0 +1,97 @@
+All-in-one OVF Installation
+===========================
+
+This pages describes how to install an `all-in-one
+image <All_in_one_Images.md>`__ on your own virtualization platform
+using `OVF (Open Virtualization
+Format) <http://dmtf.org/standards/ovf>`__.
+
+Supported Platforms
+-------------------
+
+This process should work on any virtualization platform that supports
+OVFs using x86-64 CPUs, but has only been tested on
+
+-  `VMware Player <http://www.vmware.com/products/player/>`__
+-  `VirtualBox <https://www.virtualbox.org/>`__
+-  `VMware
+   ESXi <http://www.vmware.com/products/vsphere-hypervisor/overview.html>`__.
+
+The image uses DHCP to gets its IP configuration, so the virtualization
+platform must either serve DHCP natively or be connected to a network
+with a DHCP server.
+
+If you install/run the OVF on another platform, please let us know how
+you get on on the `mailing
+list <http://lists.projectclearwater.org/listinfo/clearwater>`__ so we
+can update this page.
+
+Installation Process
+--------------------
+
+To install the OVF, you must first download it from
+http://vm-images.cw-ngv.com/cw-aio.ova and save it to disk.
+
+Then, you must import it into your virtualization platform. The process
+for this varies.
+
+-  On VMware Player, choose **File->Open a Virtual Machine** from the
+   menu and select the cw-aio.ova file you downloaded. On the Import
+   Virtual Machine dialog that appears, the defaults are normally fine,
+   so you can just click **Import**.
+-  On VirtualBox, choose **File->Import Appliance...** from the menu. In
+   the Appliance Import Wizard, click **Choose...**, select the
+   cw-aio.ova file you downloaded and click **Next**. On the next tab,
+   you can view the settings and then click **Import**.
+-  On VMware ESXi, using the VMware vSphere Client, choose
+   **File->Deploy OVF Template...** from the menu. Select the cw-aio.ova
+   file you downloaded and click through assigning it a suitable name,
+   location and attached network (which must support DHCP) before
+   finally clicking **Finish** to create the virtual machine.
+
+Running and Using the Image
+---------------------------
+
+Once you've installed the virtual machine, you should start it in the
+usual way for your virtualization platform.
+
+If you attach to the console, you should see an Ubuntu loading screen
+and then be dropped at a ``cw-aio`` login prompt. The username is
+``ubuntu`` and the password is ``cw-aio``. Note that the console is
+hard-coded to use a US keyboard, so if you have a different keyboard you
+might find that keys are remapped - in particular the ``-`` key.
+
+The OVF provides 3 network services.
+
+-  SSH - username is ``ubuntu`` and password is ``cw-aio``
+-  HTTP to ellis for subscriber management - sign-up code is ``secret``.
+   You will probably want to change this to a more secure value - see
+   `"Modifying Clearwater
+   settings" <Modifying_Clearwater_settings.md>`__ for how to do this.
+-  SIP to bono for call signaling - credentials are provisioned through
+   ellis.
+
+How these network services are exposed can vary depending on the
+capabilities of the platform.
+
+-  VMware Player sets up a private network between your PC and the
+   virtual machine and normally assigns the virtual machine IP address
+   ``192.168.28.128``. To access ellis, you'll need to point your
+   browser at http://192.168.28.128. To register over SIP, you'll need
+   to configure an outbound proxy of 192.168.28.128 port 5060.
+
+-  VirtualBox uses NAT on the local IP address, exposing SSH on port
+   8022, HTTP on port 8080 and SIP on port 8060. To access ellis, you'll
+   need to point your browser at http://localhost:8080. To register over
+   SIP, you'll need to configure an outbound proxy of localhost port
+   8060.
+
+-  VMware ESXi runs the host as normal on the network, so you can
+   connect to it directly. To find out its IP address, log in over the
+   console and type ``hostname -I``. To access ellis, just point your
+   browser at this IP address. To register over SIP, you'll need to
+   configure an outbound proxy for this IP address.
+
+Once you've successfully connected to ellis, try `making your first
+call <Making_your_first_call.md>`__ - just remember to configure the SIP
+outbound proxy as discussed above.