Working with Servers
  ====================
  
  A *server* is a virtual machine instance that is managed by OpenStack Nova,
  the `Compute` service. One advantage of using OpenStack is that the
  virtualization layer makes it easy to create and discard servers as needed.
  
  The `Server` object, generated by the `Compute::server()` method, is used
  to work with servers. You can create, update, or delete servers, and you can
  perform various *actions* on the server, such as creating a backup image,
  resizing it, or rebooting it.
  
  To create an empty server:
  
      $serv = $compute->server(); // assumes that $compute exists
  
  To retrieve the data on an existing server:
  
      $serv = $compute->server('9bfd203a-0695-410d-99a9-66c4194c967b');
  
  ## Creating, updating, or deleting a server
  
  ### Creating a new server
  
  A server requires both a [Flavor object](flavors.md) and an
  [Image object](images.md) to
  be created. In addition, a server requires a name. You can easily create a
  new server by setting the proper values and calling the `create()` method:
  
      $server = $compute->server();
      $server->name = 'Small Server';
      $server->flavor = $compute->flavor(2);
      $server->image = $compute->image('c195ef3b-9195-4474-b6f7-16e5bd86acd0');
      $server->create();
  
  As a shortcut, you can also pass these parameters to the `create()` method
  in an associative array:
  
      $server = $compute->server();
      $server->create(array(
          'name' => 'Small Server',
          'flavor' => $compute->Flavor(2),
          'image' => $compute->Image('c195ef3b-9195-4474-b6f7-16e5bd86acd0')
      ));
  
  Note that when the `create()` request completes, the server is not actually
  created. Instead, the completion of the request indicates that the server
  build has been initiated in the Compute instance. Server builds typically
  take 1-5 minutes to complete (depending upon the size of the server). However,
  the initial response will return the server's ID as well as the assigned
  root password:
  
      // assuming we've created $server, above
      printf("ID is %s, root password is %s
  ",
          $server->id, $server->adminPass);
  
  (Note: it is not recommended that you print out the root password because of
  security risks. This is only provided as an example.)
  
  When you create a new server on the Rackspace public cloud, you can also
  associate it with one or more isolated networks. For more information, see
  [Working with Cloud Networks](networks.md).
  
  ### Rebuilding an existing server
  
  "Rebuilding" a server is nearly identical to creating one; you must supply
  an Image object. You can also change the server's name as part of the rebuild.
  The primary difference between a create and a rebuild is that, in the rebuild,
  the server's IP address(es) are retained (when the server is created, new IP
  addresses are assigned).
  
  To rebuild a server:
  
      $server = $compute->server('abaf0...');     // existing server
      $server->rebuild(array(
          'adminPass' => 'REPLACE THIS WITH THE SERVER ROOT PASSWORD',
          'name' => 'A Bigger Server', // name is not required on rebuild
          'image' => $compute->image('c195ef3b-9195-4474-b6f7-16e5bd86acd0')));
  
  ### Updating a server
  
  The `update()` method is very similar to `create()` except that the only
  attributes of a server that you are permitted to update are its name and
  the [access IP addresses](accessip.md).
  
      $compute = $cloud->compute();
      $server = $compute->server('908c5617-26c2-4535-99a9-3f20e4b74835');
      $server->update(array('accessIPv4'=>'50.57.94.244'));
  
  ### Deleting a server
  
  The `delete()` method is short and sweet: it immediately initiates the
  deletion of the server. Note that this is a destructive mechanism and it is
  unlikely that the server can be recovered. Example:
  
      $compute = $cloud->compute();
      $server = $compute->server('908c5617-26c2-4535-99a9-3f20e4b74835');
      $server->delete();  // BAM! bye-bye
  
  ## Server actions
  
  You can perform various actions on a server, such as rebooting it, resizing
  it, or changing the root password.
  
  ### Setting the root password
  
  Use the `setPassword()` method to change the root user's password:
  
      $server->setPassword('new password');
  
  Note that it may take a few second for the new password to take effect. Also,
  password restrictions (such as the minimum number of characters, numbers of
  punctuation characters, and so forth) are enforced by the operating system and are
  not always detectable by the Compute service. This means that, even though
  the `setPassword()` method succeeds, the password may not be changed, and
  there may not be any feedback to that effect.
  
  ### To reboot the server
  
  You can perform either a *hard* reboot (this is like pulling the power cord
  and then restarting) or a *soft* reboot (initiated by the operating system
  and generally less disruptive than a hard reboot). A hard reboot is
  performed by default:
  
      $server->reboot();                                  // hard reboot
      $server->reboot(ServerState::REBOOT_STATE_HARD);    // also a hard reboot
      $server->reboot(ServerState::REBOOT_STATE_SOFT);    // a soft reboot
  
  If the server is "hung," or unresponsive, a hard reboot may sometimes be
  the only way to access the server.
  
  ### To resize the server
  
  A server can be resized by providing a new [Flavor object](flavors.md):
  
      $server->resize($compute->flavor(5));
  
  Once the resize completes (check the `$server->status`), you can either
  confirm it:
  
      $server->resizeConfirm();
  
  or revert it back to the original size:
  
      $server->resizeRevert();
  
  ### To rescue/unrescue a server
  
  In rescue mode, a server is rebuilt to a pristine state and the existing
  filesystem is mounted so that you can edit files and diagnose issues.
  See
  [this document](http://docs.rackspace.com/servers/api/v2/cs-devguide/content/rescue_mode.html)
  for more details.
  
  Put server into rescue mode:
  
      $password = $server->rescue();
  
  The `$password` is the assigned root password of the rescue server.
  
  Take server out of rescue mode:
  
      $server->unrescue();
  
  This restores the server to its original state (plus any changes you may have
  made while it was in rescue mode).
  
  ## Volumes
  
  See [Working with Volumes](volumes.md) for information on the 
  `Server::attachVolume()`
  and `Server::detachVolume()` methods.
  
  ## What next?
  
  * Return to the [Table of Contents](toc.md). 
  * See also [Working with Networks](networks.md).
  * To learn about dynamic 
    volume creation and assignment, see 
    [Working with Volumes](volumes.md).