diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/livecd.rst | 65 | ||||
| -rw-r--r-- | doc/source/quickstart.rst | 148 | ||||
| -rw-r--r-- | doc/source/runnova/getting.started.rst | 167 | ||||
| -rw-r--r-- | doc/source/runnova/index.rst | 2 |
4 files changed, 6 insertions, 376 deletions
diff --git a/doc/source/livecd.rst b/doc/source/livecd.rst deleted file mode 100644 index 37c92c8bc..000000000 --- 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 2dbbb7200..8fa47e3fa 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 <http://devstack.org/>`_. -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 <http://docs.openstack.org/openstack-compute/admin/content/ch03.html>`_). - -* 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 - -:: - - <ctrl-a> " - -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 - -:: - - <ctrl-a> <ctrl-d> - -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 dc0761d36..000000000 --- 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 <http://code.launchpad.net/nova>`_ -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 <http://docs.openstack.org/openstack-compute/admin/content/ch03.html>`_. - -`Detailed instructions for creating a volume group are available <http://docs.openstack.org/openstack-compute/admin/content/ch05s07.html>`_, 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-<servicename> --help, or refer to a static list at `Reference for Flags in nova.conf <http://docs.openstack.org/openstack-compute/admin/content/ch05s08.html>`_. - -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 <http://docs.openstack.org/openstack-compute/admin/content/ch03.html>`_. - -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 769bbec84..68da288ae 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`. |