NAME

    WebService::Linode - Perl Interface to the Linode.com API.

SYNOPSIS

        my $api = WebService::Linode->new( apikey => 'your api key here');
        print Dumper($api->linode_list);
        $api->linode_reboot(linodeid=>242);

    This module implements the Linode.com api methods. Linode methods have
    had dots replaced with underscores to generate the perl method name.
    All keys and parameters have been lower cased but returned data remains
    otherwise the same. For additional information see
    http://www.linode.com/api/

Constructor

    For documentation of possible arguments to the constructor, see
    WebService::Linode::Base.

Batch requests

    Each of the Linode API methods below may optionally be prefixed with
    QUEUE_ to add that request to a queue to be processed later in one or
    more batch requests which can be processed by calling
    send_queued_requests. For example:

        my @linode_ids = () # Get your linode ids through normal methods
        my @responses = map { $api->linode_ip_list( linodeid=>$_ ) } @linode_ids;

    Can be reduced to a single request:

        my @linode_ids = () # Get your linode ids through normal methods
        $api->QUEUE_linode_ip_list( linodeid=>$_ ) for @linode_ids;
        my @responses = $api->send_queued_requests; # One api request

    See WebService::Linode::Base for additional queue management methods.

  send_queued_requests

    Send queued batch requests, returns list of responses.

