Synnefo

# Copyright 2011-2013 GRNET S.A. All rights reserved.

#

# Redistribution and use in source and binary forms, with or

# without modification, are permitted provided that the following

# conditions are met:

#

#   1. Redistributions of source code must retain the above

#      copyright notice, this list of conditions and the following

#      disclaimer.

#

#   2. Redistributions in binary form must reproduce the above

#      copyright notice, this list of conditions and the following

#      disclaimer in the documentation and/or other materials

#      provided with the distribution.

#

# THIS SOFTWARE IS PROVIDED BY GRNET S.A. ``AS IS'' AND ANY EXPRESS

# OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GRNET S.A OR

# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED

# AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN

# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

# POSSIBILITY OF SUCH DAMAGE.

#

# The views and conclusions contained in the software and

# documentation are those of the authors and should not be

# interpreted as representing official policies, either expressed

# or implied, of GRNET S.A.

from django.conf import settings

from django.conf.urls import patterns

from django.db import transaction

from django.http import HttpResponse

from django.template.loader import render_to_string

from django.utils import simplejson as json

from snf_django.lib import api

from snf_django.lib.api import faults, utils

from synnefo.api import util

from synnefo.db.models import (VirtualMachine, VirtualMachineMetadata)

from synnefo.logic import servers, utils as logic_utils

from logging import getLogger

log = getLogger(__name__)

urlpatterns = patterns(

    'synnefo.api.servers',

    (r'^(?:/|.json|.xml)?$', 'demux'),

    (r'^/detail(?:.json|.xml)?$', 'list_servers', {'detail': True}),

    (r'^/(\d+)(?:.json|.xml)?$', 'server_demux'),

    (r'^/(\d+)/action(?:.json|.xml)?$', 'demux_server_action'),

    (r'^/(\d+)/ips(?:.json|.xml)?$', 'list_addresses'),

    (r'^/(\d+)/ips/(.+?)(?:.json|.xml)?$', 'list_addresses_by_network'),

    (r'^/(\d+)/metadata(?:.json|.xml)?$', 'metadata_demux'),

    (r'^/(\d+)/metadata/(.+?)(?:.json|.xml)?$', 'metadata_item_demux'),

    (r'^/(\d+)/stats(?:.json|.xml)?$', 'server_stats'),

    (r'^/(\d+)/diagnostics(?:.json)?$', 'get_server_diagnostics'),

)

def demux(request):

    if request.method == 'GET':

        return list_servers(request)

    elif request.method == 'POST':

        return create_server(request)

    else:

        return api.api_method_not_allowed(request)

def server_demux(request, server_id):

    if request.method == 'GET':

        return get_server_details(request, server_id)

    elif request.method == 'PUT':

        return update_server_name(request, server_id)

    elif request.method == 'DELETE':

        return delete_server(request, server_id)

    else:

        return api.api_method_not_allowed(request)

def metadata_demux(request, server_id):

    if request.method == 'GET':

        return list_metadata(request, server_id)

    elif request.method == 'POST':

        return update_metadata(request, server_id)

    else:

        return api.api_method_not_allowed(request)

def metadata_item_demux(request, server_id, key):

    if request.method == 'GET':

        return get_metadata_item(request, server_id, key)

    elif request.method == 'PUT':

        return create_metadata_item(request, server_id, key)

    elif request.method == 'DELETE':

        return delete_metadata_item(request, server_id, key)

    else:

        return api.api_method_not_allowed(request)

def nic_to_attachments(nic):

    """Convert a NIC object to 'attachments attribute.

    Convert a NIC object to match the format of 'attachments' attribute of the

    response to the /servers API call.

    NOTE: The 'ips' of the NIC object have been prefetched in order to avoid DB

    queries. No subsequent queries for 'ips' (like filtering) should be

    performed because this will return in a new DB query.

    """

    d = {'id': nic.id,

         'network_id': str(nic.network_id),

         'mac_address': nic.mac,

         'ipv4': '',

         'ipv6': ''}

    if nic.firewall_profile:

        d['firewallProfile'] = nic.firewall_profile

    for ip in nic.ips.all():

        if not ip.deleted:

            ip_type = "floating" if ip.floating_ip else "fixed"

            if ip.ipversion == 4:

                d["ipv4"] = ip.address

                d["OS-EXT-IPS:type"] = ip_type

            else:

                d["ipv6"] = ip.address

                d["OS-EXT-IPS:type"] = ip_type

    return d

