Move static docs into master branch
The hand-maintained static HTML docs for DevStack have been in a
GitHub gh-pages branch; move them into the master branch in
preparation for hosting them in openstack.org infrastructure.
By default tools/build_docs.sh now builds the static HTML output
into docs/html.
Change-Id: Ide5f7d980a294c7a9f8a3decaed0939f1c239934
diff --git a/docs/source/guides/multinode-lab.html b/docs/source/guides/multinode-lab.html
new file mode 100644
index 0000000..28a6585
--- /dev/null
+++ b/docs/source/guides/multinode-lab.html
@@ -0,0 +1,330 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>Multi-Node Lab Server Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+
+ <section id="overview">
+ <h1>Multi-Node Lab: Serious Stuff</h1>
+ <p>Here is OpenStack in a realistic test configuration with multiple physical servers.</p>
+ </section>
+
+ <section id="prerequisites">
+ <div class="page-header">
+ <h2>Prerequisites <small>Linux & Network</small></h2>
+ </div>
+
+ <h3>Minimal Install</h3>
+ <p>You need to have a fresh install of Linux on all of your nodes. You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu 12.04 (only 27MB) since DevStack will download & install all the additional dependencies. The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/20/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.5/isos/x86_64/CentOS-6.5-x86_64-netinstall.iso">CentOS/RHEL</a>.</p>
+
+ <p>Install a couple of packages to bootstrap configuration:</p>
+ <pre>apt-get install -y git sudo || yum install -y git sudo</pre>
+
+ <h3>Network Configuration</h3>
+ <p>The first iteration of the lab uses OpenStack's FlatDHCP network controller so
+ only a single network will be required. It should be on its own subnet without DHCP;
+ the host IPs and floating IP pool(s) will come out of this block. This example
+ uses the following:</p>
+ <ul>
+ <li>Gateway: 192.168.42.1</li>
+ <li>Physical nodes: 192.168.42.11-192.168.42.99</li>
+ <li>Floating IPs: 192.168.42.128-192.168.42.254</li>
+ </ul>
+ <p>Configure each node with a static IP.
+ For Ubuntu edit <code>/etc/network/interfaces</code>:</p>
+
+ <pre>auto eth0
+iface eth0 inet static
+ address 192.168.42.11
+ netmask 255.255.255.0
+ gateway 192.168.42.1
+</pre>
+ <p>For Fedora and CentOS/RHEL edit
+ <code>/etc/sysconfig/network-scripts/ifcfg-eth0</code>:</p>
+
+ <pre>BOOTPROTO=static
+IPADDR=192.168.42.11
+NETMASK=255.255.255.0
+GATEWAY=192.168.42.1
+</pre>
+
+<!-- save these for the VLAN version
+ auto eth0.926
+ iface eth0.926 inet static
+ address 10.4.144.3
+ netmask 255.255.240.0
+ #gateway 10.4.144.1
+ up ifconfig eth0.926
+
+ auto eth0.605
+ iface eth0.605 inet static
+ address 172.16.103.3
+ netmask 255.255.255.0
+ #gateway 172.16.103.1
+ up ifconfig eth0.605 up
+-->
+
+ </section>
+
+ <section id="installation">
+ <div class="page-header">
+ <h2>Installation <small>shake and bake</small></h2>
+ </div>
+
+ <h3>Add the DevStack User</h3>
+ <p>OpenStack runs as a non-root user that has sudo access to root. There is nothing special
+ about the name, we'll use <code>stack</code> here. Every node must use the same name and
+ preferably uid. If you created a user during the OS install you can use it and give it
+ sudo priviledges below. Otherwise create the stack user:</p>
+ <pre>groupadd stack
+useradd -g stack -s /bin/bash -d /opt/stack -m stack</pre>
+ <p>This user will be making many changes to your system during installation and operation
+ so it needs to have sudo priviledges to root without a password:</p>
+ <pre>echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers</pre>
+ <p>From here on use the <code>stack</code> user. <b>Logout</b> and <b>login</b> as the
+ <code>stack</code> user.</p>
+
+ <h3>Set Up Ssh</h3>
+ <p>Set up the stack user on each node with an ssh key for access:</p>
+ <pre>mkdir ~/.ssh; chmod 700 ~/.ssh
+echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyYjfgyPazTvGpd8OaAvtU2utL8W6gWC4JdRS1J95GhNNfQd657yO6s1AH5KYQWktcE6FO/xNUC2reEXSGC7ezy+sGO1kj9Limv5vrvNHvF1+wts0Cmyx61D2nQw35/Qz8BvpdJANL7VwP/cFI/p3yhvx2lsnjFE3hN8xRB2LtLUopUSVdBwACOVUmH2G+2BWMJDjVINd2DPqRIA4Zhy09KJ3O1Joabr0XpQL0yt/I9x8BVHdAx6l9U0tMg9dj5+tAjZvMAFfye3PJcYwwsfJoFxC8w/SLtqlFX7Ehw++8RtvomvuipLdmWCy+T9hIkl+gHYE4cS3OIqXH7f49jdJf jesse@spacey.local" > ~/.ssh/authorized_keys</pre>
+
+ <h3>Download DevStack</h3>
+ <p>Grab the latest version of DevStack from github:</p>
+ <pre>git clone https://github.com/openstack-dev/devstack.git
+cd devstack</pre>
+
+ <p>Up to this point all of the steps apply to each node in the cluster. From here on
+ there are some differences between the cluster controller (aka 'head node') and the
+ compute nodes.</p>
+
+ <h3>Configure Cluster Controller</h3>
+ <p>The cluster controller runs all OpenStack services. Configure the cluster controller's DevStack in <code>local.conf</code>:</p>
+ <pre>[[local|localrc]]
+HOST_IP=192.168.42.11
+FLAT_INTERFACE=eth0
+FIXED_RANGE=10.4.128.0/20
+FIXED_NETWORK_SIZE=4096
+FLOATING_RANGE=192.168.42.128/25
+MULTI_HOST=1
+LOGFILE=/opt/stack/logs/stack.sh.log
+ADMIN_PASSWORD=labstack
+MYSQL_PASSWORD=supersecret
+RABBIT_PASSWORD=supersecrete
+SERVICE_PASSWORD=supersecrete
+SERVICE_TOKEN=xyzpdqlazydog</pre>
+<!-- save for vlan
+FLAT_INTERFACE=eth0.926
+-->
+
+ <p>In the multi-node configuration the first 10 or so IPs in the private subnet are usually reserved. Add this to <code>local.sh</code> to have it run after every <code>stack.sh</code> run:</p>
+ <pre>for i in `seq 2 10`; do /opt/stack/nova/bin/nova-manage fixed reserve 10.4.128.$i; done</pre>
+
+ <p>Fire up OpenStack:</p>
+ <pre>./stack.sh</pre>
+ <p>A stream of activity ensues. When complete you will see a summary of
+ <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
+ shiny new OpenStack. The most recent log file is available in <code>stack.sh.log</code>.</p>
+
+ <h3>Configure Compute Nodes</h3>
+ <p>The compute nodes only run the OpenStack worker services. For additional machines, create a <code>local.conf</code> with:</p>
+ <pre>HOST_IP=192.168.42.12 # change this per compute node
+FLAT_INTERFACE=eth0
+FIXED_RANGE=10.4.128.0/20
+FIXED_NETWORK_SIZE=4096
+FLOATING_RANGE=192.168.42.128/25
+MULTI_HOST=1
+LOGFILE=/opt/stack/logs/stack.sh.log
+ADMIN_PASSWORD=labstack
+MYSQL_PASSWORD=supersecret
+RABBIT_PASSWORD=supersecrete
+SERVICE_PASSWORD=supersecrete
+SERVICE_TOKEN=xyzpdqlazydog
+DATABASE_TYPE=mysql
+SERVICE_HOST=192.168.42.11
+MYSQL_HOST=192.168.42.11
+RABBIT_HOST=192.168.42.11
+GLANCE_HOSTPORT=192.168.42.11:9292
+ENABLED_SERVICES=n-cpu,n-net,n-api,c-sch,c-api,c-vol</pre>
+<!-- save for vlan
+FLAT_INTERFACE=eth0.926
+-->
+
+ <p>Fire up OpenStack:</p>
+ <pre>./stack.sh</pre>
+ <p>A stream of activity ensues. When complete you will see a summary of
+ <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
+ shiny new OpenStack. The most recent log file is available in <code>stack.sh.log</code>.</p>
+
+ <h3>Cleaning Up After DevStack</h3>
+ <p>Shutting down OpenStack is now as simple as running the included <code>unstack.sh</code> script:</p>
+ <pre>./unstack.sh</pre>
+
+ <p>A more aggressive cleanup can be performed using <code>clean.sh</code>. It removes certain troublesome packages and attempts to leave the system in a state where changing the database or queue manager can be reliably performed.
+ <pre>./clean.sh</pre>
+
+ <p>Sometimes running instances are not cleaned up. DevStack attempts to do this when it
+ runs but there are times it needs to still be done by hand:</p>
+ <pre>sudo rm -rf /etc/libvirt/qemu/inst*
+sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy</pre>
+
+ </section>
+
+ <section id="options">
+ <div class="page-header">
+ <h2>Options <small>pimp your stack</small></h2>
+ </div>
+
+ <h3>Additional Users</h3>
+ <p>DevStack creates two OpenStack users (<code>admin</code> and <code>demo</code>) and two tenants (also <code>admin</code> and <code>demo</code>). <code>admin</code> is exactly what it sounds like, a priveleged administrative account that is a member of both the <code>admin</code> and <code>demo</code> tenants. <code>demo</code> is a normal user account that is only a member of the <code>demo</code> tenant. Creating additional OpenStack users can be done through the dashboard, sometimes it is easier to do them in bulk from a script, especially since they get blown away every time
+ <code>stack.sh</code> runs. The following steps are ripe for scripting:</p>
+ <pre># Get admin creds
+. openrc admin admin
+
+# List existing tenants
+keystone tenant-list
+
+# List existing users
+keystone user-list
+
+# Add a user and tenant
+NAME=bob
+PASSWORD=BigSecrete
+TENANT=$NAME
+keystone tenant-create --name=$NAME
+keystone user-create --name=$NAME --pass=$PASSWORD
+keystone user-role-add --user-id=<bob-user-id> --tenant-id=<bob-tenant-id> --role-id=<member-role-id>
+# member-role-id comes from the existing member role created by stack.sh
+# keystone role-list</pre>
+
+ <h3>Swift</h3>
+ <p>Swift requires a significant amount of resources and is disabled by default in DevStack.
+ The support in DevStack is geared toward a minimal installation but can be used for
+ testing. To implement a true multi-node test of Swift required more than DevStack provides.
+ Enabling it is as simple as enabling the <code>swift</code> service in <code>local.conf</code>:
+ <pre>enable_service swift</pre>
+
+ <p>Swift will put its data files in <code>SWIFT_DATA_DIR</code> (default <code>/opt/stack/data/swift</code>).
+ The size of the data 'partition' created (really a loop-mounted file) is set by
+ <code>SWIFT_LOOPBACK_DISK_SIZE</code>. The Swift config files are located in
+ <code>SWIFT_CONFIG_DIR</code> (default <code>/etc/swift</code>). All of these settings can be overridden in
+ (wait for it...) <code>local.conf</code>.</p>
+
+ <h3>Volumes</h3>
+ <p>DevStack will automatically use an existing LVM volume group named <code>stack-volumes</code>
+ to store cloud-created volumes. If <code>stack-volumes</code> doesn't exist, DevStack
+ will set up a 5Gb loop-mounted file to contain it. This obviously limits the
+ number and size of volumes that can be created inside OpenStack. The size can be
+ overridden by setting <code>VOLUME_BACKING_FILE_SIZE</code> in <code>local.conf</code>.</p>
+
+ <p><code>stack-volumes</code> can be pre-created on any physical volume supported by
+ Linux's LVM. The name of the volume group can be changed by setting <code>VOLUME_GROUP</code>
+ in <code>localrc</code>. <code>stack.sh</code> deletes
+ all logical volumes in <code>VOLUME_GROUP</code> that begin with
+ <code>VOLUME_NAME_PREFIX</code> as part of cleaning up from previous runs.
+ It is recommended to not use the root volume group as <code>VOLUME_GROUP</code>.</p>
+
+ <p>The details of creating the volume group depends on the server hardware involved
+ but looks something like this:</p>
+ <pre>pvcreate /dev/sdc
+vgcreate stack-volumes /dev/sdc</pre>
+
+ <h3>Syslog</h3>
+ <p>DevStack is capable of using <code>rsyslog</code> to agregate logging across the cluster.
+ It is off by default; to turn it on set <code>SYSLOG=True</code> in <code>local.conf</code>.
+ <code>SYSLOG_HOST</code> defaults to <code>HOST_IP</code>; on the compute nodes it
+ must be set to the IP of the cluster controller to send syslog output there. In the example
+ above, add this to the compute node <code>local.conf</code>:</p>
+ <pre>SYSLOG_HOST=192.168.42.11</pre>
+
+ <h3>Using Alternate Repositories/Branches</h3>
+ <p>The git repositories for all of the OpenStack services are defined in <code>stackrc</code>.
+ Since this file is a part of the DevStack package changes to it will probably be overwritten
+ as updates are applied. Every setting in <code>stackrc</code> can be redefined in
+ <code>local.conf</code>.</p>
+
+ <p>To change the repository or branch that a particular OpenStack service is created from,
+ simply change the value of <code>*_REPO</code> or <code>*_BRANCH</code> corresponding to
+ that service.</p>
+
+ <p>After making changes to the repository or branch, if <code>RECLONE</code> is not set
+ in <code>localrc</code> it may be necessary to remove the corresponding directory from
+ <code>/opt/stack</code> to force git to re-clone the repository.</p>
+
+ <p>For example, to pull Nova from a proposed release candidate in the primary Nova
+ repository:</p>
+ <pre>NOVA_BRANCH=rc-proposed</pre>
+
+ <p>To pull Glance from an experimental fork:</p>
+ <pre>GLANCE_BRANCH=try-something-big
+GLANCE_REPO=https://github.com/mcuser/glance.git</pre>
+
+ </section>
+
+ <section id="Notes">
+ <div class="page-header">
+ <h2>Notes <small>stuff you might need to know</small></h2>
+ </div>
+
+ <h3>Reset the Bridge</h3>
+ <p>How to reset the bridge configuration:</p>
+ <pre>sudo brctl delif br100 eth0.926
+sudo ip link set dev br100 down
+sudo brctl delbr br100</pre>
+<!--
+ sudo rm /etc/libvirt/qemu/*.xml
+-->
+
+ <h3>Set MySQL Password</h3>
+ <p>If you forgot to set the root password you can do this:</p>
+ <pre>mysqladmin -u root -pnova password 'supersecret'</pre>
+
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2014 — An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
diff --git a/docs/source/guides/pxe-boot.html b/docs/source/guides/pxe-boot.html
new file mode 100644
index 0000000..4dc61a3
--- /dev/null
+++ b/docs/source/guides/pxe-boot.html
@@ -0,0 +1,147 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>PXE Boot Server Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <section id="overview">
+ <h1>PXE Boot Server Guide: Magic Dust for Network Boot</h1>
+ <p>Boot DevStack from a PXE server to a RAM disk.</p>
+ </section>
+
+ <section id="requirements">
+ <div class="page-header">
+ <h2>Prerequisites <small>Hardware & OpenWRT</small></h2>
+ </div>
+
+ <h3>Hardware</h3>
+ <p>The whole point of this exercise is to have a highly portable boot server, so using a small router with a USB port is the desired platform. This guide uses a Buffalo WZR-HP-G300NH as an example, but it is easily generalized for other supported platforms. See openwrt.org for more.</p>
+
+ <h3>OpenWRT</h3>
+ <p>Any recent 'Backfire' build of OpenWRT will work for the boot server project. We build from trunk and have made the images available at <a href="http://openwrt.xr7.org/openwrt">http://openwrt.xr7.org/openwrt</a>.</p>
+ </section>
+
+ <section id="installation">
+ <div class="page-header">
+ <h2>Installation <small>bit blasting</small></h2>
+ </div>
+
+ <h3>Install the Image</h3>
+ <p>This process follows <a href="http://wiki.openwrt.org/toh/buffalo/wzr-hp-g300h">the OpenWRT doc OEM Install</a> to tftp the new image onto the router. You need a computer to set up the router, we assume it is a recent Linux or OS/X installation.</p>
+ <ul>
+ <li>Get openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin
+ <pre>wget http://openwrt.xr7.org/openwrt/ar71xx/openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
+ </li>
+ <li>Connect computer to LAN port 4 (closest to WAN port)</li>
+ <li>Set computer interface to IP address in the 192.168.11.2</li>
+ <li>Add static arp entry for router
+ <pre>arp -s 192.168.11.1 <mac-address></pre>
+ </li>
+ <li>Start TFTP transfer attempt
+ <pre>tftp 192.168.11.1
+binary
+rexmt 1
+timeout 60
+put openwrt-ar71xx-wzr-hp-g300nh-squashfs-tftp.bin</pre>
+ </li>
+ <li>Power on router. Router will reboot and initialize on 192.168.1.1.</li>
+ <li>Delete static arp entry for router
+ <pre>arp -d 192.168.11.1</pre>
+ </li>
+ <li>Set computer to DHCP, connect and telnet to router and set root password.</li>
+ </ul>
+
+ <h3>Configure the Router</h3>
+ <ul>
+ <li>Update <code>/etc/opkg.conf</code> to point to our repo:
+ <pre>src/gz packages http://192.168.5.13/openwrt/build/ar71xx/packages</pre>
+ </li>
+ <li>Configure anon mounts:
+ <pre>uci delete fstab.@mount[0]
+uci commit fstab
+/etc/init.d/fstab restart</pre>
+ </li>
+ <li>Reset the DHCP address range. DevStack will claim the upper
+ /25 of the router's LAN address space for floating IPs so the
+ default DHCP address range needs to be moved:
+ <pre>uci set dhcp.lan.start=65
+uci set dhcp.lan.limit=60
+uci commit dhcp</pre>
+ </li>
+ <li>Enable TFTP:
+ <pre>uci set dhcp.@dnsmasq[0].enable_tftp=1
+uci set dhcp.@dnsmasq[0].tftp_root=/mnt/sda1/tftpboot
+uci set dhcp.@dnsmasq[0].dhcp_boot=pxelinux.0
+uci commit dhcp
+/etc/init.d/dnsmasq restart</pre>
+ </li>
+ </ul>
+
+ <h3>Set Up tftpboot</h3>
+ <ul>
+ <li>Create the <code>/tmp/tftpboot</code> structure and populate it:
+ <pre>cd ~/devstack
+tools/build_pxe_boot.sh /tmp</pre>
+ This calls <code>tools/build_ramdisk.sh</code> to create a 2GB ramdisk
+ containing a complete development Oneiric OS plus the
+ OpenStack code checkouts.
+ </li>
+ <li>Copy <code>tftpboot</code> to a USB drive:
+ <pre>mount /dev/sdb1 /mnt/tmp
+rsync -a /tmp/tftpboot/ /mnt/tmp/tftpboot/
+umount /mnt/tmp</pre>
+ </li>
+ <li>Plug USB drive into router. It will be automounted and is ready to serve content.</li>
+ </ul>
+
+ <p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
+ off your DevStack experience.</p>
+
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2013 — this is not an official OpenStack project...</p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
diff --git a/docs/source/guides/ramdisk.html b/docs/source/guides/ramdisk.html
new file mode 100644
index 0000000..eaef16e
--- /dev/null
+++ b/docs/source/guides/ramdisk.html
@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>RAMdisk Boot Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <section id="overview">
+ <h1>Stack-in-a-Box: Try before you mkfs</h1>
+ <p>Run DevStack from a RAM disk to give it a whirl before making the
+ commitment to install it. We'll cover booting from a USB drive or
+ over the network via PXE. We'll even thow in configuring a home
+ router to handle the PXE boot. You will need a minimum of 3GB
+ for both of these configurations as the RAM disk itself is 2GB.</p>
+ </section>
+
+ <section id="requirements">
+ <div class="page-header">
+ <h2>Prerequisites <small>Hardware</small></h2>
+ </div>
+
+ <h3>USB Boot</h3>
+ <p><a href="usb-boot.html">This guide</a> covers the creation of a bootable USB drive. Your
+ computer BIOS must support booting from USB.</p>
+
+ <h3>PXE Boot</h3>
+ <p><a href="pxe-boot.html">This guide</a> covers the installation of OpenWRT on a home router
+ and configuring it as a PXE server, plus the creation of the
+ boot images and PXE support files.
+ </section>
+
+ <section id="installation">
+ <div class="page-header">
+ <h2>Installation <small>bit blasting</small></h2>
+ </div>
+
+ <h3>Install DevStack</h3>
+ <p>Grab the latest version of DevStack via https:</p>
+ <pre>sudo apt-get install git -y
+git clone https://github.com/openstack-dev/devstack.git
+cd devstack</pre>
+
+ <h3>Prepare the Boot RAMdisk</h3>
+ <p>Pick your boot method and follow the guide to prepare to build
+ the RAM disk and set up the boot process:</p>
+ <ul>
+ <li><a href="usb-boot.html">USB boot</a></li>
+ <li><a href="pxe-boot.html">PXE boot</a></li>
+ </ul>
+
+ <h3>Fire It Up</h3>
+ <ul>
+ <li>Boot the computer into the RAM disk. The details will vary from
+ machine to machine but most BIOSes have a method to select the
+ boot device, often by pressing F12 during POST.</li>
+ <li>Select 'DevStack' from the Boot Menu.</li>
+ <li>Log in with the 'stack' user and 'pass' password.</li>
+ <li>Create <code>devstack/localrc</code> if you wish to change any
+ of the configuration variables. You will probably want to at
+ least set the admin login password to something memorable rather
+ than the default 20 random characters:
+ <pre>ADMIN_PASSWORD=openstack</pre>
+ </li>
+ <li>Fire up OpenStack!
+ <pre>./run.sh</pre>
+ </li>
+ <li>See the processes running in screen:
+ <pre>screen -x</pre>
+ </li>
+ <li>Connect to the dashboard at <code>http://<ip-address>/</code></li>
+ </ul>
+
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2013 — this is not an official OpenStack project...</p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
diff --git a/docs/source/guides/single-machine.html b/docs/source/guides/single-machine.html
new file mode 100644
index 0000000..2280793
--- /dev/null
+++ b/docs/source/guides/single-machine.html
@@ -0,0 +1,131 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>Single Machine Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <section id="overview">
+ <h1>All-In-One: Dedicated Hardware</h1>
+ <p>Things are about to get real! Using OpenStack in containers or VMs is nice for kicking the tires, but doesn't compare to the feeling you get with hardware.</p>
+ </section>
+
+ <section id="prerequisites">
+ <div class="page-header">
+ <h2>Prerequisites <small>Linux & Network</small></h2>
+ </div>
+
+ <h3>Minimal Install</h3>
+ <p>You need to have a system with a fresh install of Linux. You can download the <a href="https://help.ubuntu.com/community/Installation/MinimalCD">Minimal CD</a> for Ubuntu 12.04 (only 27MB) since DevStack will download & install all the additional dependencies. The netinstall ISO is available for <a href="http://mirrors.kernel.org/fedora/releases/18/Fedora/x86_64/iso/Fedora-18-x86_64-netinst.iso">Fedora</a> and <a href="http://mirrors.kernel.org/centos/6.4/isos/x86_64/CentOS-6.4-x86_64-netinstall.iso">CentOS/RHEL</a>. You may be tempted to use a desktop distro on a laptop, it will probably work but you may need to tell Network Manager to keep its fingers off the interface(s) that OpenStack uses for bridging.</p>
+
+ <h3>Network Configuration</h3>
+ <p>Determine the network configuration on the interface used to integrate your
+ OpenStack cloud with your existing network. For example, if the IPs given out on your network
+ by DHCP are 192.168.1.X - where X is between 100 and 200 you will be able to use IPs
+ 201-254 for <b>floating ips</b>.</p>
+ <p>To make things easier later change your host to use a static IP instead of DHCP (i.e. 192.168.1.201).</p>
+ </section>
+
+ <section id="installation">
+ <div class="page-header">
+ <h2>Installation <small>shake and bake</small></h2>
+ </div>
+
+ <h3>Add your user</h3>
+ <p>We need to add a user to install DevStack. (if you created a user during install you can skip this step and just give the user sudo priviledges below)</p>
+ <pre>adduser stack</pre>
+ <p>Since this user will be making many changes to your system, it will need to have sudo priviledges:</p>
+ <pre>apt-get install sudo -y || yum install -y sudo
+echo "stack ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers</pre>
+ <p>From here on you should use the user you created. <b>Logout</b> and <b>login</b> as that user.</p>
+
+ <h3>Download DevStack</h3>
+ <p>We'll grab the latest version of DevStack via https:</p>
+ <pre>sudo apt-get install git -y || yum install -y git
+git clone https://github.com/openstack-dev/devstack.git
+cd devstack</pre>
+
+ <h3>Run DevStack</h3>
+ <p>Now to configure <code>stack.sh</code>. DevStack includes a sample in <code>devstack/samples/local.conf</code>. Create <code>local.conf</code> as shown below to do the following:</p>
+ <ul>
+ <li>Set <code>FLOATING_RANGE</code> to a range not used on the local network, i.e. 192.168.1.224/27. This configures IP addresses ending in 225-254 to be used as floating IPs.</li>
+ <li>Set <code>FIXED_RANGE</code> and <code>FIXED_NETWORK_SIZE</code> to configure the internal address space used by the instances.</li>
+ <li>Set <code>FLAT_INTERFACE</code> to the Ethernet interface that connects the host to your local network. This is the interface that should be configured with the static IP address mentioned above.</li>
+ <li>Set the administrative password. This password is used for the <b>admin</b> and <b>demo</b> accounts set up as OpenStack users.</li>
+ <li>Set the MySQL administrative password. The default here is a random hex string which is inconvenient if you need to look at the database directly for anything.</li>
+ <li>Set the RabbitMQ password.</li>
+ <li>Set the service password. This is used by the OpenStack services (Nova, Glance, etc) to authenticate with Keystone.</li>
+ </ul>
+ <p><code>local.conf</code> should look something like this:</p>
+ <pre>[[local|localrc]]
+FLOATING_RANGE=192.168.1.224/27
+FIXED_RANGE=10.11.12.0/24
+FIXED_NETWORK_SIZE=256
+FLAT_INTERFACE=eth0
+ADMIN_PASSWORD=supersecret
+MYSQL_PASSWORD=iheartdatabases
+RABBIT_PASSWORD=flopsymopsy
+SERVICE_PASSWORD=iheartksl</pre>
+
+ <p>Run DevStack:</p>
+ <pre>./stack.sh</pre>
+ <p>A seemingly endless stream of activity ensues. When complete you will see a summary of
+ <code>stack.sh</code>'s work, including the relevant URLs, accounts and passwords to poke at your
+ shiny new OpenStack.</p>
+
+ <h3>Using OpenStack</h3>
+ <p>At this point you should be able to access the dashboard from other computers on the
+ local network. In this example that would be http://192.168.1.201/ for the dashboard (aka Horizon).
+ Launch VMs and if you give them floating IPs and security group access those VMs will be accessable from other machines on your network.</p>
+
+ <p>Some examples of using the OpenStack command-line clients <code>nova</code> and <code>glance</code>
+ are in the shakedown scripts in <code>devstack/exercises</code>. <code>exercise.sh</code>
+ will run all of those scripts and report on the results.</p>
+
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2013 — An <a href="https://wiki.openstack.org/wiki/Programs">OpenStack program</a> created by <a href="http://www.rackspace.com/cloud/private_edition/">Rackspace Cloud Builders</a></p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
diff --git a/docs/source/guides/single-vm.html b/docs/source/guides/single-vm.html
new file mode 100644
index 0000000..2f1990a
--- /dev/null
+++ b/docs/source/guides/single-vm.html
@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>Single Machine Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <section id="overview">
+ <h1>Running a Cloud in a VM</h1>
+ <p>Use the cloud to build the cloud! Use your cloud to launch new versions of OpenStack
+ in about 5 minutes. When you break it, start over! The VMs launched in the cloud will
+ be slow as they are running in QEMU (emulation), but their primary use is testing
+ OpenStack development and operation. Speed not required.</p>
+ </section>
+
+ <section id="prerequisites">
+ <div class="page-header">
+ <h2>Prerequisites <small>Cloud & Image</small></h2>
+ </div>
+
+ <h3>Virtual Machine</h3>
+ <p>DevStack should run in any virtual machine running a supported Linux release. It will perform best with 2Gb or more of RAM.</p>
+
+ <h3>OpenStack Deployment & cloud-init</h3>
+ <p>If the cloud service has an image with <code>cloud-init</code> pre-installed, use it. You can
+ get one from <a href="http://uec-images.ubuntu.com">Ubuntu's Daily Build</a>
+ site if necessary. This will enable you to launch VMs with userdata that installs
+ everything at boot time. The userdata script below will install and run
+ DevStack with a minimal configuration. The use of <code>cloud-init</code>
+ is outside the scope of this document, refer to <a href"http://cloudinit.readthedocs.org/en/latest/index.html">the
+ <code>cloud-init</code> docs</a> for more information.</p>
+
+ <p>If you are directly using a hypervisor like Xen, kvm or VirtualBox you can manually kick off
+ the script below as a non-root user in a bare-bones server installation.</p>
+ </section>
+
+ <section id="requirements">
+ <div class="page-header">
+ <h2>Installation <small>shake and bake</small></h2>
+ </div>
+
+ <h3>Launching With Cloud-Init</h3>
+ <p>This cloud config grabs the latest version of DevStack via git, creates a minimal
+ <code>local.conf</code> file and kicks off <code>stack.sh</code>. It should
+ be passed as the user-data file when booting the VM.</p>
+ <pre>#cloud-config
+
+users:
+ - default
+ - name: stack
+ lock_passwd: False
+ sudo: ["ALL=(ALL) NOPASSWD:ALL\nDefaults:stack !requiretty"]
+ shell: /bin/bash
+
+write_files:
+ - content: |
+ #!/bin/sh
+ DEBIAN_FRONTEND=noninteractive sudo apt-get -qqy update || sudo yum update -qy
+ DEBIAN_FRONTEND=noninteractive sudo apt-get install -qqy git || sudo yum install -qy git
+ sudo chown stack:stack /home/stack
+ cd /home/stack
+ git clone https://github.com/openstack-dev/devstack.git
+ cd devstack
+ echo '[[local|localrc]]' > local.conf
+ echo ADMIN_PASSWORD=password >> local.conf
+ echo MYSQL_PASSWORD=password >> local.conf
+ echo RABBIT_PASSWORD=password >> local.conf
+ echo SERVICE_PASSWORD=password >> local.conf
+ echo SERVICE_TOKEN=tokentoken >> local.conf
+ ./stack.sh
+ path: /home/stack/start.sh
+ permissions: 0755
+
+runcmd:
+ - su -l stack ./start.sh</pre>
+ <p>As DevStack will refuse to run as root, this configures <code>cloud-init</code>
+ to create a non-root user and run the <code>start.sh</code> script as that user.</p>
+
+ <h3>Launching By Hand</h3>
+ <p>Using a hypervisor directly, launch the VM and either manually perform the steps in the
+ embedded shell script above or copy it into the VM.</p>
+
+ <h3>Using OpenStack</h3>
+ <p>At this point you should be able to access the dashboard. Launch VMs and if you give them floating IPs access those VMs from other machines on your network.</p>
+
+ <p>One interesting use case is for developers working on a VM on their laptop. Once
+ <code>stack.sh</code> has completed once, all of the pre-requisite packages are installed
+ in the VM and the source trees checked out. Setting <code>OFFLINE=True</code> in
+ <code>local.conf</code> enables <code>stack.sh</code> to run multiple times without an Internet
+ connection. DevStack, making hacking at the lake possible since 2012!</p>
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2014 — An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>
diff --git a/docs/source/guides/usb-boot.html b/docs/source/guides/usb-boot.html
new file mode 100644
index 0000000..75adc6f
--- /dev/null
+++ b/docs/source/guides/usb-boot.html
@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <title>USB Boot Server Guide - DevStack</title>
+ <meta name="description" content="">
+ <meta name="author" content="">
+
+ <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
+ <!--[if lt IE 9]>
+ <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+ <![endif]-->
+
+ <!-- Le styles -->
+ <link href="../assets/css/bootstrap.css" rel="stylesheet">
+ <link href="../assets/css/local.css" rel="stylesheet">
+ <style type="text/css">
+ body { padding-top: 60px; }
+ dd { padding: 10px; }
+ </style>
+
+ <!-- Le javascripts -->
+ <script src="../assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
+ <script src="../assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
+ </head>
+
+ <body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="/">DevStack</a>
+ <ul class="nav pull-right">
+ <li><a href="../overview.html">Overview</a></li>
+ <li><a href="../changes.html">Changes</a></li>
+ <li><a href="../faq.html">FAQ</a></li>
+ <li><a href="http://github.com/openstack-dev/devstack">GitHub</a></li>
+ <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <section id="overview">
+ <h1>USB Boot: Undoable Stack Boot</h1>
+ <p>Boot DevStack from a USB disk into a RAM disk.</p>
+ </section>
+
+ <section id="requirements">
+ <div class="page-header">
+ <h2>Prerequisites</h2>
+ </div>
+
+ <h3>Hardware</h3>
+ <p>This guide covers the creation of a bootable USB drive. Your
+ computer BIOS must support booting from USB and You will want at least 3GB of
+ RAM. You also will need a USB drive of at least 2GB.</p>
+
+ <h3>Software</h3>
+ <p>Ubuntu 11.10 (Oneiric Ocelot) is required on host to create images.</p>
+ </section>
+
+ <section id="installation">
+ <div class="page-header">
+ <h2>Installation <small>bit blasting</small></h2>
+ </div>
+
+ <h3>Set Up USB Drive</h3>
+ <ul>
+ <li>Insert the USB drive into the computer. Make a note of the device name, such as
+ <code>sdb</code>. Do not mount the device.</li>
+ <li>Install the boot system:
+ <pre>tools/build_usb_boot.sh /dev/sdb1</pre>
+ <p>This calls tools/build_ramdisk.sh to create a 2GB ramdisk
+ containing a complete development Oneiric OS plus the
+ OpenStack code checkouts. It then writes a syslinux boot sector
+ to the specified device and creates <code>/syslinux</code>.</p>
+ </li>
+ <li>If desired, you may now mount the device:
+ <pre>mount /dev/sdb1 /mnt/tmp
+# foo
+umount /mnt/tmp</pre>
+ </li>
+ </ul>
+
+ <p>Now <a href="ramdisk.html">return</a> to the RAM disk Guide to kick
+ off your DevStack experience.</p>
+
+ </section>
+
+ <footer>
+ <p>© Openstack Foundation 2011-2013 — this is not an official OpenStack project...</p>
+ </footer>
+
+ </div> <!-- /container -->
+
+ </body>
+</html>