Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Working on new admin walkthrough document

  • Loading branch information...
commit 5f794cbc5aaf7a27c2a1e25cfd9ca8c20b46d8ef 1 parent 0d07e2e
@labisso labisso authored
Showing with 335 additions and 0 deletions.
  1. +335 −0 docs/src/admin/walkthrough.html
View
335 docs/src/admin/walkthrough.html
@@ -0,0 +1,335 @@
+m4_include(/mcs/m4/worksp.lib.m4)
+_NIMBUS_HEADER(2.6 Admin Walkthrough)
+_NIMBUS_HEADER2(n,n,y,n,n,n,n)
+_NIMBUS_LEFT2_COLUMN
+_NIMBUS_LEFT2_ADMIN_SIDEBAR(n,n,n,n,n)
+_NIMBUS_LEFT2_COLUMN_END
+_NIMBUS_CENTER2_COLUMN
+_NIMBUS_IS_DEPRECATED
+
+
+<h2>Nimbus 2.6 Administrator Walkthrough</h2>
+
+<p>
+ This guide provides a hands-on overview of Nimbus administrative functionality.
+ It is intended to give new and prospective users a feel for the features and
+ philosophy behind Nimbus. It is complementary to the
+ <a href="z2c/">Zero to Cloud Guide</a> and the
+ <a href="reference.html">reference manual</a>. It steps through a simple install
+ of the <em>service node</em> but doesn't cover configuring backend nodes.
+ It then demonstrates some administrative tools and procedures.
+</p>
+
+<a name="install"> </a>
+<h3>Installation _NAMELINK(install)</h3>
+
+<p>
+ The first step is to make a basic installation of the Nimbus services. Since
+ we are just messing around, we will install to a temporary location,
+ <tt class="literal">/tmp/nimbus</tt>. The installer
+ will place all files in this location and will not affect any other part of
+ your system. You can install to any path you like, just make sure to adjust
+ the example commands in this document appropriately. You do not need to be
+ <tt class="literal">root</tt> to install and run the Nimbus services.
+</p>
+
+<p>
+ Before you proceed, make sure your system has the required dependencies. These
+ are detailed in the <a href="z2c/service-dependencies.html">Service Dependencies</a>
+ page of the Zero to Cloud guide.
+ The short version is: Java 1.5+, Python 2.5+ plus development headers
+ (but not Python 3.x), Apache ant, and gcc.
+</p>
+
+<p>
+ First download and unpack the Nimbus service source package:
+</p>
+
+<pre class="panel">
+$ wget http://www.nimbusproject.org/downloads/nimbus-2.6-src.tar.gz
+$ tar xzf nimbus-2.6-src.tar.gz
+$ cd nimbus-2.6-src/
+</pre>
+
+<p>
+ Now run the installer, specifying the destination directory as an argument.
+</p>
+
+<pre class="panel">
+$ ./install /tmp/nimbus
+</pre>
+
+<div class="note">
+ <p class="note-title">Installer Undo</p>
+ <p>
+ If the installer fails, perhaps because of a missing dependency, make sure
+ to remove your destination directory if it was created:
+ </p>
+ <pre class="panel">
+rm -fr /tmp/nimbus
+</pre>
+ <p>
+ This will ensure that once you resolve the problem, the installation will
+ not conflict with the earlier failed install.
+ </p>
+</div>
+
+<p>
+ The installation will take a minute or two and you will be asked a couple of questions at
+ the end.
+</p>
+
+<pre class="panel">
+-----------------------------------------------------------------
+ Configuring installed services
+-----------------------------------------------------------------
+
+Nimbus uses an internal Certificate Authority (CA) for some services. This CA
+is also used to generate host and user certificates if you do not have your own.
+
+This CA will be created in /tmp/nimbus/var/ca
+
+Please pick a unique, one word CA name or hit ENTER to use a UUID.
+
+For example, if you are installing this on the "Jupiter" cluster, you might use
+"JupiterNimbusCA" as the name.
+
+CA Name:
+You did not enter a name, using 'ab75d05b-87ae-4f60-9b4c-c32d207d1f29'
+</pre>
+
+<p>
+ This gives you a chance to customize the name of your certificate authority.
+ For the purposes of this tutorial you can just press <strong>[Enter]</strong> and let
+ the installer pick a unique name for you.
+</p>
+
+<p>
+ The next question asks you for the hostname you would like to use. It is important
+ that this is correct because it is used internally by Nimbus. In most cases the
+ installer will guess correctly. For the purposes of this tutorial you can just either press
+ <strong>[Enter]</strong> to use the detected hostname or type in <tt class="literal">localhost</tt>
+</p>
+
+<pre class="panel">
+What is the fully qualified hostname of this machine?
+
+Press ENTER to use the detected value (vmtroll32)
+
+Hostname: localhost
+Cannot find configured certificate and key for HTTPS, creating these for you.
+</pre>
+
+<p>
+ Once the installer has completed you are ready to start the Nimbus services.
+ Notice the final lines of output from the installer:
+</p>
+
+<pre class="panel">
+-----------------------------------------------------------------
+ Nimbus installation succeeded!
+-----------------------------------------------------------------
+
+Additional configuration may be necessary, refer to this URL for information:
+
+ http://www.nimbusproject.org/docs/2.6/admin/z2c/
+
+You can start/stop Nimbus services with the nimbusctl command. e.g:
+
+ /tmp/nimbus/bin/nimbusctl start
+</pre>
+
+<p>
+ This tells you exactly what you need to do next and where to find more information.
+ Go ahead and start the Nimbus services:
+</p>
+
+<pre class="panel">
+$ /tmp/nimbus/bin/nimbusctl start
+Launching Nimbus services... OK
+Launching Cumulus services... OK
+</pre>
+
+<p>
+ For more details on the installation process, check out the
+ <a href="z2c/service-setup.html">Service Installation</a> page of the Zero to Cloud guide.
+</p>
+
+<a name="basic-tour"> </a>
+<h3>Tour of the installation _NAMELINK(basic-tour)</h3>
+
+<p>
+ Nimbus should now be running, but in <em>fake mode</em>. This means that the services
+ run and respond to requests as normal, but there are no actual backend nodes: no virtual
+ machines are ever started. This is great for testing and for our purposes. In a real
+ Nimbus installation you would proceed to install and configure backend nodes, establish
+ communication between them and the service node, and then turn off fake mode. These steps
+ are detailed in the <a href="z2c/">Zero to Cloud guide</a>.
+</p>
+
+<p>
+ Let's quickly examine what we just installed. Change to the destination directory and
+ look around.
+</p>
+
+<pre class="panel">
+$ cd /tmp/nimbus
+$ ls
+bin libexec ve
+cumulus nimbus-setup.conf web
+install.log services
+lantorrent var
+</pre>
+
+<p>
+ There are a couple directories you should notice here. <tt class="literal">bin/</tt> contains
+ most of the command-line tools used to manage Nimbus services and users.
+</p>
+
+<pre class="panel">
+$ ls bin/
+cumulus-rebase nimbus-new-cert nimbus-reset-state
+nimbus-configure nimbus-new-user nimbus-version
+nimbus-edit-user nimbus-nodes nimbusctl
+nimbus-import-users nimbus-public-image
+nimbus-list-users nimbus-remove-user
+</pre>
+
+<p>
+ <tt class="literal">services/</tt> contains the core Nimbus Java services. Inside of it,
+ <tt class="literal">services/etc/nimbus/</tt> holds many of the important configuration
+ files.
+</p>
+
+<a name="users"> </a>
+<h3>Managing users _NAMELINK(users)</h3>
+
+<p>
+ There are four user management command line tools in <tt class="literal">bin/</tt>:
+ <tt class="literal">nimbus-new-user</tt>, <tt class="literal">nimbus-list-users</tt>,
+ <tt class="literal">nimbus-edit-user</tt>, and <tt class="literal">nimbus-remove-user</tt>.
+ To get detailed information about each of these tools, run them with the
+ <tt class="literal">--help</tt> option.
+</p>
+
+<p>
+ To begin with, we will create a new user. To do this we run the
+ <tt class="literal">nimbus-new-user</tt> command and provide it with the email address
+ of the user we wish to create. The email address is just used as a unique friendly name
+ (no email is sent).
+</p>
+
+<pre class="panel">
+$ ./bin/nimbus-new-user tutorialuser@nimbusproject.org
+cert : /tmp/nimbus/var/ca/tmpk8NmStcert/usercert.pem
+key : /tmp/nimbus/var/ca/tmpk8NmStcert/userkey.pem
+dn : /O=Auto/OU=ab75d05b-87ae-4f60-9b4c-c32d207d1f29/CN=tutorialuser@nimbusproject.org
+canonical id : dc1b51f6-f73c-11df-87a3-000c292f4ae6
+access id : e1qrC9MyqRUU33INiL7D3
+access secret : TuR5Mrdrl3eAC0tiyCF83hhnxkYL9Udi29U7k1VrvO
+url : None
+web id : None
+cloud properties : /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties
+</pre>
+
+<p>
+ Notice the output of this command. Every bit of user information is displayed here,
+ some of which is secret information (which can be turned off if needed, check out the
+ <tt class="literal">--report</tt> option). In this case, all of the critical information
+ is placed in the newly created temporary directory under /tmp/nimbus/var/ca/. In that
+ directory you will find the following files:
+
+<pre class="panel">
+cloud.properties usercert.pem userkey.pem
+</pre>
+
+<p>
+ These files need to be securely transferred to your users. In our case, lets grab a cloud
+ client and try to query the service with these credentials. If you are not familiar with
+ the Nimbus cloud client, review the <a href="../clouds/cloudquickstart.html">quickstart</a>.
+ First, download a cloud client package and unpack it somewhere on your system.
+</p>
+
+<pre class="panel">
+wget http://www.nimbusproject.org/downloads/nimbus-cloud-client-017.tar.gz
+tar xzf nimbus-cloud-client-017.tar.gz
+cd nimbus-cloud-client-017/
+</pre>
+
+<p>
+ Next copy the cloud.properties file generated by the
+ <tt class="literal">nimbus-new-user</tt> call into the
+ <tt class="literal">conf/</tt> directory. Note that the actual path will differ
+ slightly from this example, but it will have been printed out.
+</p>
+
+<pre class="panel">
+$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties conf/
+</pre>
+
+<p>
+ We also need to copy the generated key and certificate to ~/.nimbus/ in your home directory.
+ Be careful not to overwrite any existing files you may have in this directory.
+</p>
+
+<pre class="panel">
+$ mkdir ~/.nimbus
+$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/*.pem ~/.nimbus/
+</pre>
+
+<p>
+ There is one final step in configuring the cloud client. We must allow it to trust
+ the service's certificate authority, by copying some certificates into the client.
+</p>
+
+<pre class="panel">
+$ cp /tmp/nimbus/var/ca/trusted-certs/* lib/certs/
+</pre>
+
+<p>
+ Now try out the cloud client. Query the service for running instances and available
+ VM images (of course there will be none of either).
+</p>
+
+<pre class="panel">
+$ ./bin/cloud-client.sh --status
+Querying for ALL instances.
+
+There's nothing running on this cloud that you own.
+
+$ ./bin/cloud-client --list
+No files.
+</pre>
+
+
+<a name="nodes"> </a>
+<h3>Node Management _NAMELINK(nodes)</h3>
+
+<p>
+ TODO
+</p>
+
+<a name="config"> </a>
+<h3>Configuration _NAMELINK(config)</h3>
+
+<p>
+ TODO
+</p>
+
+
+
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+
+_NIMBUS_CENTER2_COLUMN_END
+_NIMBUS_FOOTER1
+_NIMBUS_FOOTER2
+_NIMBUS_FOOTER3
Please sign in to comment.
Something went wrong with that request. Please try again.