Getting Started with the Python CLI

The SoftLayer API client includes a utility, sl, that provides a way to manage portions of a SoftLayer environment on the command line. Each section of the CLI shares a name with a manager that powers it. These managers wrap the necessary SoftLayer API calls and allow the CLI libraries to focus on data manipulation and display.

Setup

Install

The SLAPI CLI tool is included with the SoftLayer Python API Client. To install please follow these steps

Configure

The easiest way to get going it to use the automated configuration tool built into the CLI. This can be accessed with the arguments config setup. The configuration tool will prompt for your SoftLayer Portal username, API Key and Endpoint URL of choice. The default endpoint will be fine for most use cases.

If you do not already have an API key, your portal username can be used and the CLI will generate and populate your config with the a API key.

However you can also create/obtain an API key by following this guide

$ sl config setup
Username []: foo
API Key or Password []: bar
Endpoint (public|private|custom): public
:..............:..................................................................:
:         Name : Value                                                            :
:..............:..................................................................:
:     Username : foo                                                              :
:      API Key : bar                                                              :
: Endpoint URL : https://api.softlayer.com/xmlrpc/v3/                             :
:      Timeout : not set                                                          :
:..............:..................................................................:
Are you sure you want to write settings to "/Users/foo/.softlayer"? [Y/n]: y
Configuration Updated Successfully

These values can also be manually added to the configuration file manually

Help

A comprehensive help dialogue is available for all CLI features. A general help menu can be accessed with the -h flag. Typically this flag can also be added to the end of any command to obtain additional information.

$ sl -h
usage: sl <module> [<args>...]
       sl help <module>
       sl help <module> <command>
       sl [-h | --help]
 
SoftLayer Command-line Client
 
The available modules are:
 
Compute:
  bmc       Bare Metal Cloud
  cci       Cloud Compute Instances
  image     Manages compute and flex images
  metadata  Get details about this machine. Also available with 'my' and 'meta'
  server    Hardware servers
  sshkey    Manage SSH keys on your account
 
Networking:
  dns       Domain Name System
  firewall  Firewall rule and security management
  globalip  Global IP address management
  rwhois    RWhoIs operations
  ssl       Manages SSL
  subnet    Subnet ordering and management
  vlan      Manage VLANs on your account
 
Storage:
  iscsi     View iSCSI details
  nas       View NAS details
 
General:
  config    View and edit configuration for this tool
  summary   Display an overall summary of your account
  help      Show help

Additional documentation for any specific command or module can be found with sl <module> [<command>] -h

$ sl cci list -h
usage: sl cci list [--hourly | --monthly] [--sortby=SORT_COLUMN] [--tags=TAGS]
                   [options]
 
List CCIs
 
Examples:
    sl cci list --datacenter=dal05
    sl cci list --network=100 --cpu=2
    sl cci list --memory='>= 2048'
    sl cci list --tags=production,db
 
Options:
  --sortby=ARG  Column to sort by. options: id, datacenter, host,
                Cores, memory, primary_ip, backend_ip
 
Filters:
  -c --cpu=CPU             Number of CPU cores
  -D --domain=DOMAIN       Domain portion of the FQDN. example: example.com
  -d DC, --datacenter=DC   datacenter shortname (sng01, dal05, ...)
  -H --hostname=HOST       Host portion of the FQDN. example: server
  -m --memory=MEMORY       Memory in mebibytes
  -n MBPS, --network=MBPS  Network port speed in Mbps
  --hourly                 Show hourly instances
  --monthly                Show monthly instances
  --tags=ARG               Only show instances that have one of these tags.
                             Comma-separated. (production,db)
 
For more on filters see 'sl help filters'
 
Standard Options:
  --format=ARG           Output format. [Options: table, raw] [Default: table]
  -C FILE --config=FILE  Config file location. [Default: ~/.softlayer]
  --debug=LEVEL          Specifies the debug noise level
                           1=warn, 2=info, 3=debug
  --timings              Time each API call and display after results
  -h --help              Show this screen

Filters

Filters can be used to limit the number of responses from commands that accept them as arguments. You can access the filter help entry with sl help filters.

For example a list of all CCIs on an account has "webserver" in the hostname could be found with:

$ sl cci list --hostname='*webserver*'

In most cases you can even apply multiple filters:

$ sl cci list --network='< 100' --cpu 2

Examples

CCI

Create

Retrieve options

A listing of values for cci create variables can be obtained with sl cci create-options. These values will populate your order with the proper information.

$ sl cci create-options
:.................:....................................................................................................:
:            Name : Value                                                                                              :
:.................:....................................................................................................:
:      datacenter : ams01,dal05,sea01,sjc01,sng01,wdc01                                                                :
:  cpus (private) : 1,2,4,8                                                                                            :
: cpus (standard) : 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16                                                             :
:          memory : 1024,2048,3072,4096,5120,6144,7168,8192,9216,10240,11264,12288,13312,14336,15360,16384,32768,49152 :
:     os (CENTOS) : CENTOS_5_32                                                                                        :
:                 : CENTOS_5_64                                                                                        :
:                 : CENTOS_6_32
...
Creating the CCI

After the appropriate values have been chosen you can create a CCI with sl cci create <options>:

$ sl cci create --hostname=foo-webserver --domain=example.com --cpu=1 --memory=1024 --hourly --os=DEBIAN_7_64
This action will incur charges on your account. Continue? [y/N]: y
:.........:......................................:
:    name : value                                :
:.........:......................................:
:      id : 1234212                              :
: created : 2013-09-30T06:51:02-06:00            :
:    guid : 093nt23n-90nl-9n2i-u902-902n3t09n23t :
:.........:......................................:

The CLI will either respond as it has above with the details of your new instance, or it will provide an error message explaining what went wrong.

Cancel

The cancellation command in the CCI argument will deprovision a CCI and remove its billing from you account. Cancellation is a destructive action - back up all data you wish to retain before running this command, as we do not keep records of information stored on your device.. Cancellation of an instance will result in the immediate destruction of the target CCI.

When using the cancel command you will be prompted to enter the CCI ID to start the cancellation process.

$ sl cci cancel pjackson-cli-test
This action cannot be undone! Type "341234" or press Enter to abort: 341234

Reboot

Reboot a CCI with the sl cci reboot command. YoYou will be prompted to confirm the reboot before it begins. By default a soft reboot is attempted with the --soft option which will gracefully restart the device. If unable to complete a soft reboot, the --hard switch can be passed which will simulate a power cycling of the device.

$ sl cci reboot foo-webserver
This will reboot the CCI with id 1234212. Continue? [y/N]: y

Retrieve a list of all CCIs on your account can be retrieved with sl cci list. Filter your results by adding the appropriate switch.

$ sl cci list --datacenter=dal05

DNS

Interact with our authoritative DNS service through the dns module.

$ sl dns
usage: sl dns [<command>] [<args>...] [options]
 
Manage DNS
 
The available zone commands are:
  create  Create zone
  delete  Delete zone
  list    List zones or a zone's records
  print   Print zone in BIND format
 
The available record commands are:
  add     Add resource record
  edit    Update resource records (bulk/single)
  remove  Remove resource records

The module contains two subsections: zone and record

Zone Print

The contents of a BIND zone file can be printed to the screen with the print command.

$ sl dns print example.com
$ORIGIN example.com.
$TTL 86400
@ IN SOA ns1.softlayer.com. support.softlayer.com. (
                       2013041501        ; Serial
                       7200              ; Refresh
                       600               ; Retry
                       1728000           ; Expire
                       43200)            ; Minimum
 
@                      86400    IN NS    ns1.softlayer.com.
@                      86400    IN NS    ns2.softlayer.com.
 
 
@                      86400    IN A     127.0.0.1
server01               7200     IN A     127.0.0.1

Zone Creation

Create a new zone combining the create command with the path for the new zone.

$ sl dns create phil.example.com

Record Creation

Zone records are created with the add command. Enter the zone along with the desired record type and corresponding record details. This example creates an A record for the IP 127.0.0.1 with a standard ttl of 86400.

$ sl dns add phil.example.com mail A 127.0.0.1 --ttl=86400

Record Editing

Edit a zone record with the edit command.

$ sl dns edit phil.example.com mail --data=192.168.1.1