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

Proposed by Vish Ishaya on 2011-04-11
Status: Merged
Approved by: Soren Hansen on 2011-04-13
Approved revision: 978
Merged at revision: 985
Proposed branch: lp:~vishvananda/nova/cloudpipe-docs
Merge into: lp:~hudson-openstack/nova/trunk
Diff against target: 187 lines (+149/-0)
5 files modified
doc/source/devref/cloudpipe.rst (+65/-0)
doc/source/devref/rc.local (+36/-0)
doc/source/devref/server.conf.template (+34/-0)
doc/source/down.sh (+7/-0)
doc/source/up.sh (+7/-0)
To merge this branch: bzr merge lp:~vishvananda/nova/cloudpipe-docs
Reviewer Review Type Date Requested Status
Soren Hansen (community) Approve on 2011-04-13
Devin Carlen (community) 2011-04-11 Approve on 2011-04-12
Anne Gentle (community) Approve on 2011-04-12
Review via email: mp+57241@code.launchpad.net

Description of the change

Updates the documentation on creating and using a cloudpipe image.

To post a comment you must log in.
Anne Gentle (annegentle) wrote :

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) wrote :

yay for documentation

review: Approve
lp:~vishvananda/nova/cloudpipe-docs updated on 2011-04-12
978. By Vish Ishaya on 2011-04-12

add up and down .sh

Soren Hansen (soren) wrote :

lgtm

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
=== 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 @@
38It 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).38It 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).
3939
4040
41Creating a Cloudpipe Image
42--------------------------
43
44Making a cloudpipe image is relatively easy.
45
46# install openvpn on a base ubuntu image.
47# set up a server.conf.template in /etc/openvpn/
48
49.. literalinclude:: server.conf.template
50 :language: bash
51 :linenos:
52
53# set up.sh in /etc/openvpn/
54
55.. literalinclude:: up.sh
56 :language: bash
57 :linenos:
58
59# set down.sh in /etc/openvpn/
60
61.. literalinclude:: down.sh
62 :language: bash
63 :linenos:
64
65# download and run the payload on boot from /etc/rc.local.
66
67.. literalinclude:: rc.local
68 :language: bash
69 :linenos:
70
71# register the image and set the image id in your flagfile::
72
73 --vpn_image_id=ami-xxxxxxxx
74
75# you should set a few other flags to make vpns work properly::
76
77 --use_project_ca
78 --cnt_vpn_clients=5
79
80
41Cloudpipe Launch81Cloudpipe Launch
42----------------82----------------
4383
@@ -63,6 +103,31 @@
63103
64If 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.104If 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.
65105
106The 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.
107
108
109Restarting Cloudpipe VPN
110------------------------
111
112You 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)::
113
114 euca-terminate-instances <instance_id>
115 mysql nova -e "update fixed_ips set allocated=0, leased=0, instance_id=NULL where fixed_ip='10.0.0.2'"
116
117You also will need to terminate the dnsmasq running for the user (make sure you use the right pid file)::
118
119 sudo kill `cat /var/lib/nova/br100.pid`
120
121Now you should be able to re-run the vpn::
122
123 nova-manage vpn run <project_id>
124
125
126Logging into Cloudpipe VPN
127--------------------------
128
129The 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.
130
66131
67The :mod:`nova.cloudpipe.pipelib` Module132The :mod:`nova.cloudpipe.pipelib` Module
68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~133~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69134
=== 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 @@
1#!/bin/sh -e
2#
3# rc.local
4#
5# This script is executed at the end of each multiuser runlevel.
6# Make sure that the script will "exit 0" on success or any other
7# value on error.
8#
9# In order to enable or disable this script just change the execution
10# bits.
11#
12# By default this script does nothing.
13####### These lines go at the end of /etc/rc.local #######
14. /lib/lsb/init-functions
15
16echo Downloading payload from userdata
17wget http://169.254.169.254/latest/user-data -O /tmp/payload.b64
18echo Decrypting base64 payload
19openssl enc -d -base64 -in /tmp/payload.b64 -out /tmp/payload.zip
20
21mkdir -p /tmp/payload
22echo Unzipping payload file
23unzip -o /tmp/payload.zip -d /tmp/payload/
24
25# if the autorun.sh script exists, run it
26if [ -e /tmp/payload/autorun.sh ]; then
27 echo Running autorun.sh
28 cd /tmp/payload
29 sh /tmp/payload/autorun.sh
30
31else
32 echo rc.local : No autorun script to run
33fi
34
35
36exit 0
037
=== 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 @@
1port 1194
2proto udp
3dev tap0
4up "/etc/openvpn/up.sh br0"
5down "/etc/openvpn/down.sh br0"
6
7persist-key
8persist-tun
9
10ca ca.crt
11cert server.crt
12key server.key # This file should be kept secret
13
14dh dh1024.pem
15ifconfig-pool-persist ipp.txt
16
17server-bridge VPN_IP DHCP_SUBNET DHCP_LOWER DHCP_UPPER
18
19client-to-client
20keepalive 10 120
21comp-lzo
22
23max-clients 1
24
25user nobody
26group nogroup
27
28persist-key
29persist-tun
30
31status openvpn-status.log
32
33verb 3
34mute 20
0\ No newline at end of file35\ No newline at end of file
136
=== 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 @@
1#!/bin/sh
2
3BR=$1
4DEV=$2
5
6/usr/sbin/brctl delif $BR $DEV
7/sbin/ifconfig $DEV down
08
=== 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 @@
1#!/bin/sh
2
3BR=$1
4DEV=$2
5MTU=$3
6/sbin/ifconfig $DEV mtu $MTU promisc up
7/usr/sbin/brctl addif $BR $DEV