Merge lp:~vishvananda/nova/cloudpipe-docs into lp:~hudson-openstack/nova/trunk

[Vish Ishaya]

Updates the documentation on creating and using a cloudpipe image.

[Anne Gentle (annegentle)]

Extremely useful. Thanks for writing it up! Is a "crl" in the phrase "if you generate a new crl" a certificate revocation list? Just making sure, it might be nice to spell it out.

review: Approve

[Devin Carlen (devcamcar)]

yay for documentation

review: Approve

[lp:~vishvananda/nova/cloudpipe-docs]

978. By Vish Ishaya on 2011-04-12

add up and down .sh

[Soren Hansen (soren)]

lgtm

review: Approve

=== modified file 'doc/source/devref/cloudpipe.rst'
--- doc/source/devref/cloudpipe.rst	2011-01-04 22:58:08 +0000
+++ doc/source/devref/cloudpipe.rst	2011-04-12 20:36:36 +0000
@@ -38,6 +38,46 @@
 It is also useful to have a cron script that will periodically redownload the metadata and copy the new crl.  This will keep revoked users from connecting and will disconnect any users that are connected with revoked certificates when their connection is renegotiated (every hour).
 
 
+Creating a Cloudpipe Image
+--------------------------
+
+Making a cloudpipe image is relatively easy.
+
+# install openvpn on a base ubuntu image.
+# set up a server.conf.template in /etc/openvpn/
+
+.. literalinclude:: server.conf.template
+   :language: bash
+   :linenos:
+
+# set up.sh in /etc/openvpn/
+
+.. literalinclude:: up.sh
+   :language: bash
+   :linenos:
+
+# set down.sh in /etc/openvpn/
+
+.. literalinclude:: down.sh
+   :language: bash
+   :linenos:
+
+# download and run the payload on boot from /etc/rc.local.
+
+.. literalinclude:: rc.local
+   :language: bash
+   :linenos:
+
+# register the image and set the image id in your flagfile::
+
+    --vpn_image_id=ami-xxxxxxxx
+
+# you should set a few other flags to make vpns work properly::
+
+    --use_project_ca
+    --cnt_vpn_clients=5
+
+
 Cloudpipe Launch
 ----------------
 
@@ -63,6 +103,31 @@
 
 If the use_project_ca flag is set (required to for cloudpipes to work securely), then each project has its own ca.  This ca is used to sign the certificate for the vpn, and is also passed to the user for bundling images.  When a certificate is revoked using nova-manage, a new Certificate Revocation List (crl) is generated.  As long as cloudpipe has an updated crl, it will block revoked users from connecting to the vpn.
 
+The userdata for cloudpipe isn't currently updated when certs are revoked, so it is necessary to restart the cloudpipe instance if a user's credentials are revoked.
+
+
+Restarting Cloudpipe VPN
+------------------------
+
+You can reboot a cloudpipe vpn through the api if something goes wrong (using euca-reboot-instances for example), but if you generate a new crl, you will have to terminate it and start it again using nova-manage vpn run.  The cloudpipe instance always gets the first ip in the subnet and it can take up to 10 minutes for the ip to be recovered.  If you try to start the new vpn instance too soon, the instance will fail to start because of a NoMoreAddresses error.  If you can't wait 10 minutes, you can manually update the ip with something like the following (use the right ip for the project)::
+
+    euca-terminate-instances <instance_id>
+    mysql nova -e "update fixed_ips set allocated=0, leased=0, instance_id=NULL where fixed_ip='10.0.0.2'"
+
+You also will need to terminate the dnsmasq running for the user (make sure you use the right pid file)::
+
+    sudo kill `cat /var/lib/nova/br100.pid`
+
+Now you should be able to re-run the vpn::
+
+    nova-manage vpn run <project_id>
+
+
+Logging into Cloudpipe VPN
+--------------------------
+
+The keypair that was used to launch the cloudpipe instance should be in the keys/<project_id> folder.  You can use this key to log into the cloudpipe instance for debugging purposes.
+
 
 The :mod:`nova.cloudpipe.pipelib` Module
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

=== added file 'doc/source/devref/rc.local'
--- doc/source/devref/rc.local	1970-01-01 00:00:00 +0000
+++ doc/source/devref/rc.local	2011-04-12 20:36:36 +0000
@@ -0,0 +1,36 @@
+#!/bin/sh -e
+#
+# rc.local
+#
+# This script is executed at the end of each multiuser runlevel.
+# Make sure that the script will "exit 0" on success or any other
+# value on error.
+#
+# In order to enable or disable this script just change the execution
+# bits.
+#
+# By default this script does nothing.
+####### These lines go at the end of /etc/rc.local #######
+. /lib/lsb/init-functions
+
+echo Downloading payload from userdata
+wget http://169.254.169.254/latest/user-data -O /tmp/payload.b64
+echo Decrypting base64 payload
+openssl enc -d -base64 -in /tmp/payload.b64 -out /tmp/payload.zip
+
+mkdir -p /tmp/payload
+echo Unzipping payload file
+unzip -o /tmp/payload.zip -d /tmp/payload/
+
+# if the autorun.sh script exists, run it
+if [ -e /tmp/payload/autorun.sh ]; then
+  echo Running autorun.sh
+  cd /tmp/payload
+  sh /tmp/payload/autorun.sh
+
+else
+  echo rc.local : No autorun script to run
+fi
+
+
+exit 0

=== added file 'doc/source/devref/server.conf.template'
--- doc/source/devref/server.conf.template	1970-01-01 00:00:00 +0000
+++ doc/source/devref/server.conf.template	2011-04-12 20:36:36 +0000
@@ -0,0 +1,34 @@
+port 1194
+proto udp
+dev tap0
+up "/etc/openvpn/up.sh br0"
+down "/etc/openvpn/down.sh br0"
+
+persist-key
+persist-tun
+
+ca ca.crt
+cert server.crt
+key server.key  # This file should be kept secret
+
+dh dh1024.pem
+ifconfig-pool-persist ipp.txt
+
+server-bridge VPN_IP DHCP_SUBNET DHCP_LOWER DHCP_UPPER
+
+client-to-client
+keepalive 10 120
+comp-lzo
+
+max-clients 1
+
+user nobody
+group nogroup
+
+persist-key
+persist-tun
+
+status openvpn-status.log
+
+verb 3
+mute 20
\ No newline at end of file

=== added file 'doc/source/down.sh'
--- doc/source/down.sh	1970-01-01 00:00:00 +0000
+++ doc/source/down.sh	2011-04-12 20:36:36 +0000
@@ -0,0 +1,7 @@
+#!/bin/sh
+
+BR=$1
+DEV=$2
+
+/usr/sbin/brctl delif $BR $DEV
+/sbin/ifconfig $DEV down

=== added file 'doc/source/up.sh'
--- doc/source/up.sh	1970-01-01 00:00:00 +0000
+++ doc/source/up.sh	2011-04-12 20:36:36 +0000
@@ -0,0 +1,7 @@
+#!/bin/sh
+
+BR=$1
+DEV=$2
+MTU=$3
+/sbin/ifconfig $DEV mtu $MTU promisc up
+/usr/sbin/brctl addif $BR $DEV