Methods from the Linode API

 account Methods

  account_estimateinvoice

    Estimates the invoice for adding a new Linode or NodeBalancer as well
    as resizing a Linode. This returns two fields: PRICE which is the
    estimated cost of the invoice, and INVOICE_TO which is the date invoice
    would be though with timezone set to America/New_York

    Required Parameters:

      * mode

      This is one of the following options: 'linode_new', 'linode_resize',
      or 'nodebalancer_new'.

    Optional Parameters:

      * paymentterm

      Subscription term in months. One of: 1, 12, or 24. This is required
      for modes 'linode_new' and 'nodebalancer_new'.

      * planid

      The desired PlanID available from avail.LinodePlans(). This is
      required for modes 'linode_new' and 'linode_resize'.

      * linodeid

      This is the LinodeID you want to resize and is required for mode
      'linode_resize'.

  account_info

    Shows information about your account such as the date your account was
    opened as well as your network utilization for the current month in
    gigabytes.

  account_paybalance

    Pays current balance on file, returning it in the response.

  account_updatecard

    Required Parameters:

      * ccnumber

      * ccexpyear

      * ccexpmonth

 avail Methods

  avail_datacenters

    Returns a list of Linode data center facilities.

  avail_distributions

    Returns a list of available Linux Distributions.

    Optional Parameters:

      * distributionid

      Limits the results to the specified DistributionID

  avail_kernels

    List available kernels.

    Optional Parameters:

      * iskvm

      Show or hide KVM compatible kernels

      * isxen

      Show or hide Xen compatible kernels

  avail_linodeplans

    Returns a structure of Linode PlanIDs containing the Plan label and the
    availability in each Datacenter.

    Optional Parameters:

      * planid

      Limits the list to the specified PlanID

  avail_nodebalancers

    Returns NodeBalancer pricing information.

  avail_stackscripts

    Returns a list of available public StackScripts.

    Optional Parameters:

      * keywords

      Search terms

      * distributionvendor

      Debian, Ubuntu, Fedora, etc.

      * distributionid

      Limit the results to StackScripts that can be applied to this
      DistributionID

 domain Methods

  domain_create

    Create a domain record.

    Required Parameters:

      * type

      master or slave

      * domain

      The zone's name

    Optional Parameters:

      * lpm_displaygroup

      Display group in the Domain list inside the Linode DNS Manager

      * soa_email

      Required when type=master

      * description

      Currently undisplayed.

      * retry_sec

      * status

      0, 1, or 2 (disabled, active, edit mode)

      * axfr_ips

      IP addresses allowed to AXFR the entire zone, semicolon separated

      * refresh_sec

      * expire_sec

      * master_ips

      When type=slave, the zone's master DNS servers list, semicolon
      separated

      * ttl_sec

  domain_delete

    Required Parameters:

      * domainid

  domain_list

    Lists domains you have access to.

    Optional Parameters:

      * domainid

      Limits the list to the specified DomainID

  domain_update

    Update a domain record.

    Required Parameters:

      * domainid

    Optional Parameters:

      * ttl_sec

      * master_ips

      When type=slave, the zone's master DNS servers list, semicolon
      separated

      * expire_sec

      * refresh_sec

      * axfr_ips

      IP addresses allowed to AXFR the entire zone, semicolon separated

      * domain

      The zone's name

      * status

      0, 1, or 2 (disabled, active, edit mode)

      * retry_sec

      * soa_email

      Required when type=master

      * description

      Currently undisplayed.

      * lpm_displaygroup

      Display group in the Domain list inside the Linode DNS Manager

      * type

      master or slave

 domain_resource Methods

  domain_resource_create

    Create a domain record.

    Required Parameters:

      * domainid

      * type

      One of: NS, MX, A, AAAA, CNAME, TXT, SRV or CAA

    Optional Parameters:

      * ttl_sec

      TTL. Leave as 0 to accept our default.

      * protocol

      The protocol to append to an SRV record. Ignored on other record
      types.

      * port

      * name

      The hostname or FQDN. When Type=MX the subdomain to delegate to the
      Target MX server.

      * tag

      The tag attribute for a CAA record. One of issue, issuewild, iodef.
      Ignored on other record types.

      * target

      When Type=MX the hostname. When Type=CNAME the target of the alias.
      When Type=TXT or CAA the value of the record. When Type=A or AAAA the
      token of '[remote_addr]' will be substituted with the IP address of
      the request.

      * priority

      Priority for MX and SRV records, 0-65535

      * weight

  domain_resource_delete

    Required Parameters:

      * domainid

      * resourceid

  domain_resource_list

    Required Parameters:

      * domainid

    Optional Parameters:

      * resourceid

  domain_resource_update

    Update a domain record.

    Required Parameters:

      * resourceid

    Optional Parameters:

      * port

      * tag

      The tag attribute for a CAA record. One of issue, issuewild, iodef.
      Ignored on other record types.

      * target

      When Type=MX the hostname. When Type=CNAME the target of the alias.
      When Type=TXT or CAA the value of the record. When Type=A or AAAA the
      token of '[remote_addr]' will be substituted with the IP address of
      the request.

      * domainid

      * name

      The hostname or FQDN. When Type=MX the subdomain to delegate to the
      Target MX server.

      * protocol

      The protocol to append to an SRV record. Ignored on other record
      types.

      * ttl_sec

      TTL. Leave as 0 to accept our default.

      * priority

      Priority for MX and SRV records, 0-65535

      * weight

 linode Methods

  linode_boot

    Issues a boot job for the provided ConfigID. If no ConfigID is provided
    boots the last used configuration profile, or the first configuration
    profile if this Linode has never been booted.

    Required Parameters:

      * linodeid

    Optional Parameters:

      * configid

      The ConfigID to boot, available from linode.config.list().

  linode_clone

    Creates a new Linode, assigns you full privileges, and then clones the
    specified LinodeID to the new Linode. There is a limit of 5 active
    clone operations per source Linode. It is recommended that the source
    Linode be powered down during the clone.

    Required Parameters:

      * linodeid

      The LinodeID that you want cloned

      * planid

      The desired PlanID available from avail.LinodePlans()

      * datacenterid

      The DatacenterID from avail.datacenters() where you wish to place
      this new Linode

    Optional Parameters:

      * paymentterm

      Subscription term in months for prepaid customers. One of: 1, 12, or
      24

  linode_create

    Creates a Linode and assigns you full privileges. There is a
    250-linodes-per-hour limiter.

    Required Parameters:

      * datacenterid

      The DatacenterID from avail.datacenters() where you wish to place
      this new Linode

      * planid

      The desired PlanID available from avail.LinodePlans()

    Optional Parameters:

      * paymentterm

      Subscription term in months for prepaid customers. One of: 1, 12, or
      24

  linode_delete

    Immediately removes a Linode from your account and issues a pro-rated
    credit back to your account, if applicable. To prevent accidental
    deletes, this requires the Linode has no Disk images. You must first
    delete its disk images."

    Required Parameters:

      * linodeid

      The LinodeID to delete

    Optional Parameters:

      * skipchecks

      Skips the safety checks and will always delete the Linode

  linode_kvmify

    Changes a Linode's hypervisor from Xen to KVM.

    Required Parameters:

      * linodeid

      The LinodeID to migrate to KVM.

  linode_list

    Returns a list of all Linodes user has access or delete to, including
    some properties. Status values are -1: Being Created, 0: Brand New, 1:
    Running, and 2: Powered Off.

    Optional Parameters:

      * linodeid

      Limits the list to the specified LinodeID

  linode_mutate

    Upgrades a Linode to its next generation.

    Required Parameters:

      * linodeid

  linode_reboot

    Issues a shutdown, and then boot job for a given LinodeID.

    Required Parameters:

      * linodeid

    Optional Parameters:

      * configid

  linode_resize

    Resizes a Linode from one plan to another. Immediately shuts the Linode
    down, charges/credits the account, and issue a migration to another
    host server.

    Required Parameters:

      * linodeid

      * planid

      The desired PlanID available from avail.LinodePlans()

  linode_shutdown

    Issues a shutdown job for a given LinodeID.

    Required Parameters:

      * linodeid

  linode_update

    Updates a Linode's properties.

    Required Parameters:

      * linodeid

    Optional Parameters:

      * label

      This Linode's label

      * alert_bwquota_enabled

      Enable the bw quote email alert

      * ms_ssh_port

      * ms_ssh_ip

      * ms_ssh_disabled

      * alert_bwout_threshold

      Mb/sec

      * alert_diskio_threshold

      IO ops/sec

      * backupweeklyday

      * alert_cpu_enabled

      Enable the cpu usage email alert

      * alert_bwquota_threshold

      Percentage of monthly bw quota

      * backupwindow

      * lpm_displaygroup

      Display group in the Linode list inside the Linode Manager

      * alert_diskio_enabled

      Enable the disk IO email alert

      * alert_cpu_threshold

      CPU Alert threshold, percentage 0-800

      * alert_bwin_threshold

      Mb/sec

      * watchdog

      Enable the Lassie shutdown watchdog

      * alert_bwout_enabled

      Enable the outgoing bandwidth email alert

      * ms_ssh_user

      * alert_bwin_enabled

      Enable the incoming bandwidth email alert

  linode_webconsoletoken

    Generates a console token starting a web console LISH session for the
    requesting IP

    Required Parameters:

      * linodeid

 linode_config Methods

  linode_config_create

    Creates a Linode Configuration Profile.

    Required Parameters:

      * kernelid

      The KernelID for this profile. Found in avail.kernels()

      * label

      The Label for this profile

      * linodeid

      * disklist

      A comma delimited list of DiskIDs; position reflects device node. The
      9th element for specifying the initrd.

    Optional Parameters:

      * helper_depmod

      Creates an empty modprobe file for the kernel you're booting.

      * helper_network

      Automatically creates network configuration files for your distro and
      places them into your filesystem.

      * runlevel

      One of 'default', 'single', 'binbash'

      * rootdevicecustom

      A custom root device setting.

      * rootdevicenum

      Which device number (1-8) that contains the root partition. 0 to
      utilize RootDeviceCustom.

      * helper_disableupdatedb

      Enable the disableUpdateDB filesystem helper

      * helper_distro

      Enable the Distro filesystem helper. Corrects fstab and
      inittab/upstart entries depending on the kernel you're booting. You
      want this.

      * comments

      Comments you wish to save along with this profile

      * virt_mode

      Controls the virtualization mode. One of 'paravirt', 'fullvirt'

      * ramlimit

      RAMLimit in MB. 0 for max.

      * helper_xen

      Deprecated - use helper_distro.

      * rootdevicero

      Enables the 'ro' kernel flag. Modern distros want this.

      * devtmpfs_automount

      Controls if pv_ops kernels should automount devtmpfs at boot.

  linode_config_delete

    Deletes a Linode Configuration Profile.

    Required Parameters:

      * configid

      * linodeid

  linode_config_list

    Lists a Linode's Configuration Profiles.

    Required Parameters:

      * linodeid

    Optional Parameters:

      * configid

  linode_config_update

    Updates a Linode Configuration Profile.

    Required Parameters:

      * configid

    Optional Parameters:

      * helper_depmod

      Creates an empty modprobe file for the kernel you're booting.

      * helper_network

      Automatically creates network configuration files for your distro and
      places them into your filesystem.

      * runlevel

      One of 'default', 'single', 'binbash'

      * kernelid

      The KernelID for this profile. Found in avail.kernels()

      * label

      The Label for this profile

      * helper_distro

      Enable the Distro filesystem helper. Corrects fstab and
      inittab/upstart entries depending on the kernel you're booting. You
      want this.

      * comments

      Comments you wish to save along with this profile

      * rootdevicecustom

      A custom root device setting.

      * rootdevicenum

      Which device number (1-8) that contains the root partition. 0 to
      utilize RootDeviceCustom.

      * linodeid

      * helper_disableupdatedb

      Enable the disableUpdateDB filesystem helper

      * disklist

      A comma delimited list of DiskIDs; position reflects device node. The
      9th element for specifying the initrd.

      * virt_mode

      Controls the virtualization mode. One of 'paravirt', 'fullvirt'

      * ramlimit

      RAMLimit in MB. 0 for max.

      * rootdevicero

      Enables the 'ro' kernel flag. Modern distros want this.

      * devtmpfs_automount

      Controls if pv_ops kernels should automount devtmpfs at boot.

      * helper_xen

      Deprecated - use helper_distro.

 linode_disk Methods

  linode_disk_create

    Required Parameters:

      * size

      The size in MB of this Disk.

      * type

      The formatted type of this disk. Valid types are: ext3, ext4, swap,
      raw

      * label

      The display label for this Disk

      * linodeid

    Optional Parameters:

      * isreadonly

      Enable forced read-only for this Disk

  linode_disk_createfromdistribution

    Required Parameters:

      * rootpass

      The root (or core) user's password

      * size

      Size of this disk image in MB

      * linodeid

      * distributionid

      The DistributionID to create this disk from. Found in
      avail.distributions()

      * label

      The label of this new disk image

    Optional Parameters:

      * rootsshkey

      Optionally sets this string into /root/.ssh/authorized_keys (or
      /home/core/.ssh/authorized_keys) upon distribution configuration.

  linode_disk_createfromimage

    Creates a new disk from a previously imagized disk.

    Required Parameters:

      * linodeid

      Specifies the Linode to deploy on to

      * imageid

      The ID of the frozen image to deploy from

    Optional Parameters:

      * label

      The label of this new disk image

      * size

      The size of the disk image to creates. Defaults to the minimum size
      required for the requested image

      * rootsshkey

      Optionally sets this string into /root/.ssh/authorized_keys upon
      image deployment

      * rootpass

      Optionally sets the root password at deployment time. If a password
      is not provided the existing root password of the frozen image will
      not be modified

  linode_disk_createfromstackscript

    Required Parameters:

      * linodeid

      * rootpass

      The root user's password

      * size

      Size of this disk image in MB

      * stackscriptudfresponses

      JSON encoded name/value pairs, answering this StackScript's User
      Defined Fields

      * distributionid

      Which Distribution to apply this StackScript to. Must be one from the
      script's DistributionIDList

      * stackscriptid

      The StackScript to create this image from

      * label

      The label of this new disk image

    Optional Parameters:

      * rootsshkey

      Optionally sets this string into /root/.ssh/authorized_keys upon
      distribution configuration.

  linode_disk_delete

    Required Parameters:

      * diskid

      * linodeid

  linode_disk_duplicate

    Performs a bit-for-bit copy of a disk image.

    Required Parameters:

      * linodeid

      * diskid

  linode_disk_imagize

    Creates a gold-master image for future deployments

    Required Parameters:

      * linodeid

      Specifies the source Linode to create the image from

      * diskid

      Specifies the source Disk to create the image from

    Optional Parameters:

      * label

      Sets the name of the image shown in the base image list, defaults to
      the source image label

      * description

      An optional description of the created image

  linode_disk_list

    Status values are 1: Ready and 2: Being Deleted.

    Required Parameters:

      * linodeid

    Optional Parameters:

      * diskid

  linode_disk_resize

    Required Parameters:

      * diskid

      * linodeid

      * size

      The requested new size of this Disk in MB

  linode_disk_update

    Required Parameters:

      * diskid

    Optional Parameters:

      * linodeid

      * label

      The display label for this Disk

      * isreadonly

      Enable forced read-only for this Disk

 linode_ip Methods

  linode_ip_addprivate

    Assigns a Private IP to a Linode. Returns the IPAddressID that was
    added.

    Required Parameters:

      * linodeid

  linode_ip_addpublic

    Assigns a Public IP to a Linode. Returns the IPAddressID and IPAddress
    that was added.

    Required Parameters:

      * linodeid

      The LinodeID of the Linode that will be assigned an additional public
      IP address

  linode_ip_list

    Returns the IP addresses of all Linodes you have access to.

    Optional Parameters:

      * linodeid

      If specified, limits the result to this LinodeID

      * ipaddressid

      If specified, limits the result to this IPAddressID

  linode_ip_setrdns

    Sets the rDNS name of a Public IP. Returns the IPAddressID and
    IPAddress that were updated.

    Required Parameters:

      * hostname

      The hostname to set the reverse DNS to

      * ipaddressid

      The IPAddressID of the address to update

  linode_ip_swap

    Exchanges Public IP addresses between two Linodes within a Datacenter.
    The destination of the IP Address can be designated by either the
    toLinodeID or withIPAddressID parameter. Returns the resulting
    relationship of the Linode and IP Address parameters. When performing a
    one directional swap, the source is represented by the first of the two
    resultant array members.

    Required Parameters:

      * ipaddressid

      The IPAddressID of an IP Address to transfer or swap

    Optional Parameters:

      * tolinodeid

      The LinodeID of the Linode where IPAddressID will be transfered

      * withipaddressid

      The IP Address ID to swap

 linode_job Methods

  linode_job_list

    Required Parameters:

      * linodeid

    Optional Parameters:

      * pendingonly

      * jobid

      Limits the list to the specified JobID

 stackscript Methods

  stackscript_create

    Create a StackScript.

    Required Parameters:

      * distributionidlist

      Comma delimited list of DistributionIDs that this script works on

      * script

      The actual script

      * label

      The Label for this StackScript

    Optional Parameters:

      * description

      * rev_note

      * ispublic

      Whether this StackScript is published in the Library, for everyone to
      use

  stackscript_delete

    Required Parameters:

      * stackscriptid

  stackscript_list

    Lists StackScripts you have access to.

    Optional Parameters:

      * stackscriptid

      Limits the list to the specified StackScriptID

  stackscript_update

    Update a StackScript.

    Required Parameters:

      * stackscriptid

    Optional Parameters:

      * script

      The actual script

      * label

      The Label for this StackScript

      * rev_note

      * ispublic

      Whether this StackScript is published in the Library, for everyone to
      use

      * description

      * distributionidlist

      Comma delimited list of DistributionIDs that this script works on

 nodeblancer Methods

 nodebalancer_config Methods

  nodebalancer_config_create

    Required Parameters:

      * nodebalancerid

      The parent NodeBalancer's ID

    Optional Parameters:

      * cipher_suite

      SSL cipher suite to enforce. One of 'recommended', 'legacy'

      * check_interval

      Seconds between health check probes. 2-3600

      * port

      Port to bind to on the public interfaces. 1-65534

      * check

      Perform active health checks on the backend nodes. One of
      'connection', 'http', 'http_body'

      * check_attempts

      Number of failed probes before taking a node out of rotation. 1-30

      * stickiness

      Session persistence. One of 'none', 'table', 'http_cookie'

      * protocol

      Either 'tcp', 'http', or 'https'

      * check_passive

      Enable passive checks based on observing communication with back-end
      nodes.

      * check_body

      When check=http, a regex to match within the first 16,384 bytes of
      the response body

      * check_timeout

      Seconds to wait before considering the probe a failure. 1-30. Must be
      less than check_interval.

      * check_path

      When check=http, the path to request

      * ssl_key

      Unpassphrased private key for the SSL certificate when protocol is
      'https'

      * algorithm

      Balancing algorithm. One of 'roundrobin', 'leastconn', 'source'

      * ssl_cert

      SSL certificate served by the NodeBalancer when the protocol is
      'https'

  nodebalancer_config_delete

    Deletes a NodeBalancer's Config

    Required Parameters:

      * nodebalancerid

      * configid

      The ConfigID to delete

  nodebalancer_config_list

    Returns a list of NodeBalancers this user has access or delete to,
    including their properties

    Required Parameters:

      * nodebalancerid

    Optional Parameters:

      * configid

      Limits the list to the specified ConfigID

  nodebalancer_config_update

    Updates a Config's properties

    Required Parameters:

      * configid

    Optional Parameters:

      * check_timeout

      Seconds to wait before considering the probe a failure. 1-30. Must be
      less than check_interval.

      * stickiness

      Session persistence. One of 'none', 'table', 'http_cookie'

      * check_attempts

      Number of failed probes before taking a node out of rotation. 1-30

      * check_body

      When check=http, a regex to match within the first 16,384 bytes of
      the response body

      * protocol

      Either 'tcp', 'http', or 'https'

      * check_passive

      Enable passive checks based on observing communication with back-end
      nodes.

      * check

      Perform active health checks on the backend nodes. One of
      'connection', 'http', 'http_body'

      * port

      Port to bind to on the public interfaces. 1-65534

      * check_interval

      Seconds between health check probes. 2-3600

      * cipher_suite

      SSL cipher suite to enforce. One of 'recommended', 'legacy'

      * ssl_cert

      SSL certificate served by the NodeBalancer when the protocol is
      'https'

      * algorithm

      Balancing algorithm. One of 'roundrobin', 'leastconn', 'source'

      * ssl_key

      Unpassphrased private key for the SSL certificate when protocol is
      'https'

      * check_path

      When check=http, the path to request

 nodebalancer_node Methods

  nodebalancer_node_create

    Required Parameters:

      * address

      The address:port combination used to communicate with this Node

      * configid

      The parent ConfigID to attach this Node to

      * label

      This backend Node's label

    Optional Parameters:

      * weight

      Load balancing weight, 1-255. Higher means more connections.

      * mode

      The connections mode for this node. One of 'accept', 'reject',
      'backup', or 'drain'

  nodebalancer_node_delete

    Deletes a Node from a NodeBalancer Config

    Required Parameters:

      * nodeid

      The NodeID to delete

  nodebalancer_node_list

    Returns a list of Nodes associated with a NodeBalancer Config

    Required Parameters:

      * configid

    Optional Parameters:

      * nodeid

      Limits the list to the specified NodeID

  nodebalancer_node_update

    Updates a Node's properties

    Required Parameters:

      * nodeid

    Optional Parameters:

      * label

      This backend Node's label

      * mode

      The connections mode for this node. One of 'accept', 'reject',
      'backup', or 'drain'

      * address

      The address:port combination used to communicate with this Node

      * weight

      Load balancing weight, 1-255. Higher means more connections.

 user Methods

  user_getapikey

    Authenticates a Linode Manager user against their username, password,
    and two-factor token (when enabled), and then returns a new API key,
    which can be used until it expires. The number of active keys is
    limited to 20. Batch requests will be rejected if they include this API
    action.

    Required Parameters:

      * password

      * username

    Optional Parameters:

      * label

      An optional label for this key.

      * token

      Required when two-factor authentication is enabled. Emergency scratch
      codes are not permitted.

      * expires

      Number of hours the key will remain valid, between 0 and 8760. 0
      means no expiration. Defaults to 168.

 image Methods

  image_delete

    Deletes a gold-master image

    Required Parameters:

      * imageid

      The ID of the gold-master image to delete

  image_list

    Lists available gold-master images

    Optional Parameters:

      * pending

      Show images currently being created.

      * imageid

      Request information for a specific gold-master image

  image_update

    Update an Image record.

    Required Parameters:

      * imageid

      The ID of the Image to modify.

    Optional Parameters:

      * description

      An optional description of the Image.

      * label

      The label of the Image.

 professionalservices_scope Methods

AUTHORS

      * Michael Greb, <michael@thegrebs.com>

      * Stan "The Man" Schwertly <stan@schwertly.com>

COPYRIGHT & LICENSE

    Copyright 2008-2014 Michael Greb, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

