.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index::
   double: Methods; server

.. _server:

Server Methods
--------------

API Methods for dealing with servers

.. function:: server.info

    Describes the server returning a dictionary.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :returns: A dictionary with the following keys:
    
        **name**
            String: name of this server (same as service name), e.g. "testaa1".
        **host_name**
            String: host name for this server, e.g. "testaa1.miniserver.com".
        **primary_ip**
            String: primary IP address for this server, e.g. "1.2.3.4".
        **ips**
            List of Dictionaries: All the IP addresses assigned to this server described as a dictionary with the following keys:
    
            **address**
                String: IP address, e.g. "1.2.3.4".
            **reverse_map**
                String: Reverse mapping for IP address, e.g. "server.example.com".
            **bytes_in_yesterday**
                Integer: Bytes received yesterday to this IP address.
            **bytes_out_yesterday**
                Integer: Bytes sent yesterday from this IP address.
            **bytes_in_today**
                Integer: Bytes received today so far to this IP address.
            **bytes_out_today**
                Integer: Bytes sent today so far from this IP address.
        **vlans**
            Dictionary with the following keys:
                **tagged**:
                    List of Strings: The names of all the tagged vLANs this server is in.
                **untagged**:
                    List of Strings: The names of all the untagged vLANs this server is in.
        **os**
            String: describing the Operation System  installed, e.g. "debian_wheezy_64", "win2012serverstd_r2_64".
        **backups**
            Boolean: whether this server has a backup service.
        **control_panel**
            String: describing the control panel, e.g. "none", or "cpanel".
        **firewall_type**
            String: describing the firewall type, e.g. "none", "basic", "self_managed" or "managed".
        **firewall_rule_group**
            Dictionary: describing the firewall rule group applied to the server as returned by :func:`firewalling.rule_group_info`.
            Empty if ``firewall_type`` is "none".
        **monitoring_level**
            Strong: describing the monitoring level, "basic", "advanced" or "managed".
        **monitor**
            Boolean: whether we are monitoring this server.
        **ignore_monitoring_off**
            Boolean: the customer has acknowledged that they aren't being monitored.
        **no_nrpe**
            Boolean: Disable NRPE agent for this server.
        **no_auto_reboot**
            Boolean: Don't auto reboot this server.
        **support_level**
            String: support level "infrastructure_only", "basic" or "managed".
        **vulnscan**
            String: whether this server is vulnerability scanned, 'none' = no scanning, 'basic' = Self-monitored, 'managed' = Memset-monitored.
        **intrusion_detection**
            String: The intrusion detection support level for this server e.g. "none", "basic" = Self-monitored, "monitored" = Memset-monitored or "protected" = Memset-protected
        **intrusion_detection_alert_level**
            Integer: The alert level that is set for  Intrusion Detection (1-15) or 0 (intrusion_detection="none")
    
    The keys as described in :func:`service.info` will also be returned.

.. function:: server.list

    List all the servers for an account.
    
    If the status isn't passed in then it will find all the servers with status=LIVE.
    
    :param status: Status of the server to look for. Acceptable values: 'LIVE', 'CANCELLED'.
    :type status: String, Optional
    
    :returns: Returns a list of dictionaries where each dictionary is as described in func:`server_info`.

.. function:: server.move_ips

    Moves a list of public IPv4 address from one server to another.
    
    This cannot be used to move IPs that are private, or where the source or destination server are
    in assigned to a load balancer.
    
    The list of IPs will need to be configured on the host once the job has completed.
    
    If the destination host is a Linux Miniserver, the IPs can be automatically applied by triggering 
    a reboot with :func:`server.reboot`.
     
    Please note that if the destination host is a Miniserver without a vLAN, it will require a 
    reboot using :func:`server.reboot` for the new IPs to be routed correctly.
    
    The source and destination servers will be unavailable for a short period during this move.
    
    :param source_ips: List of public IP addresses to be moved.
    :type source_ips: List
    
    :param destination_name: Name of the server. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type destination_name: String
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: 
        :class:`ApiErrorDoesNotExist` if the `destination_name` or any ip in `source_ips` cannot be found.
    
        :class:`ApiErrorBadParameters` if an empty list of IPs is provided.
    
        :class:`ApiErrorPreconditionFailed` will be raised if:
    
            - Any server is in a load balancer. 
            - Any IP cannot be moved to the destination network zone.
            - Any of the supplied IPs are private.
            - If any IP is the primary IP of a server.

.. function:: server.reboot

    Schedules a reboot for name
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param email_address: Email address for response to reboot, uses admin contact email if not passed in. Must be a valid email address.
    :type email_address: String, Optional
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: May raise :class:`ApiErrorAlreadyInProgress` if a reboot is pending already.

