fog--fog/lib/fog/xenserver/examples/getting_started.md

# Getting started: the compute service

## Connecting, retrieving and managing server objects

First, create a connection to the XenServer host:

    require 'fog'
    require 'pp'
    
    #
    # http://rubydoc.info/github/fog/fog/Fog/Compute/XenServer/Real
    #
    conn = Fog::Compute.new({
      :provider => 'XenServer',
      :xenserver_url => 'xenserver-test',
      :xenserver_username => 'root',
      :xenserver_password => 'changeme',
      :xenserver_defaults => { 
        :template => "squeeze-test" 
      }
    })

## Listing servers (VMs) and templates

We try to follow fog naming conventions and behavior as much as we can, so the
terminology used in fog/xenserver is a little bit different from the one
used in XAPI/XenServer documents. In particular:

* A Fog::Compute::XenServer::Server is a XenServer VM or DomU

* A Fog::Compute::XenServer::Host is a Hypervisor or Dom0

Having that in mind, we can start doing things with out XenServer host.

Listing all the servers (VMs):

    conn.servers.all 

This will return a list of Fog::Compute::XenServer::Server.

List all the servers whose name matches Ubuntu:

    conn.servers.all :name_matches => "Ubuntu"

Listing the first server running (templates aren't included by default 
in the list):

    server = conn.servers.first

Listing custom templates, that is, the ones created by the user:

    custom = conn.servers.custom_templates

Listing built-in templates (the templates available after a fresh install):

    built_in = conn.servers.builtin_templates

Templates are regular Fog::Compute::XenServer::Server objects too, so you can
inspect some of their attributes. The relevant XAPI documentation:

http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VM

Fog::Compute::XenServer::Server attributes and operations usually map to the
ones found in the official Citrix documentation, and they are available at:

http://rubydoc.info/github/fog/fog/Fog/Compute/XenServer/Server

and 

https://github.com/fog/fog/blob/master/lib/fog/xenserver/models/compute/server.rb

## Server operations and attributes

Getting server VIFs (virtual network interfaces):

    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VIF
    server.networks
    # or server.vifs

Listing the server VBDs (virtual block devices):

    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VBD
    server.vbds


Get VDIs objects (virtual disk images) attached to the server:

    server.vbds.each do |vbd|
      # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VDI
      vdi = vbd.vdi
      # In bytes
      puts vdi.virtual_size
      puts vdi.physical_utilisation
    end

## Server creation and life-cycle management

Creating a new server/VM:

    server = conn.servers.create :name => 'foobar',
                                 :template_name => 'squeeze-test'

The server is automatically started after that.

Note that template_name is optional if you have specified the ':template'
parameter when when creating the connection.

If you don't want to automatically start the server, use 'new' instead of 'create':

    server = conn.servers.new :name => 'foobar',
                              :template_name => 'squeeze-test'

and set auto_start to false when saving it:

    server.save :auto_start => false

Shutting down the server, By forcing it

    server.stop 'hard'
    # server.hard_shutdown is equivalent

Doing a clean shutdown

    server.stop 'clean'
    # server.clean_shutdown is equivalent

And finally, destroy it (it will force a shutdown first if running):

    server.destroy

# XenServer Host (Dom0) operations

The are some operations that can be performed on the host, without retrieving
and/or manipulating servers:

Listing all the VBDs (virtual block devices):

    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=VBD
    conn.vbds.all

This will retrieve the list of every single VBD available in the XenServer.

Same thing applies to the virtual disk images:

    conn.vdis.all

Listing Storage Repositories (Xen SRs), where the disk images are stored:
    
    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=SR
    conn.storage_repositories


XenServer Pools:

    # http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/api/?c=pool
    conn.pools


Retrieve the default storage repository in a pool:

    conn.pools.first.default_storage_repository
    # or the equivalent conn.pools.first.default_sr