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.