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

Proposed by Vish Ishaya
Status: Merged
Approved by: Soren Hansen
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
Devin Carlen (community) Approve
Anne Gentle (community) Approve
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.
Revision history for this message
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
Revision history for this message
Devin Carlen (devcamcar) wrote :

yay for documentation

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

add up and down .sh

Revision history for this message
Soren Hansen (soren) wrote :

lgtm

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'doc/source/devref/cloudpipe.rst'
2--- doc/source/devref/cloudpipe.rst 2011-01-04 22:58:08 +0000
3+++ doc/source/devref/cloudpipe.rst 2011-04-12 20:36:36 +0000
4@@ -38,6 +38,46 @@
5 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).
6
7
8+Creating a Cloudpipe Image
9+--------------------------
10+
11+Making a cloudpipe image is relatively easy.
12+
13+# install openvpn on a base ubuntu image.
14+# set up a server.conf.template in /etc/openvpn/
15+
16+.. literalinclude:: server.conf.template
17+ :language: bash
18+ :linenos:
19+
20+# set up.sh in /etc/openvpn/
21+
22+.. literalinclude:: up.sh
23+ :language: bash
24+ :linenos:
25+
26+# set down.sh in /etc/openvpn/
27+
28+.. literalinclude:: down.sh
29+ :language: bash
30+ :linenos:
31+
32+# download and run the payload on boot from /etc/rc.local.
33+
34+.. literalinclude:: rc.local
35+ :language: bash
36+ :linenos:
37+
38+# register the image and set the image id in your flagfile::
39+
40+ --vpn_image_id=ami-xxxxxxxx
41+
42+# you should set a few other flags to make vpns work properly::
43+
44+ --use_project_ca
45+ --cnt_vpn_clients=5
46+
47+
48 Cloudpipe Launch
49 ----------------
50
51@@ -63,6 +103,31 @@
52
53 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.
54
55+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.
56+
57+
58+Restarting Cloudpipe VPN
59+------------------------
60+
61+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)::
62+
63+ euca-terminate-instances <instance_id>
64+ mysql nova -e "update fixed_ips set allocated=0, leased=0, instance_id=NULL where fixed_ip='10.0.0.2'"
65+
66+You also will need to terminate the dnsmasq running for the user (make sure you use the right pid file)::
67+
68+ sudo kill `cat /var/lib/nova/br100.pid`
69+
70+Now you should be able to re-run the vpn::
71+
72+ nova-manage vpn run <project_id>
73+
74+
75+Logging into Cloudpipe VPN
76+--------------------------
77+
78+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.
79+
80
81 The :mod:`nova.cloudpipe.pipelib` Module
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84=== added file 'doc/source/devref/rc.local'
85--- doc/source/devref/rc.local 1970-01-01 00:00:00 +0000
86+++ doc/source/devref/rc.local 2011-04-12 20:36:36 +0000
87@@ -0,0 +1,36 @@
88+#!/bin/sh -e
89+#
90+# rc.local
91+#
92+# This script is executed at the end of each multiuser runlevel.
93+# Make sure that the script will "exit 0" on success or any other
94+# value on error.
95+#
96+# In order to enable or disable this script just change the execution
97+# bits.
98+#
99+# By default this script does nothing.
100+####### These lines go at the end of /etc/rc.local #######
101+. /lib/lsb/init-functions
102+
103+echo Downloading payload from userdata
104+wget http://169.254.169.254/latest/user-data -O /tmp/payload.b64
105+echo Decrypting base64 payload
106+openssl enc -d -base64 -in /tmp/payload.b64 -out /tmp/payload.zip
107+
108+mkdir -p /tmp/payload
109+echo Unzipping payload file
110+unzip -o /tmp/payload.zip -d /tmp/payload/
111+
112+# if the autorun.sh script exists, run it
113+if [ -e /tmp/payload/autorun.sh ]; then
114+ echo Running autorun.sh
115+ cd /tmp/payload
116+ sh /tmp/payload/autorun.sh
117+
118+else
119+ echo rc.local : No autorun script to run
120+fi
121+
122+
123+exit 0
124
125=== added file 'doc/source/devref/server.conf.template'
126--- doc/source/devref/server.conf.template 1970-01-01 00:00:00 +0000
127+++ doc/source/devref/server.conf.template 2011-04-12 20:36:36 +0000
128@@ -0,0 +1,34 @@
129+port 1194
130+proto udp
131+dev tap0
132+up "/etc/openvpn/up.sh br0"
133+down "/etc/openvpn/down.sh br0"
134+
135+persist-key
136+persist-tun
137+
138+ca ca.crt
139+cert server.crt
140+key server.key # This file should be kept secret
141+
142+dh dh1024.pem
143+ifconfig-pool-persist ipp.txt
144+
145+server-bridge VPN_IP DHCP_SUBNET DHCP_LOWER DHCP_UPPER
146+
147+client-to-client
148+keepalive 10 120
149+comp-lzo
150+
151+max-clients 1
152+
153+user nobody
154+group nogroup
155+
156+persist-key
157+persist-tun
158+
159+status openvpn-status.log
160+
161+verb 3
162+mute 20
163\ No newline at end of file
164
165=== added file 'doc/source/down.sh'
166--- doc/source/down.sh 1970-01-01 00:00:00 +0000
167+++ doc/source/down.sh 2011-04-12 20:36:36 +0000
168@@ -0,0 +1,7 @@
169+#!/bin/sh
170+
171+BR=$1
172+DEV=$2
173+
174+/usr/sbin/brctl delif $BR $DEV
175+/sbin/ifconfig $DEV down
176
177=== added file 'doc/source/up.sh'
178--- doc/source/up.sh 1970-01-01 00:00:00 +0000
179+++ doc/source/up.sh 2011-04-12 20:36:36 +0000
180@@ -0,0 +1,7 @@
181+#!/bin/sh
182+
183+BR=$1
184+DEV=$2
185+MTU=$3
186+/sbin/ifconfig $DEV mtu $MTU promisc up
187+/usr/sbin/brctl addif $BR $DEV