Table of Contents
Manage cloud and container virtualization. Multiple technologies (multiple virtualization backends) are supported (e.g. Linux LXC and AWS) providing various levels of virtualization. Throughout this documentation (and in fact in the command line options) s9s uses the word “container” to identify virtualized servers. The actual virtualization backend might use the term “virtual machine” or “Linux container” but s9s provides a high-level generic interface to interact with them, so the generic “container” term is used. So please note, the term “container” does not necessarily mean “Linux container”, it means “a server that is running in some kind of virtualized environment”.
In order to utilize the s9s command-line tool and the CMON Controller to manage virtualization, a virtualization host (container server) has to be installed first. The installation of such a container environment is documented in the s9s server.
Usage
s9s container {command} {options}Command
| Name, shorthand | Description |
|---|---|
−−create |
Creates and starts a new container or virtual machine. If this option is provided, the controller will create a new job that creates a container. By default the container will also be started, an account will be created, passwordless sudo granted and the controller will wait for the controller to obtain an IP address. |
−−delete |
Stop and delete the container or virtual machine. |
−−list, -L |
Lists the containers. See Container List. |
−−start |
Starts an existing container. |
−−stat |
Prints the details of a container. |
−−stop |
Stops the container. This will not remove the container by default, but it will stop it. If the container is set to be deleted on stop (temporary) it will be deleted. |
Options
| Name, shorthand | Description |
|---|---|
−−log |
Waits until the job is executed. While waiting the job logs will be shown unless the silent mode is set. |
−−recurrence=CRONTABSTRING |
This option can be used to create recurring jobs, jobs that are repeated over and over again until they are manually deleted. Every time the job is repeated a new job will be instantiated by copying the original recurring job and starting the copy. The options argument is a crontab style string defining the recurrence of the job. See Crontab. |
−−schedule=DATETIME |
The job will not be executed now but it is scheduled to execute later. The DateTime string is sent to the backend, so all the formats are supported by the controller. |
−−timeout=SECONDS |
Sets the timeout for the created job. If the execution of the job is not done before the timeout counted from the start time of the job expires the job will fail. Some jobs might not support the timeout feature, the controller might ignore this value. |
−−wait |
Waits until the job is executed. While waiting a progress bar will be shown unless the silent mode is set. |
−−cloud=PROVIDER |
This option can be used when a new container(s) created. The name of the cloud provider where the new container will be created. This command-line option can also be used to filter the list of the containers when used together with one of the --list or --stat options. |
--container-format=FORMATSTRING |
The string controls the format of the printed information about the containers. See Container Format. |
−−containers=LIST |
A list of containers to be created or managed. The containers can be passed as command-line options (suitable for simple commands) or as an optional argument for this command-line option. The s9s container --stop node01 and the s9s container --stop --containers=node01 commands for example are equivalent. See Create Container List. |
−−credential-id=ID |
The cloud credential ID that should be used when creating a new container. This is an optional value, if not provided the controller will find the credential to be used by the cloud name and the chosen region. |
−−firewalls=LIST |
List of firewall (AKA security groups) IDs separated by , or ; to be used for newly created containers. This is not a mandatory option, if the virtualization server needs a firewall to be set one such a firewall will be automatically created. Containers created in the same job (for example in a create cluster operation) the containers will share the same firewall, so they will be able to communicate.If the container is created so that it will be added to an existing cluster (e.g. in an add node job) the controller will try to find the firewall of the existing nodes and if it exists will re-use the same ID, so that the nodes can reach each other. |
−−generate-key |
Create a new SSH keypair when creating new containers. If this command line option was provided a new SSH keypair will be created and registered for a new user account to provide SSH access to the new container(s). If the command creates more than one containers the same one keypair will be registered for all.This command line option is actually useful for the cases when a new cluster is created together with the new containers. |
−−image=NAME |
The name of the image from which the new container will be created. This option is not mandatory, when a new container is created the controller can choose an image if it is needed. To find out what images are supported by the registered container servers please issue the s9s server --list-images command. |
−−image-os-user=NAME |
The name of the initial OS user defined in the image for the first login. Use this option to create containers based on custom images. |
−−os-key-file=PATH |
The path of the SSH key to install on a new container to allow the user to log in. This command-line option can be passed when a new container is created, the argument of the option should be the path of the private key stored on the controller. Although the path of the private key file is passed only the public key will be uploaded to the new container. |
−−os-password=PASSWORD |
This command-line option can be passed when creating new containers to set the password for the user that will be created on the container. Please note that some virtualization backend might not support passwords, only keys. |
−−os-user=USERNAME |
This option may be used when creating new containers to pass the name of the user that will be created on the new container. Please note that this option is not mandatory, because the controller will create an account whose name is the same as the name of the cmon user creating the container. The public key of the cmon user will also be registered (if the user has an associated public key) so the user can actually log in. |
−−region=REGION |
The name of the region the container is created. |
−−servers=LIST |
A list of servers to work with. |
−−subnet-id=ID |
This option can be used when new containers are created to set the subnet ID for the container. To find out what subnets are supported by the registered container servers please issue the s9s server --list-subnets command. |
−−template=NAME |
The name of the container template. See Container Template. |
−−volumes=LIST |
When a new container is created this command-line option can be used to pass a list of volumes that will be created for the container. See Volume List. |
−−vpc-id=ID |
This option can be used when new containers are created to set the VPC ID for the container. To find out what VPCs are supported by the registered container servers please issue the s9s server --list-subnets --long command. |
Container Format
The string controls the format of the printed information about the containers. When this command line option is used the specified information will be printed instead of the default columns. The format string uses the % character to mark variable fields and flag characters as they are specified in the standard printf() C library functions. The % specifiers are ended by field name letters to refer to various properties of the containers.
The %+12i format string for example has the +12 flag characters in it with the standard meaning: the field will be 12 characters wide and the + or - sign will always be printed with the number. The properties of the container are encoded by letters. The in the %16D for example the letter D encodes the data directory field, so the full path of the data directory on the container will be substituted. Standard \ notation is also available, \n for example, encodes a new-line character.
The s9s-tools support the following fields:
| Field | Description |
|---|---|
| A | The IP address of the container. This is by default the public IPv4 address of the container. Containers being deleted/created might not have any IP addresses, then the - string is substituted. |
| a | The private IP address of the container if there is any or the - string. |
| C | The full path of the configuration file that stores the container settings if such a configuration file exists. |
| c | The cloud (sometimes mentioned as ‘provider’) of the container, for example, AWS or AZ as it is set in the credentials file /var/lib/cmon/cloud_credentials.json. |
| F | The name of the first firewall (security group) if the container has such a property set, the string - otherwise. |
| G | The name of the group owner of the node. |
| I | The ID of the container. |
| i | The name of the image that was used to create the container. |
| N | The name (alias) of the container. |
| O | The username of the owner of the container. |
| S | The state of the container as a string. |
| P | The CDT path of the user. |
| p | The name of the parent server, the container server that manages the container. |
| R | The name of the region in which the container is hosted. |
| r | The address range of the subnet the container belongs to in CIDR notation (e.g.10.0.0.0/24) |
| T | The type of container (e.g. cmon-cloud or lxc). |
| t | The name of the template that was used to create a container or the - string if no such template was used. |
| U | The ID of the subnet of the container. |
| V | The ID of the VPC for the container. |
| z | The class name of the container object. |
| % | The % character itself. |
Container List
Using the --list and --long command-line options a detailed list of the containers can be printed. Here is an example of such a list:
$ s9s container --list --long
S TYPE TEMPLATE OWNER GROUP NAME IP ADDRESS SERVER
- lxc - pipas testgroup bestw_controller - core1
u lxc - pipas testgroup dns1 192.168.0.2 core1
u lxc ubuntu pipas testgroup ft_containers_35698 192.168.0.228 core1
u lxc - pipas testgroup mqtt 192.168.0.5 core1
- lxc - pipas testgroup ubuntu - core1
u lxc - pipas testgroup www 192.168.0.19 core1
Total: 6 containers, 4 running.The list contains the following fields:
| Field | Description |
|---|---|
| S | The abbreviated status information. This is u for a container that is up and running and - otherwise. |
| TYPE | Shows what kind of container or virtual machine shown in this line, the type of software that provides virtualization. |
| TEMPLATE | The name of the template that is used to create the container. |
| OWNER | The owner of the server object. |
| GROUP | The group owner of the server object. |
| NAME | The name of the container. This is not necessarily the hostname, this is a unique name to identify the container on the host. |
| IP ADDRESS | The IP address of the container or the - character if the container has no IP address. |
| SERVER | The server on which the container can be found. |
Create Container List
The command-line option argument is one or more containers separated by the ; character. Each container is an URL defining the container name (an alias for the container) and zero or more properties. The string container05parent_server=core1;container06?parent_server=core2, for example, defines two containers one on one server and the other on the other server.
To see what properties are supported in the controller for the containers, one may use the following command:
$ s9s metatype --list-properties --type=CmonContainer --long
ST NAME UNIT DESCRIPTION
r- acl - The access control list.
r- alias - The name of the container.
r- architecture - The processor architecture.See Property List for details.
Container Template
Defining a template is an easy way to set a number of complex properties without actually enumerating them in the command line one by one. The actual interpretation of the template name is up to the virtualization backend that is the protocol of the container server. The lxc backend for example considers the template to be an already created container, it simply creates the new container by copying the template container so the new container inherits everything.
The template name can also be provided as a property name for the container, so the command s9s container --create --containers="node02?template=ubuntu;node03"--log for example will create two containers, one using a template, the other using the default settings.
Note that the --template the command-line option is not mandatory, if emitted suitable default values will be chosen, but if the template is provided and the template is not found the creation of the new container will fail.
Volume List
The list can contain one or more volumes separated by the ; character. Every volume consists of three properties separated by the : character, a volume name, the volume size in gigabytes, and a volume type that is either “HDD” or “SSD”. The string vol1:5:hdd;vol2:10:hdd for example defines two hard-disk volumes, one 5GByte, and one 10GByte.
For convenience, the volume name and the type can be omitted, so that automatically generated volume names are used.
Examples
Create a container with no special information needed, every setting will use the default values. For this, of course, at least one container server has to be pre-registered and properly working:
$ s9s container --create --waitUsing the default, automatically chosen container names might not be the easiest way, so here is an example that provides a container name:
$ s9s container --create --wait node01This is equivalent to the following example that provides the container name through a command-line option:
$ s9s container --create --wait --containers="node01"