def attachments_to_addresses(attachments):

    """Convert 'attachments' attribute to 'addresses'.

    Convert a a list of 'attachments' attribute to a list of 'addresses'

    attribute, as expected in the response to /servers API call.

    """

    addresses = {}

    for nic in attachments:

        net_addrs = []

        if nic["ipv4"]:

            net_addrs.append({"version": 4,

                              "addr": nic["ipv4"],

                              "OS-EXT-IPS:type": nic["OS-EXT-IPS:type"]})

        if nic["ipv6"]:

            net_addrs.append({"version": 6,

                              "addr": nic["ipv6"],

                              "OS-EXT-IPS:type": nic["OS-EXT-IPS:type"]})

        addresses[nic["network_id"]] = net_addrs

    return addresses

def vm_to_dict(vm, detail=False):

    d = dict(id=vm.id, name=vm.name)

    d['links'] = util.vm_to_links(vm.id)

    if detail:

        d['user_id'] = vm.userid

        d['tenant_id'] = vm.userid

        d['status'] = logic_utils.get_rsapi_state(vm)

        d['SNF:task_state'] = logic_utils.get_task_state(vm)

        d['progress'] = 100 if d['status'] == 'ACTIVE' else vm.buildpercentage

        d['hostId'] = vm.hostid

        d['updated'] = utils.isoformat(vm.updated)

        d['created'] = utils.isoformat(vm.created)

        d['flavor'] = {"id": vm.flavor.id,

                       "links": util.flavor_to_links(vm.flavor.id)}

        d['image'] = {"id": vm.imageid,

                      "links": util.image_to_links(vm.imageid)}

        d['suspended'] = vm.suspended

        metadata = dict((m.meta_key, m.meta_value) for m in vm.metadata.all())

        d['metadata'] = metadata

        nics = vm.nics.all()

        active_nics = filter(lambda nic: nic.state == "ACTIVE", nics)

        active_nics.sort(key=lambda nic: nic.id)

        attachments = map(nic_to_attachments, active_nics)

        d['attachments'] = attachments

        d['addresses'] = attachments_to_addresses(attachments)

        # include the latest vm diagnostic, if set

        diagnostic = vm.get_last_diagnostic()

        if diagnostic:

            d['diagnostics'] = diagnostics_to_dict([diagnostic])

        else:

            d['diagnostics'] = []

        # Fixed

        d["security_groups"] = [{"name": "default"}]

        d["key_name"] = None

        d["config_drive"] = ""

        d["accessIPv4"] = ""

        d["accessIPv6"] = ""

        fqdn = get_server_fqdn(vm, active_nics)

        d["SNF:fqdn"] = fqdn

        d["SNF:port_forwarding"] = get_server_port_forwarding(vm, active_nics,

                                                              fqdn)

    return d

def get_server_public_ip(vm_nics, version=4):

    """Get the first public IP address of a server.

    NOTE: 'vm_nics' objects have prefetched the ips

    """

    for version in [4, 6]:

        for nic in vm_nics:

            for ip in nic.ips.all():

                if ip.ipversion == version and ip.public:

                    return ip

    return None

def get_server_fqdn(vm, vm_nics):

    public_ip = get_server_public_ip(vm_nics)

    if public_ip is None:

        return ""

    fqdn_setting = settings.CYCLADES_SERVERS_FQDN

    if fqdn_setting is None:

        return public_ip.address

    elif isinstance(fqdn_setting, basestring):

        return fqdn_setting % {"id": vm.id}

    else:

        msg = ("Invalid setting: CYCLADES_SERVERS_FQDN."

               " Value must be a string.")

        raise faults.InternalServerError(msg)

def get_server_port_forwarding(vm, vm_nics, fqdn):

    """Create API 'port_forwarding' attribute from corresponding setting.

    Create the 'port_forwarding' API vm attribute based on the corresponding

    setting (CYCLADES_PORT_FORWARDING), which can be either a tuple

    of the form (host, port) or a callable object returning such tuple. In

    case of callable object, must be called with the following arguments:

    * ip_address

    * server_id

    * fqdn

    * owner UUID

    NOTE: 'vm_nics' objects have prefetched the ips

    """

    port_forwarding = {}

    public_ip = get_server_public_ip(vm_nics)

    if public_ip is None:

        return port_forwarding

    for dport, to_dest in settings.CYCLADES_PORT_FORWARDING.items():

        if hasattr(to_dest, "__call__"):

            to_dest = to_dest(public_ip.address, vm.id, fqdn, vm.userid)

        msg = ("Invalid setting: CYCLADES_PORT_FOWARDING."

               " Value must be a tuple of two elements (host, port).")

        if not isinstance(to_dest, tuple) or len(to_dest) != 2:

                raise faults.InternalServerError(msg)

        else:

            try:

                host, port = to_dest

            except (TypeError, ValueError):

                raise faults.InternalServerError(msg)

        port_forwarding[dport] = {"host": host, "port": str(port)}

    return port_forwarding