.. function:: server.reimage_from_snapshot

    Schedules re-imaging of name.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param storage_name: Name of the storage service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type storage_name: String
    
    :param image_type: Snapshot image type. Acceptable values: 'raw', 'tar', 'ntfsclone'.
    :type image_type: String
    
    :param snapshot_path: Path to the snapshot (check notes).
    :type snapshot_path: String
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: May raise one of the following exceptions:
    
        * :class:`ApiErrorAlreadyInProgress` if a re-imaging is pending already.
        * :class:`ApiErrorBadParameters` if the requested image_type is not available for that server or the snapshot name isn't valid.
        * :class:`ApiErrorMethodNotFound` if the server doesn't support re-imaging.
        * :class:`ApiErrorPreconditionFailed` if server current status isn't valid for re-imaging.
        * :class:`ApiErrorPreconditionFailed` if the server and the cloud storage are in different data zones.
    
    This method is only available on Miniservers.
    
    The snapshot path parameter depends on the image type:
      * **raw images**: the path to the .raw.gz image.
      * **ntfsclone images**: the path to the snapshot directory (it must contain the .XMBR file and all the .img.gz files).
      * **tar images**: the path to the .tar image.
    
    When using a **raw image**, it must contain an instance of the same type of operating
    system as currently installed on the server. For example: re-imaging a Linux based server with
    a Microsoft Windows raw image will result in a broken system.
    
    An email will be sent to the admin contact when the process is finished.
    
    See also :func:`server.snapshot_list` for retrieving a list of valid snapshots from a storage.

.. function:: server.reimage_from_stock_image

    Schedules re-imaging of name.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param os: The Operating System name.
    :type os: String
    
    :param os_bits: Whether to use a 32 or 64-bit system. Note that some operating systems may not be available in both versions. Acceptable values: '32', '64'.
    :type os_bits: String, Optional
    
    :param pub_ssh_key: Public SSH key to be installed in the server (`root` user). Only available when reimaging a Linux server. 
    :type pub_ssh_key: String, Optional
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: May raise one of the following exceptions:
    
        * :class:`ApiErrorAlreadyInProgress` if a re-imaging is pending already.
        * :class:`ApiErrorBadParameters` if the requested operating system is not available for that server, the operating system name isn't valid or the provided public SSH key isn't valid.
        * :class:`ApiErrorMethodNotFound` if the server doesn't support re-imaging.
        * :class:`ApiErrorPreconditionFailed` if server current status isn't valid for re-imaging.
    
    This method is only available on Miniservers.
    
    The `os` and `os_bits` parameters are as described in :doc:`methods_create`.
    
    You can manage public SSH keys on the Manage SSH Keys page in the Memset control panel.

.. function:: server.set_intrusion_detection_alert_level

    Sets the Intrusion Detection email alert level for name.
    
    Refer to the `Intrusion Detection page <https://www.memset.com/services/security/intrusion-detection/>`_ for alert levels.
    
    :raises: May raise :class:`ApiErrorPreconditionFailed` if Intrusion Detection is not enabled on this server.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param alert_level: The required new Intrusion Detection alert level. Ensure this value is greater than or equal to 1. Ensure this value is less than or equal to 15.
    :type alert_level: Integer
    
    

.. function:: server.slave_ns_add

    Add a domain to the Memset name server slaves for the primary name server ``name``.
    
    It may take up to 30 minutes for the domain to be added.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param domain_name: The slaved domain name. Must be a valid host name.
    :type domain_name: String
    
    :returns: The added domain name
    
    :raises:
        May raise one of the following exceptions:
         * :class:`ApiErrorDoesNotExist` if ``name`` cannot be found for the account.
         * :class:`ApiErrorPreconditionFailed` if the domain is already slaved.

.. function:: server.slave_ns_delete

    Delete a domain from the Memset name server slaves for the primary name server ``name``.
    
    It may take up to 30 minutes for the domain to be deleted.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param domain_name: The slaved domain name. Must be a valid host name.
    :type domain_name: String
    
    :returns: The deleted domain name.
    
    :raises: :class:`ApiErrorDoesNotExist` if ``name`` cannot be found for the account or slaved ``domain_name`` not found for ``name``.

.. function:: server.slave_ns_list

    List all domain names being slaved by Memset's name server slaves for the primary name server ``name``.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :returns: A list of domain names.
    
    :raises: :class:`ApiErrorDoesNotExist` if ``name`` cannot be found for the account.

