Inventory

The inventory file holds information about your hosting provider(s) and host(s), so beam knows how to contact the relevant API endpoints and what credentials to use. Here’s a sample file:

[special:vendors]
ramnode = https://vpscp.ramnode.com
vendor2 = https://vendor2-panel.com
default = ramnode

[nyc-1]
key = nyc-1_host_key
hash = nyc-1_host_hash

[ams-1]
key = ams-1_host_key
hash = ams-1_host_hash
vendor = vendor2

This file defines two hosts, nyc-1, hosted with RamNode, and ams-1, hosted with FlipHost. At the top are the vendor names in a special vendors section (all other sections are assumed to represent hosts). The format maps a vendor name to their base endpoint for the SolusVM API. The default directive indicates the implicit vendor of every host, and must be specified if more than one vendor is defined.

Each host has its own section. The correct key and hash values can be optained from the SolusVM control panel used by your vendor. If a host is not provided by the default vendor, a vendor directive specifies the correct one.

CLI

The CLI client can be used to find information about a single host.

$ beam --help
usage: beam [-h] [-V]
            (-A {boot,reboot,shutdown} | -a ATTRIBUTES [ATTRIBUTES ...])
            [host]

A lightweight wrapper for the SolusVM client API.

positional arguments:
  host                  the identifier of the host whose information to
                        retrieve

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -A {boot,reboot,shutdown}, --action {boot,reboot,shutdown}
                        an action to execute against the host
  -a ATTRIBUTES [ATTRIBUTES ...], --attributes ATTRIBUTES [ATTRIBUTES ...]
                        one or more attributes of the host to retrieve
$ beam -a bandwidth.free_percentage nyc-1
0.4983459835
$ beam -a primary_ip lon-1
2604:180:2:32b::498b
$ beam -a is_online memory.used_bytes ams-1
True
34578234983
$ beam -A shutdown nyc-1
OK

Library

import beam

# shutdown a specific host
host = beam.host('nyc-1')  # name, key or hash
if host.is_online:
    host.shutdown()

# boot all offline hosts
[host.boot() for host in beam.hosts() if not host.is_online]

# get a list of hosts using above 90% of their memory
hosts = [host for host in beam.hosts()
         if host.memory.used_percentage > .9]

# get a list of hosts with less than 10 GiB of storage left
hosts = [host for host in beam.hosts()
         if host.storage.free_bytes < 1024 ** 3 * 10]