def diagnostics_to_dict(diagnostics):

    """

    Extract api data from diagnostics QuerySet.

    """

    entries = list()

    for diagnostic in diagnostics:

        # format source date if set

        formatted_source_date = None

        if diagnostic.source_date:

            formatted_source_date = utils.isoformat(diagnostic.source_date)

        entry = {

            'source': diagnostic.source,

            'created': utils.isoformat(diagnostic.created),

            'message': diagnostic.message,

            'details': diagnostic.details,

            'level': diagnostic.level,

        }

        if formatted_source_date:

            entry['source_date'] = formatted_source_date

        entries.append(entry)

    return entries

def render_server(request, server, status=200):

    if request.serialization == 'xml':

        data = render_to_string('server.xml', {

            'server': server,

            'is_root': True})

    else:

        data = json.dumps({'server': server})

    return HttpResponse(data, status=status)

def render_diagnostics(request, diagnostics_dict, status=200):

    """

    Render diagnostics dictionary to json response.

    """

    return HttpResponse(json.dumps(diagnostics_dict), status=status)

@api.api_method(http_method='GET', user_required=True, logger=log)

def get_server_diagnostics(request, server_id):

    """

    Virtual machine diagnostics api view.

    """

    log.debug('server_diagnostics %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq)

    diagnostics = diagnostics_to_dict(vm.diagnostics.all())

    return render_diagnostics(request, diagnostics)

@api.api_method(http_method='GET', user_required=True, logger=log)

def list_servers(request, detail=False):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       overLimit (413)

    log.debug('list_servers detail=%s', detail)

    user_vms = VirtualMachine.objects.filter(userid=request.user_uniq)

    if detail:

        user_vms = user_vms.prefetch_related("nics__ips")

    user_vms = utils.filter_modified_since(request, objects=user_vms)

    servers_dict = [vm_to_dict(server, detail)

                    for server in user_vms.order_by('id')]

    if request.serialization == 'xml':

        data = render_to_string('list_servers.xml', {

            'servers': servers_dict,

            'detail': detail})

    else:

        data = json.dumps({'servers': servers_dict})

    return HttpResponse(data, status=200)

@api.api_method(http_method='POST', user_required=True, logger=log)

def create_server(request):

    # Normal Response Code: 202

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badMediaType(415),

    #                       itemNotFound (404),

    #                       badRequest (400),

    #                       serverCapacityUnavailable (503),

    #                       overLimit (413)

    req = utils.get_request_dict(request)

    log.info('create_server %s', req)

    user_id = request.user_uniq

    try:

        server = req['server']

        name = server['name']

        metadata = server.get('metadata', {})

        assert isinstance(metadata, dict)

        image_id = server['imageRef']

        flavor_id = server['flavorRef']

        personality = server.get('personality', [])

        assert isinstance(personality, list)

        networks = server.get("networks")

        if networks is not None:

            assert isinstance(networks, list)

    except (KeyError, AssertionError):

        raise faults.BadRequest("Malformed request")

    # Verify that personalities are well-formed

    util.verify_personality(personality)

    # Get image information

    image = util.get_image_dict(image_id, user_id)

    # Get flavor (ensure it is active)

    flavor = util.get_flavor(flavor_id, include_deleted=False)

    # Generate password

    password = util.random_password()

    vm = servers.create(user_id, name, password, flavor, image,

                        metadata=metadata, personality=personality,

                        networks=networks)

    server = vm_to_dict(vm, detail=True)

    server['status'] = 'BUILD'

    server['adminPass'] = password

    response = render_server(request, server, status=202)

    return response

@api.api_method(http_method='GET', user_required=True, logger=log)

def get_server_details(request, server_id):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       itemNotFound (404),

    #                       overLimit (413)

    log.debug('get_server_details %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq,

                     prefetch_related="nics__ips")

    server = vm_to_dict(vm, detail=True)

    return render_server(request, server)

@api.api_method(http_method='PUT', user_required=True, logger=log)

@transaction.commit_on_success

def update_server_name(request, server_id):

    # Normal Response Code: 204

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       badMediaType(415),

    #                       itemNotFound (404),

    #                       buildInProgress (409),

    #                       overLimit (413)

    req = utils.get_request_dict(request)

    log.info('update_server_name %s %s', server_id, req)

    try:

        name = req['server']['name']

    except (TypeError, KeyError):

        raise faults.BadRequest("Malformed request")

    vm = util.get_vm(server_id, request.user_uniq, for_update=True,

                     non_suspended=True)

    servers.rename(vm, new_name=name)

    return HttpResponse(status=204)

@api.api_method(http_method='DELETE', user_required=True, logger=log)

def delete_server(request, server_id):

    # Normal Response Codes: 204

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       itemNotFound (404),

    #                       unauthorized (401),

    #                       buildInProgress (409),

    #                       overLimit (413)

    log.info('delete_server %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq, for_update=True,

                     non_suspended=True)

    vm = servers.destroy(vm)

    return HttpResponse(status=204)

# additional server actions

ARBITRARY_ACTIONS = ['console', 'firewallProfile']

def key_to_action(key):

    """Map HTTP request key to a VM Action"""

    if key == "shutdown":

        return "STOP"

    if key == "delete":

        return "DESTROY"

    if key in ARBITRARY_ACTIONS:

        return None

    else:

        return key.upper()

@api.api_method(http_method='POST', user_required=True, logger=log)

@transaction.commit_on_success

def demux_server_action(request, server_id):

    req = utils.get_request_dict(request)

    log.debug('server_action %s %s', server_id, req)

    if len(req) != 1:

        raise faults.BadRequest("Malformed request")

    # Do not allow any action on deleted or suspended VMs

    vm = util.get_vm(server_id, request.user_uniq, for_update=True,

                     non_deleted=True, non_suspended=True)

    action = req.keys()[0]

    if key_to_action(action) not in [x[0] for x in VirtualMachine.ACTIONS]:

        if action not in ARBITRARY_ACTIONS:

            raise faults.BadRequest("Action %s not supported" % action)

    action_args = req[action]

    if not isinstance(action_args, dict):

        raise faults.BadRequest("Invalid argument")

    return server_actions[action](request, vm, action_args)

@api.api_method(http_method='GET', user_required=True, logger=log)

def list_addresses(request, server_id):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       overLimit (413)

    log.debug('list_addresses %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq, prefetch_related="nic__ips")

    attachments = [nic_to_attachments(nic)

                   for nic in vm.nics.filter(state="ACTIVE")]

    addresses = attachments_to_addresses(attachments)

    if request.serialization == 'xml':

        data = render_to_string('list_addresses.xml', {'addresses': addresses})

    else:

        data = json.dumps({'addresses': addresses, 'attachments': attachments})

    return HttpResponse(data, status=200)

@api.api_method(http_method='GET', user_required=True, logger=log)

def list_addresses_by_network(request, server_id, network_id):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       itemNotFound (404),

    #                       overLimit (413)

    log.debug('list_addresses_by_network %s %s', server_id, network_id)

    machine = util.get_vm(server_id, request.user_uniq)

    network = util.get_network(network_id, request.user_uniq)

    nics = machine.nics.filter(network=network, state="ACTIVE")

    addresses = attachments_to_addresses(map(nic_to_attachments, nics))

    if request.serialization == 'xml':

        data = render_to_string('address.xml', {'addresses': addresses})

    else:

        data = json.dumps({'network': addresses})

    return HttpResponse(data, status=200)

@api.api_method(http_method='GET', user_required=True, logger=log)

def list_metadata(request, server_id):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       overLimit (413)

    log.debug('list_server_metadata %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq)

    metadata = dict((m.meta_key, m.meta_value) for m in vm.metadata.all())

    return util.render_metadata(request, metadata, use_values=False,

                                status=200)

@api.api_method(http_method='POST', user_required=True, logger=log)

@transaction.commit_on_success

def update_metadata(request, server_id):

    # Normal Response Code: 201

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       buildInProgress (409),

    #                       badMediaType(415),

    #                       overLimit (413)

    req = utils.get_request_dict(request)

    log.info('update_server_metadata %s %s', server_id, req)

    vm = util.get_vm(server_id, request.user_uniq, non_suspended=True)

    try:

        metadata = req['metadata']

        assert isinstance(metadata, dict)

    except (KeyError, AssertionError):

        raise faults.BadRequest("Malformed request")

    for key, val in metadata.items():

        meta, created = vm.metadata.get_or_create(meta_key=key)

        meta.meta_value = val

        meta.save()

    vm.save()

    vm_meta = dict((m.meta_key, m.meta_value) for m in vm.metadata.all())

    return util.render_metadata(request, vm_meta, status=201)

@api.api_method(http_method='GET', user_required=True, logger=log)

def get_metadata_item(request, server_id, key):

    # Normal Response Codes: 200, 203

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       itemNotFound (404),

    #                       badRequest (400),

    #                       overLimit (413)

    log.debug('get_server_metadata_item %s %s', server_id, key)

    vm = util.get_vm(server_id, request.user_uniq)

    meta = util.get_vm_meta(vm, key)

    d = {meta.meta_key: meta.meta_value}

    return util.render_meta(request, d, status=200)

@api.api_method(http_method='PUT', user_required=True, logger=log)

@transaction.commit_on_success

def create_metadata_item(request, server_id, key):

    # Normal Response Code: 201

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       itemNotFound (404),

    #                       badRequest (400),

    #                       buildInProgress (409),

    #                       badMediaType(415),

    #                       overLimit (413)

    req = utils.get_request_dict(request)

    log.info('create_server_metadata_item %s %s %s', server_id, key, req)

    vm = util.get_vm(server_id, request.user_uniq, non_suspended=True)

    try:

        metadict = req['meta']

        assert isinstance(metadict, dict)

        assert len(metadict) == 1

        assert key in metadict

    except (KeyError, AssertionError):

        raise faults.BadRequest("Malformed request")

    meta, created = VirtualMachineMetadata.objects.get_or_create(

        meta_key=key,

        vm=vm)

    meta.meta_value = metadict[key]

    meta.save()

    vm.save()

    d = {meta.meta_key: meta.meta_value}

    return util.render_meta(request, d, status=201)

@api.api_method(http_method='DELETE', user_required=True, logger=log)

@transaction.commit_on_success

def delete_metadata_item(request, server_id, key):

    # Normal Response Code: 204

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       itemNotFound (404),

    #                       badRequest (400),

    #                       buildInProgress (409),

    #                       badMediaType(415),

    #                       overLimit (413),

    log.info('delete_server_metadata_item %s %s', server_id, key)

    vm = util.get_vm(server_id, request.user_uniq, non_suspended=True)

    meta = util.get_vm_meta(vm, key)

    meta.delete()

    vm.save()

    return HttpResponse(status=204)

@api.api_method(http_method='GET', user_required=True, logger=log)

def server_stats(request, server_id):

    # Normal Response Codes: 200

    # Error Response Codes: computeFault (400, 500),

    #                       serviceUnavailable (503),

    #                       unauthorized (401),

    #                       badRequest (400),

    #                       itemNotFound (404),

    #                       overLimit (413)

    log.debug('server_stats %s', server_id)

    vm = util.get_vm(server_id, request.user_uniq)

    #secret = util.encrypt(vm.backend_vm_id)

    secret = vm.backend_vm_id      # XXX disable backend id encryption

    stats = {

        'serverRef': vm.id,

        'refresh': settings.STATS_REFRESH_PERIOD,

        'cpuBar': settings.CPU_BAR_GRAPH_URL % secret,

        'cpuTimeSeries': settings.CPU_TIMESERIES_GRAPH_URL % secret,

        'netBar': settings.NET_BAR_GRAPH_URL % secret,

        'netTimeSeries': settings.NET_TIMESERIES_GRAPH_URL % secret}

    if request.serialization == 'xml':

        data = render_to_string('server_stats.xml', stats)

    else:

        data = json.dumps({'stats': stats})

    return HttpResponse(data, status=200)

# ACTIONS

server_actions = {}

network_actions = {}

def server_action(name):

    '''Decorator for functions implementing server actions.

    `name` is the key in the dict passed by the client.

    '''

    def decorator(func):

        server_actions[name] = func

        return func

    return decorator

def network_action(name):

    '''Decorator for functions implementing network actions.

    `name` is the key in the dict passed by the client.

    '''

    def decorator(func):

        network_actions[name] = func

        return func

    return decorator

@server_action('start')

def start(request, vm, args):

    # Normal Response Code: 202

    # Error Response Codes: serviceUnavailable (503),

    #                       itemNotFound (404)

    vm = servers.start(vm)

    return HttpResponse(status=202)

@server_action('shutdown')

def shutdown(request, vm, args):

    # Normal Response Code: 202

    # Error Response Codes: serviceUnavailable (503),

    #                       itemNotFound (404)

    vm = servers.stop(vm)