diff --git a/contrib/nova.sh b/contrib/nova.sh deleted file mode 100755 index 16cddebd5d52..000000000000 --- a/contrib/nova.sh +++ /dev/null @@ -1,234 +0,0 @@ -#!/usr/bin/env bash -DIR=`pwd` -CMD=$1 -if [ "$CMD" = "branch" ]; then - SOURCE_BRANCH=${2:-lp:nova} - DIRNAME=${3:-nova} -else - DIRNAME=${2:-nova} -fi - -NOVA_DIR=$DIR/$DIRNAME - -if [ ! -n "$HOST_IP" ]; then - # NOTE(vish): This will just get the first ip in the list, so if you - # have more than one eth device set up, this will fail, and - # you should explicitly set HOST_IP in your environment - HOST_IP=`LC_ALL=C ifconfig | grep -m 1 'inet addr:'| cut -d: -f2 | awk '{print $1}'` -fi - -USE_MYSQL=${USE_MYSQL:-1} -INTERFACE=${INTERFACE:-eth0} -FLOATING_RANGE=${FLOATING_RANGE:-10.6.0.0/27} -FIXED_RANGE=${FIXED_RANGE:-10.0.0.0/24} -MYSQL_PASS=${MYSQL_PASS:-nova} -TEST=${TEST:-0} -USE_LDAP=${USE_LDAP:-0} -# Use OpenDJ instead of OpenLDAP when using LDAP -USE_OPENDJ=${USE_OPENDJ:-0} -# Use IPv6 -USE_IPV6=${USE_IPV6:-0} -LIBVIRT_TYPE=${LIBVIRT_TYPE:-qemu} -NET_MAN=${NET_MAN:-VlanManager} -# NOTE(vish): If you are using FlatDHCP on multiple hosts, set the interface -# below but make sure that the interface doesn't already have an -# ip or you risk breaking things. -# FLAT_INTERFACE=eth0 - -if [ "$USE_MYSQL" == 1 ]; then - SQL_CONN=mysql://root:$MYSQL_PASS@localhost/nova -else - SQL_CONN=sqlite:///$NOVA_DIR/nova.sqlite -fi - -if [ "$USE_LDAP" == 1 ]; then - AUTH=ldapdriver.LdapDriver -else - AUTH=dbdriver.DbDriver -fi - -if [ "$CMD" == "branch" ]; then - sudo apt-get install -y bzr - if [ ! -e "$DIR/.bzr" ]; then - bzr init-repo $DIR - fi - rm -rf $NOVA_DIR - bzr branch $SOURCE_BRANCH $NOVA_DIR - cd $NOVA_DIR - mkdir -p $NOVA_DIR/instances - mkdir -p $NOVA_DIR/networks - exit -fi - -# You should only have to run this once -if [ "$CMD" == "install" ]; then - sudo apt-get install -y python-software-properties - sudo add-apt-repository ppa:nova-core/trunk - sudo apt-get update - sudo apt-get install -y dnsmasq-base kpartx kvm gawk iptables ebtables - sudo apt-get install -y user-mode-linux kvm libvirt-bin - sudo apt-get install -y screen euca2ools vlan curl rabbitmq-server - sudo apt-get install -y lvm2 iscsitarget open-iscsi - sudo apt-get install -y socat unzip - echo "ISCSITARGET_ENABLE=true" | sudo tee /etc/default/iscsitarget - sudo /etc/init.d/iscsitarget restart - sudo modprobe kvm - sudo /etc/init.d/libvirt-bin restart - sudo modprobe nbd - sudo apt-get install -y python-mox python-ipy python-paste - sudo apt-get install -y python-migrate python-gflags python-greenlet - sudo apt-get install -y python-libvirt python-libxml2 python-routes - sudo apt-get install -y python-netaddr python-pastedeploy python-eventlet - sudo apt-get install -y python-novaclient python-glance python-cheetah - sudo apt-get install -y python-carrot python-tempita python-sqlalchemy - sudo apt-get install -y python-suds python-kombu - - - if [ "$USE_IPV6" == 1 ]; then - sudo apt-get install -y radvd - sudo bash -c "echo 1 > /proc/sys/net/ipv6/conf/all/forwarding" - sudo bash -c "echo 0 > /proc/sys/net/ipv6/conf/all/accept_ra" - fi - - if [ "$USE_MYSQL" == 1 ]; then - cat <$NOVA_DIR/bin/nova.conf << NOVA_CONF_EOF ---verbose ---nodaemon ---dhcpbridge_flagfile=$NOVA_DIR/bin/nova.conf ---network_manager=nova.network.manager.$NET_MAN ---my_ip=$HOST_IP ---public_interface=$INTERFACE ---vlan_interface=$INTERFACE ---sql_connection=$SQL_CONN ---auth_driver=nova.auth.$AUTH ---libvirt_type=$LIBVIRT_TYPE -NOVA_CONF_EOF - - if [ -n "$FLAT_INTERFACE" ]; then - echo "--flat_interface=$FLAT_INTERFACE" >>$NOVA_DIR/bin/nova.conf - fi - - if [ "$USE_IPV6" == 1 ]; then - echo "--use_ipv6" >>$NOVA_DIR/bin/nova.conf - fi - - killall dnsmasq - if [ "$USE_IPV6" == 1 ]; then - killall radvd - fi - screen -d -m -S nova -t nova - sleep 1 - if [ "$USE_MYSQL" == 1 ]; then - mysql -p$MYSQL_PASS -e 'DROP DATABASE nova;' - mysql -p$MYSQL_PASS -e 'CREATE DATABASE nova;' - else - rm $NOVA_DIR/nova.sqlite - fi - if [ "$USE_LDAP" == 1 ]; then - if [ "$USE_OPENDJ" == 1 ]; then - echo '--ldap_user_dn=cn=Directory Manager' >> \ - /etc/nova/nova-manage.conf - sudo $NOVA_DIR/nova/auth/opendj.sh - else - sudo $NOVA_DIR/nova/auth/slap.sh - fi - fi - rm -rf $NOVA_DIR/instances - mkdir -p $NOVA_DIR/instances - rm -rf $NOVA_DIR/networks - mkdir -p $NOVA_DIR/networks - if [ "$TEST" == 1 ]; then - cd $NOVA_DIR - python $NOVA_DIR/run_tests.py - cd $DIR - fi - - # create the database - $NOVA_DIR/bin/nova-manage db sync - # create an admin user called 'admin' - $NOVA_DIR/bin/nova-manage user admin admin admin admin - # create a project called 'admin' with project manager of 'admin' - $NOVA_DIR/bin/nova-manage project create admin admin - # create a small network - $NOVA_DIR/bin/nova-manage network create $FIXED_RANGE 1 32 - - # create some floating ips - $NOVA_DIR/bin/nova-manage floating create `hostname` $FLOATING_RANGE - - if [ ! -d "$NOVA_DIR/images" ]; then - if [ ! -d "$DIR/converted-images" ]; then - # convert old images - mkdir $DIR/converted-images - ln -s $DIR/converted-images $NOVA_DIR/images - $NOVA_DIR/bin/nova-manage image convert $DIR/images - else - ln -s $DIR/converted-images $NOVA_DIR/images - fi - - fi - - - # nova api crashes if we start it with a regular screen command, - # so send the start command by forcing text into the window. - screen_it api "$NOVA_DIR/bin/nova-api" - screen_it objectstore "$NOVA_DIR/bin/nova-objectstore" - screen_it compute "$NOVA_DIR/bin/nova-compute" - screen_it network "$NOVA_DIR/bin/nova-network" - screen_it scheduler "$NOVA_DIR/bin/nova-scheduler" - screen_it volume "$NOVA_DIR/bin/nova-volume" - screen_it ajax_console_proxy "$NOVA_DIR/bin/nova-ajax-console-proxy" - sleep 2 - # export environment variables for project 'admin' and user 'admin' - $NOVA_DIR/bin/nova-manage project zipfile admin admin $NOVA_DIR/nova.zip - unzip -o $NOVA_DIR/nova.zip -d $NOVA_DIR/ - - screen_it test "export PATH=$NOVA_DIR/bin:$PATH;. $NOVA_DIR/novarc" - if [ "$CMD" != "run_detached" ]; then - screen -S nova -x - fi -fi - -if [ "$CMD" == "run" ] || [ "$CMD" == "terminate" ]; then - # shutdown instances - . $NOVA_DIR/novarc; euca-describe-instances | grep i- | cut -f2 | xargs euca-terminate-instances - sleep 2 - # delete volumes - . $NOVA_DIR/novarc; euca-describe-volumes | grep vol- | cut -f2 | xargs -n1 euca-delete-volume - sleep 2 -fi - -if [ "$CMD" == "run" ] || [ "$CMD" == "clean" ]; then - screen -S nova -X quit - rm *.pid* -fi - -if [ "$CMD" == "scrub" ]; then - $NOVA_DIR/tools/clean-vlans - if [ "$LIBVIRT_TYPE" == "uml" ]; then - virsh -c uml:///system list | grep i- | awk '{print \$1}' | xargs -n1 virsh -c uml:///system destroy - else - virsh list | grep i- | awk '{print \$1}' | xargs -n1 virsh destroy - fi -fi diff --git a/doc/.gitignore b/doc/.gitignore index 88f9974bd731..291b04e45dde 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1 +1,3 @@ _build/* +source/api/* +.autogenerated diff --git a/doc/source/livecd.rst b/doc/source/livecd.rst deleted file mode 100644 index 37c92c8bca6a..000000000000 --- a/doc/source/livecd.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. - Copyright 2010-2011 OpenStack LLC - - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Installing the Live CD -====================== - -If you'd like to set up a sandbox installation of Nova, you can use one of these Live CD images. - -If you don't already have VirtualBox installed, you can download it from http://www.virtualbox.org/wiki/Downloads. - -Download the zip or iso file and then follow these steps to try Nova in a virtual environment. - -http://c0047913.cdn1.cloudfiles.rackspacecloud.com/OpenStackNova.x86_64-2010.1.2.iso (OpenSUSE image; root password is "linux" for this image) - -http://c0028699.cdn1.cloudfiles.rackspacecloud.com/nova-vm.zip (~900 MB) (log in information is nova/nova) - -Once a VM is configured and started, here are the basics: - - #. Login to Ubuntu using ID nova and Password nova. - - #. Switch to running as sudo (enter nova when prompted for the password):: - - sudo -s - - #. To run Nova for the first time, enter:: - - cd /var/openstack/ - - #. Now that you're in the correct directory, enter:: - - ./nova.sh run - - .. image:: images/novashvirtually.png - -If it's already running, use screen -ls, and when the nova screen is presented,then enter screen -d -r nova. - -These are the steps to get an instance running (the image is already provided in this environment). Enter these commands in the "test" screen. - -:: - - euca-add-keypair test > test.pem - chmod 600 test.pem - euca-run-instances -k test -t m1.tiny ami-tiny - euca-describe-instances - - ssh -i test.pem root@10.0.0.3 - -To see output from the various workers, switch screen windows with Ctrl+A " (quotation mark). - - .. image:: images/novascreens.png - diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 2dbbb72002cb..8fa47e3fa60b 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -18,147 +18,9 @@ Nova Quickstart =============== -.. todo:: - P1 (this is one example of how to use priority syntax) - * Document the assumptions about pluggable interfaces (sqlite3 instead of - mysql, etc) (todd) - * Document env vars that can change things (USE_MYSQL, HOST_IP) (todd) +The quickest way to set up an OpenStack development environment for testing is +to use `DevStack `_. -Recommended System Configuration --------------------------------- - -Although Nova can be run on a variety of system architectures, for most users the following will be simplest: - -* Ubuntu Lucid -* 10GB Hard Disk Space -* 512MB RAM - -For development, Nova can run from within a VM. - - -Getting the Code ----------------- - -Nova is hosted on launchpad. You can get the code with the following command - -:: - - git clone https://github.com/openstack/nova.git - -The `contrib/nova.sh` file in the source distribution is a script that -will quickly set up nova to run on a single machine. It is tested against -Ubuntu only, but other distributions are forthcoming. - -A more recent shell script for setting up an OpenStack development environment -can be found at http://devstack.org - -Environment Variables ---------------------- - -By tweaking the environment that nova.sh run in, you can build slightly -different configurations (though for more complex setups you should see -`Installing and Configuring OpenStack Compute `_). - -* HOST_IP - * Default: address of first interface from the ifconfig command - * Values: 127.0.0.1, or any other valid address -* TEST - * Default: 0 - * Values: 1, run tests after checkout and initial setup -* USE_MYSQL - * Default: 0, use sqlite3 - * Values: 1, use mysql instead of sqlite3 -* MYSQL_PASS (Only useful if $USE_MYSQL=1) - * Default: nova - * Values: value of root password for mysql -* USE_LDAP - * Default: 0, use :mod:`nova.auth.dbdriver` - * Values: 1, use :mod:`nova.auth.ldapdriver` -* LIBVIRT_TYPE - * Default: qemu - * Values: uml, kvm - -Usage ------ - -Unless you want to spend a lot of time fiddling with permissions and sudoers, -you should probably run nova as root. - -:: - - sudo -i - -If you are concerned about security, nova runs just fine inside a virtual -machine. - -Use the script to install and run the current trunk. You can also specify a -specific branch by putting `lp:~someone/nova/some-branch` after the branch -command - -:: - - ./nova.sh branch - ./nova.sh install - ./nova.sh run - -The run command will drop you into a screen session with all of the workers -running in different windows You can use eucatools to run commands against the -cloud. - -:: - - euca-add-keypair test > test.pem - euca-run-instances -k test -t m1.tiny ami-tiny - euca-describe-instances - -To see output from the various workers, switch screen windows - -:: - - " - -will give you a list of running windows. - -When the instance is running, you should be able to ssh to it. - -:: - - chmod 600 test.pem - ssh -i test.pem root@10.0.0.3 - -When you exit screen - -:: - - - -nova will terminate. It may take a while for nova to finish cleaning up. If -you exit the process before it is done because there were some problems in your -build, you may have to clean up the nova processes manually. If you had any -instances running, you can attempt to kill them through the api: - -:: - - ./nova.sh terminate - -Then you can destroy the screen: - -:: - - ./nova.sh clean - -If things get particularly messed up, you might need to do some more intense -cleanup. Be careful, the following command will manually destroy all runnning -virsh instances and attempt to delete all vlans and bridges. - -:: - - ./nova.sh scrub - -You can edit files in the install directory or do a git pull to pick up new versions. You only need to do - -:: - - ./nova.sh run - -to run nova after the first install. The database should be cleaned up on each run. \ No newline at end of file +To start over, drop the nova, glance, and keystone databases, delete the logs, +delete the IP addresses and bridges created, and then recreate the databases +and restart the services to get back to a clean state. diff --git a/doc/source/runnova/getting.started.rst b/doc/source/runnova/getting.started.rst deleted file mode 100644 index dc0761d36c9d..000000000000 --- a/doc/source/runnova/getting.started.rst +++ /dev/null @@ -1,167 +0,0 @@ -.. - Copyright 2010-2011 United States Government as represented by the - Administrator of the National Aeronautics and Space Administration. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Getting Started with Nova -========================= - -This code base is continually changing, so dependencies also change. If you -encounter any problems, see the :doc:`../community` page. -The `contrib/nova.sh` script should be kept up to date, and may be a good -resource to review when debugging. - -The purpose of this document is to get a system installed that you can use to -test your setup assumptions. Working from this base installtion you can -tweak configurations and work with different flags to monitor interaction with -your hardware, network, and other factors that will allow you to determine -suitability for your deployment. After following this setup method, you should -be able to experiment with different managers, drivers, and flags to get the -best performance. - -Dependencies ------------- - -Related servers we rely on - -* **RabbitMQ**: messaging queue, used for all communication between components - -Optional servers - -* **OpenLDAP**: By default, the auth server uses the RDBMS-backed datastore by - setting FLAGS.auth_driver to `nova.auth.dbdriver.DbDriver`. But OpenLDAP - (or LDAP) could be configured by specifying `nova.auth.ldapdriver.LdapDriver`. - There is a script in the sources (`nova/auth/slap.sh`) to install a very basic - openldap server on ubuntu. -* **ReDIS**: There is a fake ldap auth driver - `nova.auth.ldapdriver.FakeLdapDriver` that backends to redis. This was - created for testing ldap implementation on systems that don't have an easy - means to install ldap. -* **MySQL**: Either MySQL or another database supported by sqlalchemy needs to - be avilable. Currently, only sqlite3 an mysql have been tested. - -Python libraries that we use (from pip-requires): - -.. literalinclude:: ../../../tools/pip-requires - -Other libraries: - -* **XenAPI**: Needed only for Xen Cloud Platform or XenServer support. Available - from http://wiki.xensource.com/xenwiki/XCP_SDK or - http://community.citrix.com/cdn/xs/sdks. - -External unix tools that are required: - -* iptables -* ebtables -* gawk -* curl -* kvm -* libvirt -* dnsmasq -* vlan -* open-iscsi and iscsitarget (if you use iscsi volumes) - -Nova uses cutting-edge versions of many packages. There are ubuntu packages in -the nova-core trunk ppa. You can use add this ppa to your sources list on an -ubuntu machine with the following commands:: - - sudo apt-get install -y python-software-properties - sudo add-apt-repository ppa:nova-core/trunk - -Recommended ------------ - -* euca2ools: python implementation of aws ec2-tools and ami tools -* build tornado to use C module for evented section - - -Installation --------------- - -You can install from packages for your particular Linux distribution if they are -available. Otherwise you can install from source by checking out the source -files from the `Nova Source Code Repository `_ -and running:: - - python setup.py install - -Configuration ---------------- - -Configuring the host system -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Nova can be configured in many different ways. In this "Getting Started with Nova" document, we only provide what you need to get started as quickly as possible. For a more detailed description of system -configuration, start reading through `Installing and Configuring OpenStack Compute `_. - -`Detailed instructions for creating a volume group are available `_, or use these quick instructions. - -* Create a volume group (you can use an actual disk for the volume group as - well):: - - # This creates a 1GB file to create volumes out of - dd if=/dev/zero of=MY_FILE_PATH bs=100M count=10 - losetup --show -f MY_FILE_PATH - # replace /dev/loop0 below with whatever losetup returns - # nova-volumes is the default for the --volume_group flag - vgcreate nova-volumes /dev/loop0 - - -Configuring Nova -~~~~~~~~~~~~~~~~ - -Configuration of the entire system is performed through python-gflags. The -best way to track configuration is through the use of a flagfile. - -A flagfile is specified with the ``--flagfile=FILEPATH`` argument to the binary -when you launch it. Flagfiles for nova are typically stored in -``/etc/nova/nova.conf``, and flags specific to a certain program are stored in -``/etc/nova/nova-COMMAND.conf``. Each configuration file can include another -flagfile, so typically a file like ``nova-manage.conf`` would have as its first -line ``--flagfile=/etc/nova/nova.conf`` to load the common flags before -specifying overrides or additional options. - -To get a current comprehensive list of flag file options, run bin/nova- --help, or refer to a static list at `Reference for Flags in nova.conf `_. - -A sample configuration to test the system follows:: - - --verbose - --nodaemon - --auth_driver=nova.auth.dbdriver.DbDriver - -Running -------- - -There are many parts to the nova system, each with a specific function. They -are built to be highly-available, so there are may configurations they can be -run in (ie: on many machines, many listeners per machine, etc). This part -of the guide only gets you started quickly, to learn about HA options, see -`Installing and Configuring OpenStack Compute `_. - -Launch supporting services - -* rabbitmq -* redis (optional) -* mysql (optional) -* openldap (optional) - -Launch nova components, each should have ``--flagfile=/etc/nova/nova.conf`` - -* nova-api -* nova-compute -* nova-objectstore -* nova-volume -* nova-scheduler diff --git a/doc/source/runnova/index.rst b/doc/source/runnova/index.rst index 769bbec847c0..68da288ae79a 100644 --- a/doc/source/runnova/index.rst +++ b/doc/source/runnova/index.rst @@ -23,7 +23,7 @@ This guide describes the basics of running and managing Nova. This site is inten Running the Cloud ----------------- -The fastest way to get a test cloud running is by following the directions in the :doc:`../quickstart`. It relies on a nova.sh script to run on a single machine. +The fastest way to get a test cloud running is by following the directions in the :doc:`../quickstart`. Nova's cloud works via the interaction of a series of daemon processes that reside persistently on the host machine(s). Fortunately, the :doc:`../quickstart` process launches sample versions of all these daemons for you. Once you are familiar with basic Nova usage, you can learn more about daemons by reading :doc:`../service.architecture` and :doc:`binaries`.