Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 336 lines (269 sloc) 10.694 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 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
Something went wrong with that request. Please try again.