Beacon

Beacon provides a command-line interface to apnscp API + module introspection.

Usage

Prerequisites

Beacon requires a key to be setup first in the control panel. Visit Dev > API Keys to generate a key. Beacon also requires at least PHP7, which restricts operation to v6.5+ platforms. Set the key by running exec with --key. Overwrite a previously configured key with -s:

beacon exec --key=somekey -s common_get_uptime

Commands

show

show service Display underlying code for given service

Example

beacon show common_get_load

Example response

/**
 * array get_load (void)
 *
 * @privilege PRIVILEGE_ALL
 * @return array returns an assoc array of the 1, 5, and 15 minute
 * load averages; indicies of 1,5,15
 */
 public function get_load()
 {
     $fp = fopen('/proc/loadavg', 'r');
     $loadData = fgets($fp);
     fclose($fp);
     $loadData = array_slice(explode(" ", $loadData), 0, 3);
     return array_combine(array(1, 5, 15), $loadData);
 }

exec

exec flags service [args, ...] Executes named service with optional args

Example

beacon exec common_get_uptime

Example response

25 days 10 mins

Optional flags

• format [json, bash, php] Alter output format

beacon exec --format=json common_get_load

{"1":"0.00","5":"0.00","15":"0.00"}

beacon exec --format=php common_get_load

Array
(
    [1] => 0.04
    [5] => 0.01
    [15] => 0.00
)

beacon exec --format=bash common_get_load

(["1"]="0.04" ["5"]="0.01" ["15"]="0.00")

Bash formatting can be used in shell scripting to populate variables, e.g.

declare -a load=`beacon exec --format=bash common_get_load`
echo ${load[1]}

• set Set API key as default on exit

• key key Specify an API key, key

• keyfile file Specify a file, file that contains the API key to use. The file should be formatted as empty consisting of nothing but the key.

• endpoint url Use the endpoint url instead of http://localhost:2082/soap.

arrays and hashes

Arrays and hashes are fed using a bracketed expression [] which may also be nested.

beacon e file_delete '[/tmp/a, /tmp/b]'

beacon e user_add_user "newuser" "newpassword" "some new user" '[imap:1,smtp:1]'

null and bool types

null and false may be passed verbatim to indicate a null or true/false parameter. To pass a string literal of the corresponding type, surround the argument with both single and double quotes,

Clear ACLs for user myuser

beacon e file_set_acls /home/foo myuser null

This is interchangeable, due to shell parsing mechanics, to,

beacon e file_set_acls /home/foo myuser "null"

Set read, write, execute for user "null"

beacon e file_set_acls /home/foo "'null'" 7

API reference

All modules are available through api.apnscp.com. Modules that follow the naming XXX_Module are exposed as xxx, for example methods in File_Module are exposed as file_<method> and set_acls in File_Module is referenced as file_set_acls.