.. function:: server.snapshot

    Schedules a snapshot for name.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param storage_name: Name of the storage service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type storage_name: String
    
    :param image_type: Snapshot image type. Acceptable values: 'raw', 'tar', 'ntfsclone'.
    :type image_type: String
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: May raise one of the following exceptions:
    
        * :class:`ApiErrorAlreadyInProgress` if a snapshot is pending already.
        * :class:`ApiErrorBadParameters` if the requested image_type is not available for that server.
        * :class:`ApiErrorMethodNotFound` if the server doesn't support snapshots.
        * :class:`ApiErrorPreconditionFailed` if server current status isn't valid for taking snapshots.
        * :class:`ApiErrorPreconditionFailed` if the server and the cloud storage are in different data zones.
    
    This method is only available on Miniservers.
    
    * "raw" - Supported for Miniservers running  Microsoft Windows or a Linux operating system.
    * "tar" - A deprecated image type for use with our classic Miniservers running a Linux operating system.
    * "ntfsclone" - A deprecated image type for Miniservers running a Microsoft Windows operating system.
    
    Please be advised that classic Miniservers are deprecated and won't be supported in future API releases.

.. function:: server.snapshot_delete

    Deletes a snapshot.
    
    :param storage_name: Name of the storage service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type storage_name: String
    
    :param snapshot_path: Path to the snapshot as returned by server.snapshot_list method. Ensure this value has at most 255 characters.
    :type snapshot_path: String
    
    :returns: A dictionary as described in :func:`job.status`.
    :raises: May raise :class:`ApiErrorAlreadyInProgress` if there is a pending deletion for that snapshot.
    
    The snapshots are expected to be in a container named 'miniserver-snapshots', so the path to the snapshot
    is relative to this container.
    
    See also :func:`server.snapshot_list` for retrieving a list of valid snapshots from a storage.

.. function:: server.snapshot_list

    Lists snapshots found in the storage identified by storage_name.
    
    :param storage_name: Name of the storage service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type storage_name: String
    
    :returns: An array of dictionaries with the following keys:
    
        **snapshot_path**
            String: full path to the snapshot.
        **image_type**
            String: "raw", "ntfsclone" or "tar".
        **os_type**
            String: "linux", "windows", "freebsd", etc; or "unknown" in case it can't be identified.
        **os_option**
            String: operating system option to be used to provision a Miniserver using this snapshot.
        **description**
            String: description of the snapshot.
        **user_comment**
            String: user provided comment (if any) or none.
        **last_modified**
            Date: last modification date of the snapshot.
    
    :raises: May raise :class:`ApiErrorDoesNotExist` if no snapshots are found.
    
    The snapshots are expected to be in a container named 'miniserver-snapshots'.
    This function doesn't guarantee that found snapshots are correct.

.. function:: server.upgrade

    Upgrades a Miniserver instance to a higher specification.
    
    :param name: Name of the service. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters.
    :type name: String
    
    :param new_sku: The SKU you wish to upgrade to. Acceptable values for Miniserver VM VPS packages (monthly billing) are
        
        ===   ===========
        sku   description
        ===   ===========
        ===   ===========
        
        
        Acceptable values for Miniserver cloud compute (billed hourly) are
        
        ===   ===========
        sku   description
        ===   ===========
        ===   ===========
        
        
        
    :type new_sku: String
    
    :param dry_run: If True, then the service is not provisioned but the information is still returned.
    :type dry_run: Boolean
    
    :param upgrade_disk: If set to False, the disk won't be upgraded. If you don't change your disk you can reduce the time required for the upgrade and later you'll have the option to downgrade your Miniserver if you need to.
    :type upgrade_disk: Boolean, Optional
    
    :returns: A dictionary with the following keys
    
      **new_sku**
          String: The new SKU of the server.
    
      **dry_run**
          Boolean: As specified in the API call.
    
      **currency**
          String: The currency of the order. You cannot specify the currency in the API request, the account's currency will be used. Currently, the account currency must be changed via the Memset website. Returned value will be one of 'GBP', 'USD', or 'EUR'.
    
      **net_setup_price**
          Float: There will be a one-off setup charge to cover the rental increase until the service expiry date, net of VAT. Only for Miniserver VM VPS Packages.
    
      **net_increase**
          Float: The increase of the monthly rental for the service, net of VAT. Only for Miniserver VM VPS packages.
    
      **net_hourly_inarrears_rental_price**
          Float: The new hourly rate for the service, net of VAT. Only for Miniserver cloud compute.
    
      **invoice_ref**
          Integer: The invoice reference for the order. Will not be provided if the method is called with ``dry_run=True``.
    
      **job**
          Dictionary: Provides the status of the job to set up the requested service. Will not be provided when the method is called with ``dry_run=True``. See :func:`job.status` for further details.
    
    This method is only available on Miniservers.
    
    See the following pages for princing and more information:
    
      - `Miniserver VM VPS Packages <https://www.memset.com/dedicated-servers/vps/>`_
      - `Miniserver cloud compute <https://www.memset.com/cloud/compute/>`_