Skip to content
This repository
Browse code

Working on new admin walkthrough document

  • Loading branch information...
commit 5f794cbc5aaf7a27c2a1e25cfd9ca8c20b46d8ef 1 parent 0d07e2e
David LaBissoniere labisso authored

Showing 1 changed file with 335 additions and 0 deletions. Show diff stats Hide diff stats

  1. +335 0 docs/src/admin/walkthrough.html
335 docs/src/admin/walkthrough.html
... ... @@ -0,0 +1,335 @@
  1 +m4_include(/mcs/m4/worksp.lib.m4)
  2 +_NIMBUS_HEADER(2.6 Admin Walkthrough)
  3 +_NIMBUS_HEADER2(n,n,y,n,n,n,n)
  4 +_NIMBUS_LEFT2_COLUMN
  5 +_NIMBUS_LEFT2_ADMIN_SIDEBAR(n,n,n,n,n)
  6 +_NIMBUS_LEFT2_COLUMN_END
  7 +_NIMBUS_CENTER2_COLUMN
  8 +_NIMBUS_IS_DEPRECATED
  9 +
  10 +
  11 +<h2>Nimbus 2.6 Administrator Walkthrough</h2>
  12 +
  13 +<p>
  14 + This guide provides a hands-on overview of Nimbus administrative functionality.
  15 + It is intended to give new and prospective users a feel for the features and
  16 + philosophy behind Nimbus. It is complementary to the
  17 + <a href="z2c/">Zero to Cloud Guide</a> and the
  18 + <a href="reference.html">reference manual</a>. It steps through a simple install
  19 + of the <em>service node</em> but doesn't cover configuring backend nodes.
  20 + It then demonstrates some administrative tools and procedures.
  21 +</p>
  22 +
  23 +<a name="install"> </a>
  24 +<h3>Installation _NAMELINK(install)</h3>
  25 +
  26 +<p>
  27 + The first step is to make a basic installation of the Nimbus services. Since
  28 + we are just messing around, we will install to a temporary location,
  29 + <tt class="literal">/tmp/nimbus</tt>. The installer
  30 + will place all files in this location and will not affect any other part of
  31 + your system. You can install to any path you like, just make sure to adjust
  32 + the example commands in this document appropriately. You do not need to be
  33 + <tt class="literal">root</tt> to install and run the Nimbus services.
  34 +</p>
  35 +
  36 +<p>
  37 + Before you proceed, make sure your system has the required dependencies. These
  38 + are detailed in the <a href="z2c/service-dependencies.html">Service Dependencies</a>
  39 + page of the Zero to Cloud guide.
  40 + The short version is: Java 1.5+, Python 2.5+ plus development headers
  41 + (but not Python 3.x), Apache ant, and gcc.
  42 +</p>
  43 +
  44 +<p>
  45 + First download and unpack the Nimbus service source package:
  46 +</p>
  47 +
  48 +<pre class="panel">
  49 +$ wget http://www.nimbusproject.org/downloads/nimbus-2.6-src.tar.gz
  50 +$ tar xzf nimbus-2.6-src.tar.gz
  51 +$ cd nimbus-2.6-src/
  52 +</pre>
  53 +
  54 +<p>
  55 + Now run the installer, specifying the destination directory as an argument.
  56 +</p>
  57 +
  58 +<pre class="panel">
  59 +$ ./install /tmp/nimbus
  60 +</pre>
  61 +
  62 +<div class="note">
  63 + <p class="note-title">Installer Undo</p>
  64 + <p>
  65 + If the installer fails, perhaps because of a missing dependency, make sure
  66 + to remove your destination directory if it was created:
  67 + </p>
  68 + <pre class="panel">
  69 +rm -fr /tmp/nimbus
  70 +</pre>
  71 + <p>
  72 + This will ensure that once you resolve the problem, the installation will
  73 + not conflict with the earlier failed install.
  74 + </p>
  75 +</div>
  76 +
  77 +<p>
  78 + The installation will take a minute or two and you will be asked a couple of questions at
  79 + the end.
  80 +</p>
  81 +
  82 +<pre class="panel">
  83 +-----------------------------------------------------------------
  84 + Configuring installed services
  85 +-----------------------------------------------------------------
  86 +
  87 +Nimbus uses an internal Certificate Authority (CA) for some services. This CA
  88 +is also used to generate host and user certificates if you do not have your own.
  89 +
  90 +This CA will be created in /tmp/nimbus/var/ca
  91 +
  92 +Please pick a unique, one word CA name or hit ENTER to use a UUID.
  93 +
  94 +For example, if you are installing this on the "Jupiter" cluster, you might use
  95 +"JupiterNimbusCA" as the name.
  96 +
  97 +CA Name:
  98 +You did not enter a name, using 'ab75d05b-87ae-4f60-9b4c-c32d207d1f29'
  99 +</pre>
  100 +
  101 +<p>
  102 + This gives you a chance to customize the name of your certificate authority.
  103 + For the purposes of this tutorial you can just press <strong>[Enter]</strong> and let
  104 + the installer pick a unique name for you.
  105 +</p>
  106 +
  107 +<p>
  108 + The next question asks you for the hostname you would like to use. It is important
  109 + that this is correct because it is used internally by Nimbus. In most cases the
  110 + installer will guess correctly. For the purposes of this tutorial you can just either press
  111 + <strong>[Enter]</strong> to use the detected hostname or type in <tt class="literal">localhost</tt>
  112 +</p>
  113 +
  114 +<pre class="panel">
  115 +What is the fully qualified hostname of this machine?
  116 +
  117 +Press ENTER to use the detected value (vmtroll32)
  118 +
  119 +Hostname: localhost
  120 +Cannot find configured certificate and key for HTTPS, creating these for you.
  121 +</pre>
  122 +
  123 +<p>
  124 + Once the installer has completed you are ready to start the Nimbus services.
  125 + Notice the final lines of output from the installer:
  126 +</p>
  127 +
  128 +<pre class="panel">
  129 +-----------------------------------------------------------------
  130 + Nimbus installation succeeded!
  131 +-----------------------------------------------------------------
  132 +
  133 +Additional configuration may be necessary, refer to this URL for information:
  134 +
  135 + http://www.nimbusproject.org/docs/2.6/admin/z2c/
  136 +
  137 +You can start/stop Nimbus services with the nimbusctl command. e.g:
  138 +
  139 + /tmp/nimbus/bin/nimbusctl start
  140 +</pre>
  141 +
  142 +<p>
  143 + This tells you exactly what you need to do next and where to find more information.
  144 + Go ahead and start the Nimbus services:
  145 +</p>
  146 +
  147 +<pre class="panel">
  148 +$ /tmp/nimbus/bin/nimbusctl start
  149 +Launching Nimbus services... OK
  150 +Launching Cumulus services... OK
  151 +</pre>
  152 +
  153 +<p>
  154 + For more details on the installation process, check out the
  155 + <a href="z2c/service-setup.html">Service Installation</a> page of the Zero to Cloud guide.
  156 +</p>
  157 +
  158 +<a name="basic-tour"> </a>
  159 +<h3>Tour of the installation _NAMELINK(basic-tour)</h3>
  160 +
  161 +<p>
  162 + Nimbus should now be running, but in <em>fake mode</em>. This means that the services
  163 + run and respond to requests as normal, but there are no actual backend nodes: no virtual
  164 + machines are ever started. This is great for testing and for our purposes. In a real
  165 + Nimbus installation you would proceed to install and configure backend nodes, establish
  166 + communication between them and the service node, and then turn off fake mode. These steps
  167 + are detailed in the <a href="z2c/">Zero to Cloud guide</a>.
  168 +</p>
  169 +
  170 +<p>
  171 + Let's quickly examine what we just installed. Change to the destination directory and
  172 + look around.
  173 +</p>
  174 +
  175 +<pre class="panel">
  176 +$ cd /tmp/nimbus
  177 +$ ls
  178 +bin libexec ve
  179 +cumulus nimbus-setup.conf web
  180 +install.log services
  181 +lantorrent var
  182 +</pre>
  183 +
  184 +<p>
  185 + There are a couple directories you should notice here. <tt class="literal">bin/</tt> contains
  186 + most of the command-line tools used to manage Nimbus services and users.
  187 +</p>
  188 +
  189 +<pre class="panel">
  190 +$ ls bin/
  191 +cumulus-rebase nimbus-new-cert nimbus-reset-state
  192 +nimbus-configure nimbus-new-user nimbus-version
  193 +nimbus-edit-user nimbus-nodes nimbusctl
  194 +nimbus-import-users nimbus-public-image
  195 +nimbus-list-users nimbus-remove-user
  196 +</pre>
  197 +
  198 +<p>
  199 + <tt class="literal">services/</tt> contains the core Nimbus Java services. Inside of it,
  200 + <tt class="literal">services/etc/nimbus/</tt> holds many of the important configuration
  201 + files.
  202 +</p>
  203 +
  204 +<a name="users"> </a>
  205 +<h3>Managing users _NAMELINK(users)</h3>
  206 +
  207 +<p>
  208 + There are four user management command line tools in <tt class="literal">bin/</tt>:
  209 + <tt class="literal">nimbus-new-user</tt>, <tt class="literal">nimbus-list-users</tt>,
  210 + <tt class="literal">nimbus-edit-user</tt>, and <tt class="literal">nimbus-remove-user</tt>.
  211 + To get detailed information about each of these tools, run them with the
  212 + <tt class="literal">--help</tt> option.
  213 +</p>
  214 +
  215 +<p>
  216 + To begin with, we will create a new user. To do this we run the
  217 + <tt class="literal">nimbus-new-user</tt> command and provide it with the email address
  218 + of the user we wish to create. The email address is just used as a unique friendly name
  219 + (no email is sent).
  220 +</p>
  221 +
  222 +<pre class="panel">
  223 +$ ./bin/nimbus-new-user tutorialuser@nimbusproject.org
  224 +cert : /tmp/nimbus/var/ca/tmpk8NmStcert/usercert.pem
  225 +key : /tmp/nimbus/var/ca/tmpk8NmStcert/userkey.pem
  226 +dn : /O=Auto/OU=ab75d05b-87ae-4f60-9b4c-c32d207d1f29/CN=tutorialuser@nimbusproject.org
  227 +canonical id : dc1b51f6-f73c-11df-87a3-000c292f4ae6
  228 +access id : e1qrC9MyqRUU33INiL7D3
  229 +access secret : TuR5Mrdrl3eAC0tiyCF83hhnxkYL9Udi29U7k1VrvO
  230 +url : None
  231 +web id : None
  232 +cloud properties : /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties
  233 +</pre>
  234 +
  235 +<p>
  236 + Notice the output of this command. Every bit of user information is displayed here,
  237 + some of which is secret information (which can be turned off if needed, check out the
  238 + <tt class="literal">--report</tt> option). In this case, all of the critical information
  239 + is placed in the newly created temporary directory under /tmp/nimbus/var/ca/. In that
  240 + directory you will find the following files:
  241 +
  242 +<pre class="panel">
  243 +cloud.properties usercert.pem userkey.pem
  244 +</pre>
  245 +
  246 +<p>
  247 + These files need to be securely transferred to your users. In our case, lets grab a cloud
  248 + client and try to query the service with these credentials. If you are not familiar with
  249 + the Nimbus cloud client, review the <a href="../clouds/cloudquickstart.html">quickstart</a>.
  250 + First, download a cloud client package and unpack it somewhere on your system.
  251 +</p>
  252 +
  253 +<pre class="panel">
  254 +wget http://www.nimbusproject.org/downloads/nimbus-cloud-client-017.tar.gz
  255 +tar xzf nimbus-cloud-client-017.tar.gz
  256 +cd nimbus-cloud-client-017/
  257 +</pre>
  258 +
  259 +<p>
  260 + Next copy the cloud.properties file generated by the
  261 + <tt class="literal">nimbus-new-user</tt> call into the
  262 + <tt class="literal">conf/</tt> directory. Note that the actual path will differ
  263 + slightly from this example, but it will have been printed out.
  264 +</p>
  265 +
  266 +<pre class="panel">
  267 +$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/cloud.properties conf/
  268 +</pre>
  269 +
  270 +<p>
  271 + We also need to copy the generated key and certificate to ~/.nimbus/ in your home directory.
  272 + Be careful not to overwrite any existing files you may have in this directory.
  273 +</p>
  274 +
  275 +<pre class="panel">
  276 +$ mkdir ~/.nimbus
  277 +$ cp /tmp/nimbus/var/ca/tmpk8NmStcert/*.pem ~/.nimbus/
  278 +</pre>
  279 +
  280 +<p>
  281 + There is one final step in configuring the cloud client. We must allow it to trust
  282 + the service's certificate authority, by copying some certificates into the client.
  283 +</p>
  284 +
  285 +<pre class="panel">
  286 +$ cp /tmp/nimbus/var/ca/trusted-certs/* lib/certs/
  287 +</pre>
  288 +
  289 +<p>
  290 + Now try out the cloud client. Query the service for running instances and available
  291 + VM images (of course there will be none of either).
  292 +</p>
  293 +
  294 +<pre class="panel">
  295 +$ ./bin/cloud-client.sh --status
  296 +Querying for ALL instances.
  297 +
  298 +There's nothing running on this cloud that you own.
  299 +
  300 +$ ./bin/cloud-client --list
  301 +No files.
  302 +</pre>
  303 +
  304 +
  305 +<a name="nodes"> </a>
  306 +<h3>Node Management _NAMELINK(nodes)</h3>
  307 +
  308 +<p>
  309 + TODO
  310 +</p>
  311 +
  312 +<a name="config"> </a>
  313 +<h3>Configuration _NAMELINK(config)</h3>
  314 +
  315 +<p>
  316 + TODO
  317 +</p>
  318 +
  319 +
  320 +
  321 +<br />
  322 +<br />
  323 +<br />
  324 +<br />
  325 +<br />
  326 +<br />
  327 +<br />
  328 +<br />
  329 +<br />
  330 +<br />
  331 +
  332 +_NIMBUS_CENTER2_COLUMN_END
  333 +_NIMBUS_FOOTER1
  334 +_NIMBUS_FOOTER2
  335 +_NIMBUS_FOOTER3

0 comments on commit 5f794cb

Please sign in to comment.
Something went wrong with that request. Please try again.