Notes
-
Default SlapOS Master is https://slapos.vifib.com. It can be changed by altering configuration files or with the --master-url argument for commands that support it.
-
Most commands take a configuration file parameter, provided as --cfg /path/to/file.cfg.
If no such argument is provided:
- “
node
” commands read configuration from /etc/opt/slapos/slapos.cfg, or the file referenced by the SLAPOS_CONFIGURATION environment variable.
- likewise, “client” commands (request, supply...) use ~/.slapos/slapos.cfg, or the SLAPOS_CLIENT_CONFIGURATION variable.
Common options
Without arguments, the slapos program lists all the available commands and common options.
usage: slapos [--version] [-v] [-q] [--debug] [--log-file LOG_FILE] [-h]
usage: slapos [--version] [-v] [-q] [--debug] [--log-file LOG_FILE] [-h]
SlapOS client 1.2.4.1
optional arguments:
--version show program's version number and exit
-v, --verbose Increase verbosity of output. Can be repeated.
-q, --quiet suppress output except warnings and errors
--debug show tracebacks on errors
--log-file LOG_FILE, --logfile LOG_FILE, --log_file LOG_FILE
Specify a file to log output (default: console only)
-h, --help show this help message and exit
client commands:
configure client configure slapos client with an existing account
console open python console with slap library imported
remove remove a Software from a node
request request an instance and get status and parameters of instance
supply supply a Software to a node
node commands:
node bang request update on all partitions
node boot Test network and invoke simple format and bang (Use on Linux startup)
node collect Collect system consumption and data and store.
node format create users, partitions and network configuration
node instance run instance deployment
node register register a node in the SlapOS cloud
node report run instance reports and garbage collection
node restart alias for 'node supervisorctl restart'
node software run software installation/deletion
node start alias for 'node supervisorctl start'
node status alias for 'node supervisorctl status'
node stop alias for 'node supervisorctl stop'
node supervisorctl open supervisor console, for process management
node supervisord launch, if not already running, supervisor daemon
node tail alias for 'node supervisorctl tail'
other commands:
cache lookup perform a query to the networkcache
complete print bash completion command
configure local Configure a slapos node, from scratch to ready-ro-use, using slapproxy.
help print detailed help for another command
proxy show display proxy instances and parameters
proxy start minimalist, stand-alone SlapOS Master
The -q and -v options control the verbosity of console output (-v: DEBUG, default: INFO, -q: WARNING).
Output to a logfile is not affected, and is the same as -v.
SlapOS Client commands
These commands are used by clients (as human beings or programs) to manage their own instances.
configure client
configure slapos client with an existing account
usage: slapos configure client [-h] [--cfg CFG] [--master-url MASTER_URL]
[--master-url-web MASTER_URL_WEB]
[--token TOKEN]
configure slapos client with an existing account
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-
client.cfg)
--master-url MASTER_URL
URL of SlapOS Master REST API (default:
https://slap.vifib.com)
--master-url-web MASTER_URL_WEB
URL of SlapOS Master webservice to register
certificates (default: https://www.slapos.org)
--token TOKEN SlapOS 'credential security' authentication token (use
'--token ask' for interactive prompt)
configure local
configure slapos node, slapos proxy and slapos client to work in a self-contained, autonomous way, without any external slapos master.
usage: slapos configure local [-h] [--cfg CFG]
[--interface-name INTERFACE_NAME]
[--partition-number PARTITION_NUMBER]
[--ipv4-local-network IPV4_LOCAL_NETWORK]
[--daemon-listen-ip DAEMON_LISTEN_IP]
[--daemon-listen-port DAEMON_LISTEN_PORT]
[--slapos-instance-root SLAPOS_INSTANCE_ROOT]
[--slapos-software-root SLAPOS_SOFTWARE_ROOT]
[--slapos-buildout-directory SLAPOS_BUILDOUT_DIRECTORY]
[--slapos-configuration-directory SLAPOS_CONFIGURATION_DIRECTORY]
Configure a slapos node, from scratch to ready-ro-use, using slapproxy.
request
usage: slapos request [-h] [--cfg CFG] [--node NODE [NODE ...]] [--type TYPE]
[--state STATE] [--slave]
[--parameters PARAMETERS [PARAMETERS ...]]
reference software_url
request an instance and get status and parameters of instance
positional arguments:
reference Your instance reference
software_url Your software url
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-
client.cfg)
--node NODE [NODE ...]
Node request option 'option1=value1 option2=value2'
(i.e. computer_guid=COMP-1234)
--type TYPE Software type to be requested
--state STATE State of the requested instance
--slave Ask for a slave instance
--parameters PARAMETERS [PARAMETERS ...]
Give your configuration 'option1=value1
option2=value2'
Request the deployment of a service (instance).
Examples
$ slapos request "My Beautiful Instance" wordpress --node computer_guid=COMP-12345
-
Request a wordpress instance named "mybeautifulinstance" on any available machine (either owned by user, public, or shared by other user to current user):
$ slapos request mybeautifulinstance wordpress
- Request a wordpress instance named "My Beautiful Instance" on Node named "COMP-12345":
-
Request a kvm instance named “mykvm” on Node named “COMP-12345”, specifying nbd-host and nbd-ip parameters:
$ slapos request mykvm kvm --node computer_guid=COMP-12345 --configuration \
nbd-host=debian.nbd.vifib.net nbd-port=1024
-
Request a kvm instance specifying the full URL, with default settings:
$ slapos request mykvm \
https://lab.node.vifib.com/nexedi/slapos/raw/1.0.56/software/kvm/software.cfg
- Request a kvm instance specifying an alias from SlapOS Master, with default settings
$ slapos request mykvm product.kvm
In these examples, wordpress and kvm are aliases for the full URL, and are defined in slapos-client.cfg.
supply
usage: slapos supply [-h] [--cfg CFG] software_url node
supply a Software to a node
positional arguments:
software_url Your software url
node Target node
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-client.cfg)
Ask installation of a software on a specific node or group of nodes. Nodes will then be ready to accept instances of specified software.
Examples
-
Ask installation of kvm Software Release on COMP-12345:
$ slapos supply kvm COMP-12345
-
Ask installation of kvm Software Release on COMP-12345, using alias from SlapOS Master:
$ slapos supply product.kvm COMP-12345
In this example, kvm is an alias for the full URL, and is defined in slapos-client.cfg.
remove
usage: slapos remove [-h] [--cfg CFG] software_url node
remove a Software from a node
positional arguments:
software_url Your software url
node Target node
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-client.cfg)
Ask removal of a software from a specific node or group of nodes. Existing instances won’t work anymore.
Examples
In this example, kvm is an alias for the full URL, and is defined in slapos-client.cfg.
console
usage: slapos console [-h] [--cfg CFG] [-u MASTER_URL] [-k KEY_FILE]
[-c CERT_FILE] [-i | -b | -p]
open python console with slap library imported
You can play with the global "slap" object and
with the global "request" method.
examples :
>>> # Request instance
>>> request(kvm, "myuniquekvm")
>>> # Request software installation on owned computer
>>> supply(kvm, "mycomputer")
>>> # Fetch instance informations on already launched instance
>>> request(kvm, "myuniquekvm").getConnectionParameter("url")
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-
client.cfg)
-u MASTER_URL, --master_url MASTER_URL
Url of SlapOS Master to use
-k KEY_FILE, --key_file KEY_FILE
SSL Authorisation key file
-c CERT_FILE, --cert_file CERT_FILE
SSL Authorisation certificate file
-i, --ipython Use IPython shell if available (default)
-b, --bpython Use BPython shell if available
-p, --python Use plain Python shell
SlapOS Node commands
This group of commands is used to control the current SlapOS Node. They are only useful to Node administrators.
node, node status
These are both aliases for node supervisorctl status. It displays the status of the node, also running the supervisor daemon if needed.
usage: slapos node supervisorctl [-h] [--cfg CFG] ...
open supervisor console, for process management
positional arguments:
supervisor_args parameters passed to supervisorctl
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION
or /etc/opt/slapos/slapos.cfg)
node register
usage: slapos node register [-h] [--interface-name INTERFACE_NAME]
[--master-url MASTER_URL]
[--master-url-web MASTER_URL_WEB]
[--partition-number PARTITION_NUMBER]
[--ipv4-local-network IPV4_LOCAL_NETWORK]
[--ipv6-interface IPV6_INTERFACE] [--login-auth]
[--login LOGIN] [--password PASSWORD]
[--token TOKEN] [--create-tap] [--dry-run]
node_name
register a node in the SlapOS cloud
positional arguments:
node_name Name of the node
optional arguments:
-h, --help show this help message and exit
--interface-name INTERFACE_NAME
Primary network interface. IP of Partitions will be
added to it (default: eth0)
--master-url MASTER_URL
URL of SlapOS Master REST API (default:
https://slap.vifib.com)
--master-url-web MASTER_URL_WEB
URL of SlapOS Master webservice to register
certificates (default: https://www.slapos.org)
--partition-number PARTITION_NUMBER
Number of partitions to create in the SlapOS Node
(default: 10)
--ipv4-local-network IPV4_LOCAL_NETWORK
Subnetwork used to assign local IPv4 addresses. It
should be a not used network in order to avoid
conflicts (default: 10.0.0.0/16)
--ipv6-interface IPV6_INTERFACE
Interface name to get ipv6
--login-auth Force login and password authentication
--login LOGIN Your SlapOS Master login. Asks it interactively, then
password.
--password PASSWORD Your SlapOS Master password. If not provided, asks it
interactively. NOTE: giving password as parameter
should be avoided for security reasons.
--token TOKEN SlapOS 'computer security' authentication token
--create-tap, -t Will trigger creation of one virtual "tap" interface
per Partition and attach it to primary interface.
Requires primary interface to be a bridge. Needed to
host virtual machines (default: False)
--dry-run, -n Simulate the execution steps (default: False)
This will register the current node, and generate the SlapOS configuration file.
The command requires an authentication token, either provided as an argument, or given at the interactive prompt. Go to the SlapOS Master web page, click Servers, then token. A token is valid for a single node register command and will expire after one day.
If the Node is already registered (slapos.cfg and certificate are already present), the command issues a warning, backups the original configuration and creates a new one.
Notes:
- “IPv6 interface” and “create tap” won’t be put at all in the SlapOS Node configuration file if not explicitly written.
Examples
-
Register computer named “mycomputer” to SlapOS Master:
$ slapos node register mycomputer
-
Register computer named “mycomputer” to SlapOS Master using br0 as primary interface, tap0 as IPv6 interface and different local ipv4 subnet:
$ slapos node register mycomputer --interface-name br0 --ipv6-interface tap0 \
--ipv4-local-network 11.0.0.0/16
-
Register computer named “mycomputer” to another SlapOS master accessible via https://www.myownslaposmaster.com, and SLAP webservice accessible via https://slap.myownslaposmaster.com (note that this address should be the “slap” webservice URL, not web URL):
$ slapos node register mycomputer --master-url https://slap.myownslaposmaster.com \
--master-url-web https://www.myownslaposmaster.com
-
Register computer named “mycomputer” to SlapOS Master, and ask to create tap interface to be able to host KVMs:
$ slapos node register mycomputer --create-tap
node software
usage: slapos node software [-h] [--cfg CFG] [--instance-root INSTANCE_ROOT]
[--software-root SOFTWARE_ROOT]
[--master-url MASTER_URL]
[--computer-id COMPUTER_ID]
[--supervisord-socket SUPERVISORD_SOCKET]
[--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH]
[--buildout BUILDOUT] [--pidfile PIDFILE]
[--key_file KEY_FILE] [--cert_file CERT_FILE]
[--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE]
[--master_ca_file MASTER_CA_FILE]
[--certificate_repository_path CERTIFICATE_REPOSITORY_PATH]
[--maximum-periodicity MAXIMUM_PERIODICITY]
[--promise-timeout PROMISE_TIMEOUT] [--now]
[--maximal_delay MAXIMAL_DELAY]
[--all | --only-sr ONLY_SR]
run software installation/deletion
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CONFIGURATION or /etc/opt/slapos/slapos.cfg)
--instance-root INSTANCE_ROOT
The instance root directory location.
--software-root SOFTWARE_ROOT
The software_root directory location.
--master-url MASTER_URL
The master server URL. Mandatory.
--computer-id COMPUTER_ID
The computer id defined in the server.
--supervisord-socket SUPERVISORD_SOCKET
The socket supervisor will use.
--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH
The location where supervisord configuration will be
stored.
--buildout BUILDOUT Location of buildout binary.
--pidfile PIDFILE The location where pidfile will be created. Can be
provided by configuration file, or defaults to
/opt/slapos/slapgrid-sr.pid
--key_file KEY_FILE SSL Authorisation key file.
--cert_file CERT_FILE
SSL Authorisation certificate file.
--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE
Signature private key file.
--master_ca_file MASTER_CA_FILE
Root certificate of SlapOS master key.
--certificate_repository_path CERTIFICATE_REPOSITORY_PATH
Path to directory where downloaded certificates would
be stored.
--maximum-periodicity MAXIMUM_PERIODICITY
Periodicity at which buildout should be run in
instance.
--promise-timeout PROMISE_TIMEOUT
Promise timeout in seconds (default: 3)
--now Launch slapgrid without delay. Default behavior.
--maximal_delay MAXIMAL_DELAY
Deprecated. Will only work from configuration file in
the future.
--all Process all Software Releases, even if already
installed.
--only-sr ONLY_SR, --only ONLY_SR
Force the update of a single software release (can be
full URL or MD5 hash), even if is already installed.
This option will make all other sofware releases be
ignored.
Return values:
(among other standard Python return values)
- 0 Everything went fine.
- 1 At least one software was not correctly installed.
node instance
usage: slapos node instance [-h] [--cfg CFG] [--instance-root INSTANCE_ROOT]
[--software-root SOFTWARE_ROOT]
[--master-url MASTER_URL]
[--computer-id COMPUTER_ID]
[--supervisord-socket SUPERVISORD_SOCKET]
[--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH]
[--buildout BUILDOUT] [--pidfile PIDFILE]
[--key_file KEY_FILE] [--cert_file CERT_FILE]
[--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE]
[--master_ca_file MASTER_CA_FILE]
[--certificate_repository_path CERTIFICATE_REPOSITORY_PATH]
[--maximum-periodicity MAXIMUM_PERIODICITY]
[--promise-timeout PROMISE_TIMEOUT] [--now]
[--maximal_delay MAXIMAL_DELAY]
[--all | --only-cp ONLY_CP]
run instance deployment
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CONFIGURATION or /etc/opt/slapos/slapos.cfg)
--instance-root INSTANCE_ROOT
The instance root directory location.
--software-root SOFTWARE_ROOT
The software_root directory location.
--master-url MASTER_URL
The master server URL. Mandatory.
--computer-id COMPUTER_ID
The computer id defined in the server.
--supervisord-socket SUPERVISORD_SOCKET
The socket supervisor will use.
--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH
The location where supervisord configuration will be
stored.
--buildout BUILDOUT Location of buildout binary.
--pidfile PIDFILE The location where pidfile will be created. Can be
provided by configuration file, or defaults to
/opt/slapos/slapgrid-cp.pid
--key_file KEY_FILE SSL Authorisation key file.
--cert_file CERT_FILE
SSL Authorisation certificate file.
--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE
Signature private key file.
--master_ca_file MASTER_CA_FILE
Root certificate of SlapOS master key.
--certificate_repository_path CERTIFICATE_REPOSITORY_PATH
Path to directory where downloaded certificates would
be stored.
--maximum-periodicity MAXIMUM_PERIODICITY
Periodicity at which buildout should be run in
instance.
--promise-timeout PROMISE_TIMEOUT
Promise timeout in seconds (default: 3)
--now Launch slapgrid without delay. Default behavior.
--maximal_delay MAXIMAL_DELAY
Deprecated. Will only work from configuration file in
the future.
--all Process all Computer Partitions.
--only-cp ONLY_CP, --only ONLY_CP
Update a single or a list of computer partitions
(ie.:slappartX, slappartY), this option will make all
other computer partitions be ignored.
Return values:
(among other standard Python return values)
- 0 Everything went fine.
- 1 At least one instance was not correctly processed.
- 2 At least one promise has failed.
node collect
usage: slapos node collect [-h] [--cfg CFG]
Collect system consumption and data and store.
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION or
/etc/opt/slapos/slapos.cfg)
Return values:
(among other standard Python return values)
- 0 Everything went fine.
- 1 Fail to collect computer information
node report
usage: slapos node report [-h] [--cfg CFG] [--instance-root INSTANCE_ROOT]
[--software-root SOFTWARE_ROOT]
[--master-url MASTER_URL]
[--computer-id COMPUTER_ID]
[--supervisord-socket SUPERVISORD_SOCKET]
[--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH]
[--buildout BUILDOUT] [--pidfile PIDFILE]
[--key_file KEY_FILE] [--cert_file CERT_FILE]
[--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE]
[--master_ca_file MASTER_CA_FILE]
[--certificate_repository_path CERTIFICATE_REPOSITORY_PATH]
[--maximum-periodicity MAXIMUM_PERIODICITY]
[--promise-timeout PROMISE_TIMEOUT] [--now]
[--maximal_delay MAXIMAL_DELAY]
run instance reports and garbage collection
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CONFIGURATION or /etc/opt/slapos/slapos.cfg)
--instance-root INSTANCE_ROOT
The instance root directory location.
--software-root SOFTWARE_ROOT
The software_root directory location.
--master-url MASTER_URL
The master server URL. Mandatory.
--computer-id COMPUTER_ID
The computer id defined in the server.
--supervisord-socket SUPERVISORD_SOCKET
The socket supervisor will use.
--supervisord-configuration-path SUPERVISORD_CONFIGURATION_PATH
The location where supervisord configuration will be
stored.
--buildout BUILDOUT Location of buildout binary.
--pidfile PIDFILE The location where pidfile will be created. Can be
provided by configuration file, or defaults to
/opt/slapos/slapgrid-ur.pid
--key_file KEY_FILE SSL Authorisation key file.
--cert_file CERT_FILE
SSL Authorisation certificate file.
--signature_private_key_file SIGNATURE_PRIVATE_KEY_FILE
Signature private key file.
--master_ca_file MASTER_CA_FILE
Root certificate of SlapOS master key.
--certificate_repository_path CERTIFICATE_REPOSITORY_PATH
Path to directory where downloaded certificates would
be stored.
--maximum-periodicity MAXIMUM_PERIODICITY
Periodicity at which buildout should be run in
instance.
--promise-timeout PROMISE_TIMEOUT
Promise timeout in seconds (default: 3)
--now Launch slapgrid without delay. Default behavior.
--maximal_delay MAXIMAL_DELAY
Deprecated. Will only work from configuration file in
the future.
Return values:
(among other standard Python return values)
- 0 Everything went fine.
- 1 At least one instance hasn’t correctly been processed.
node start|stop|restart|tail|status
usage: slapos node <start|stop|restart|tail|status> [-h] [--cfg CFG] <instance>:[process]
Start/Stop/Restart/Show stdout/stderr of instance and/or process.
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION
or /etc/opt/slapos/slapos.cfg)
Examples
-
Start all processes of slappart3:
$ slapos node start slappart3:
-
Stop only apache in slappart1:
$ slapos node stop slappart1:apache
-
Show stdout/stderr of mysqld in slappart2:
$ slapos node tail slappart2:mysqld
node supervisorctl
usage: slapos node supervisorctl [-h] [--cfg CFG] ...
open supervisor console, for process management
positional arguments:
supervisor_args parameters passed to supervisorctl
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION
or /etc/opt/slapos/slapos.cfg)
node supervisord
usage: slapos node supervisord [-h] [--cfg CFG]
launch, if not already running, supervisor daemon
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION or
/etc/opt/slapos/slapos.cfg)
SlapOS Miscellaneous commands
configure client
usage: slapos configure client [-h] [--cfg CFG] [--master-url MASTER_URL]
[--master-url-web MASTER_URL_WEB]
[--token TOKEN]
configure slapos client with an existing account
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default:
$SLAPOS_CLIENT_CONFIGURATION or ~/.slapos/slapos-
client.cfg)
--master-url MASTER_URL
URL of SlapOS Master REST API (default:
https://slap.vifib.com)
--master-url-web MASTER_URL_WEB
URL of SlapOS Master webservice to register
certificates (default: https://www.slapos.org)
--token TOKEN SlapOS 'credential security' authentication token (use
'--token ask' for interactive prompt)
This creates a client configuration file, and downloads a certificate + key pair from the SlapOS Master. They will be used for all the “slapos client” commands.
The command requires an authentication token, either provided as an argument, or given at the interactive prompt.
Go to the SlapOS Master web page, click Servers, then token. A token is valid for a single configure client command and will expire after one day.
cache lookup
usage: slapos cache lookup [-h] [--cfg CFG] software_url
perform a query to the networkcache
You can provide either a complete URL to the software release,
or a corresponding MD5 hash value.
The command will report which OS distribution/version have a binary
cache of the software release, and which ones are compatible
with the OS you are currently running.
positional arguments:
software_url Your software url or MD5 hash
optional arguments:
-h, --help show this help message and exit
--cfg CFG SlapOS configuration file (default: $SLAPOS_CONFIGURATION or
/etc/opt/slapos/slapos.cfg)
Examples
-
See if the wordpress Software Release is available in precompiled format for our distribution:
$ slapos cache lookup http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
Software URL: http://git.erp5.org/gitweb/slapos.git/blob_plain/refs/tags/slapos-0.156:/software/kvm/software.cfg
MD5: 4410088e11f370503e9d78db4cfa4ec4
-------------
Available for:
distribution | version | id | compatible?
-----------------+--------------+----------------+-------------
CentOS | 6.3 | Final | no
Fedora | 17 | Beefy Miracle | no
Ubuntu | 12.04 | precise | yes
debian | 6.0.6 | | no
debian | 7.0 | | no
You can also use the corresponding hash value in place of the URL.