Cloud 66 Toolbelt Commands

About backup management

The following commands help you manage your backups, such as listing, downloading and initiating backups on your stacks.

Note:

This only applies to managed backups and not the unmanaged ones.

List your backups

This will list all the managed backups of a stack grouped by their database type and/or backup schedule.

Usage

$ cx backups list [-s <stack>] [-l] [<db type>]

Parameters

Parameter Description
stack Name of your stack
db type (optional) The type of DB you’d like to list backups for (eg. mysql)
l (optional) Returns the latest successful backup
e (optional) Your stack environment

Example

$ cx backups list -s "My Awesome App" -e production

Download your backups

Allows you to download a managed database backup through the command line, concatenating separate files into one automatically if it consists of numerous files.

Usage

$ cx backups download [-s <stack>] [-d <download directory>] <backup id>

Parameters

Parameter Default Description
stack Name of your stack
dbtypes (optional) all Comma separated list of Database types which need backup tasks
frequency (optional) 0 */1 * * * Frequency of backup task in cron schedule format
keep (optional) 100 Number of previous backups to keep
gzip (optional) true Compress your backups with gzip
exclude-tables (optional) Tables that must be excluded from the backup
run-on-replica (optional) true Run backup task on replica server if available

Example

$ cx backups new -s mystack --dbtypes=postgresql --frequency="0 */1 * * *" --keep 50 --gzip=true exclude-tables=my_log_table --run-on-replica=false

Database management

Use these commands to configure your replication slave database servers.

Slave promotion to standalone master

Usage

$ cx databases resync-slave [-s <stack>] <slave server name>

Re-syncs the specified slave database server with its master database server.

From time-to-time your slave database may go out of sync with its master. This action attempts to re-sync your specified slave server. This can happen depending on many factors (such as DB size, frequency of change, networking between servers etc).

The server provided must have already been configured as a replication slave via the Cloud 66 UI. Providing the database type is optional and is only necessary for shared servers where we can’t automatically determine the target database type.

Important!

This action could result in application downtime, it is advisable to choose a non-busy time to perform this action, and to place your stack in maintenance mode.

The existing master and other slaves will need to be removed after this process as after this the new configuration will have only a single database. You will be able to configure replication from this again after that point.

In the case of any servers not being accessible during this time, those servers will remain unchanged. It is therefore important to stop/shutdown those servers in this case (or to manually stop the DB service on those servers) as having multiple masters in a cluster could cause problems throughout the cluster.

Parameters

Parameter Default Description
stack Name of your stack
stack server name Name of the replication slave server to re-synchronise with master
database type (optional) The Database type

Example

$ cx databases resync-slave -s My_Awesome_App my_slave_server_name
$ cx databases resync-slave -s My_Awesome_App --dbtype postgresql my_slave_server_name

Download

Use this command to download a file from the remote server to your local computer.

Usage

$ cx download [-s <stack>] [--server <server name>] [source file] [target directory]

If you don’t specify a target directory, the file will be downloaded to your current local directory.

Parameters

Parameter Default Description
stack Name of the stack
server name Name of the server to access
source file The path to the file on your server
target directory (optional) Your local target path

Example

$ cx download -s "My Awesome App" --server web /tmp/file.txt /tmp/file.txt

Gateway management

These commands allow you to manage your gateways.

List gateways

This command lists all gateways on your account.

Usage

$ cx --org <organization_name> gateways list [ --verbose]

Parameters

Parameter Default Description
name The name of the gateway
address Public address of the gateway. It could be the IP or DNS address
username The username which should be used to connect to gateway
private-ip The private ip of the gateway.

Example

$ cx --org My_Awesome_org gateways add --name aws_bastion --address 1.1.1.1  --username ec2-user  --private-ip 2.2.2.2

Open gateway

Make the gateway available to use with cloud66 for ttl amount of time.

Usage

$ cx --org <organization_name> gateways open --name <gateway name> --key <The path to the gateway server key> --ttl <time to live >

Parameters

Parameter Default Description
name Name of the gateway

Example

$ cx --org My_Awesome_org gateways close --name aws_bastion

Remove gateway

This command will remove the gateway from your account

Usage

$ cx --org <organization_name> gateways remove --name <gateway name>

Parameters

Parameter Default Description
name Name of the gateway

Example

$ cx --org My_Awesome_org gateways remove --name aws_bastion

Job management

These commands allow you to list jobs and run a job immediately.

List jobs

This command lists all jobs on a stack or a server.

Usage

$ cx jobs list [-s <stack>] --server <server name>|<server ip>|<server role> --service <service name>

Parameters

Parameter Default Description
stack Name of the stack
server name Name of the job to run
arg (optional) Parameters you would like to pass job ( more info )

Examples

$ cx job run -s "My Awesome App" my_job
$ cx job run -s "My Awesome App" --arg "arg1" --arg "arg2" my_job

Temporary lease

Opens a port on your server firewall to temporarily allow access from a specified IP address.

Usage

$ cx lease [-s <stack>] [-f <from IP>] [-t <time to open>] [-p <port>]

Parameters

Parameter Default Description
stack Name of the stack
f (optional) User IP address The source IP to allow connections from
t (optional) 20 minutes Time to open for (max 240 minutes)
p (optional) 22 Port to open
e (optional) Your stack environment

Example

$ cx lease -s "My Awesome App" -f 123.123.123.123 -t 30 -e production

For more fine grained access control, use the Stack network settings page.

Cloud 66 Easy Login

Cloud 66 Toolbelt uses OAuth 2 for authentication and authorization. Once you have authorized Toolbelt with your Cloud 66 account you can create, delete, scale and deploy your stacks right from the terminal window. All these actions are accessible from the Cloud 66 web UI as well. As a matter of fact, Cloud 66 Toolbelt is more powerful than its web UI.

Cloud 66 Easy Login allows you to login to Cloud 66 web UI from your terminal without entering your password or 2fa. Once you have Cloud 66 Toolbelt authorized on your computer, simple use the login command to open up a browser and login to your account. $ cx login

Access Control for Toolbelt Login

Account owners can control who on their teams can use the Toolbelt to login to their account. This is done through the permissions configurable on the Teams page for each user in the team.

Open your website

Usage

$ cx open [-s <stack>] [<server name>|<server ip>|<server role>]

Parameters

Parameter Description
stack Name of your stack
server name (optional) Name of the server to access
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)

Example

$ cx open -s "My Awesome App"

Redeploy your stack

This is an alias for the stacks redeploy command, which triggers the deployment of a stack from the command line, just like clicking on redeploy in the UI.

Usage

$ cx redeploy [-s <stack>] [-y] [--git-ref <git_ref>] [--service <service>] [--service <service>] [--service <service>]

Parameters

Parameter Description
stack Name of your stack
e (optional) Your stack environment
y (optional) Automatically answer yes to any prompts
git-ref (optional, non-Docker) Redeploy the specific git reference (branch, tag or hash). Non-Docker stacks only.
service (optional, repeatable, Docker only) Will deploy the specified services from your stack only. Each service can have an optional colon-separated reference which is image tag or git reference for image based services, or for git based services.
listen (optional) Will follow the deployment and log progress output

Examples

$ cx redeploy -s "My Awesome App" -e production
$ cx redeploy -s "My Awesome App" -e production -y --git-ref my_git_ref_value
$ cx redeploy -s "My Awesome Docker App" --service web:8c7f3d393162f88b8b9493f6babec574b03ca957 --service api:latest

Deploying a stack that is already being deployed will enqueue your redeploy command and will run it immediately after the current deployment is finished.

Run command

This command will execute a command directly on the remote server. It does this by first opening the firewall for SSH from your IP address temporarily (20 minutes), downloads your SSH key if you don’t have it, starts a SSH session, executes the command specified and returns its output.

Usage

$ cx run -s <stack> --server <server name>|<server ip>|<server role> --service '<command>'

Parameters

At least one of the optional server parameters are necessary in order to identify which server to run the command on.

Parameter Default Description
stack Name of the stack
server Specify a server
server name (optional) Name of the server to access
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)
service (optional) The service in which to run the command (Docker stacks only)

Examples

$ cx run -s "My Awesome App" --server web1 'pwd'

The service parameter applies to Docker stacks and allows you to enter a Docker container with your command (based on the latest image of that service). Some examples are:

$ cx run -s My_Awesome_App --server web1 --service my_api_service '/bin/bash'
$ cx run -s My_Awesome_App --server web1 --service my_api_service 'bundle exec rails c'

Server management

These commands allow you to list and set various settings on your servers.

List server settings

This command lists the possible settings for a specific server.

Usage

$ cx servers settings list [-s <stack>] --server <server name>|<server ip>|<server role>

Parameters

Parameter Default Description
stack Name of the stack
server name (optional) Name of the server to access
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)
setting The setting you would like to change
value The value for the setting

Examples

$ cx servers settings set -s "My Awesome App" --server lion

Reboot servers

Use this command to reboot a specific server from the command line

Usage

$ cx servers reboot [-s <stack>] [-e stack environment] --server <server name> 

Parameters

Parameter Default Description
stack Name of the stack
server name (optional) Name of the server to reboot
e (optional) Your stack environment

Example

$ cx server reboot -s mystack --server lion -e production

Listing services

Usage

$ cx services list [-s <stack>] [--server <slave server name>|<slave server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Parameter Default Description
stack Name of the stack
service name Name of the target service
server name (optional) Name of the target server
group (optional) Name of the target server group (ie. web/db/docker etc)
count Desired count (ie. +2, -3 or 5)

Example

$ cx services scale -s mystack my_web_service 1
$ cx services scale -s mystack a_backend_service --server backend +5
$ cx services scale -s mystack a_backend_service -2
$ cx services scale -s mystack a_backend_service --group docker 3

Stopping services

Usage

$ cx services stop [-s <stack>] <service name> [--server <server name>|<server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Parameter Default Description
stack Name of the stack
service name Name of the target service
server name (optional) Name of the target server

Example

$ cx services restart -s mystack my_web_service
$ cx services restart -s mystack a_backend_service
$ cx services restart -s mystack --server my_server my_web_service

Getting service information

Usage

$ cx services info [-s <stack>] <service name> [--server <server name>|<server ip>]

Gets information about the given service such as service name, source type, git-ref, image info, container count and docker commands. Optionally provide the server to act only on that server.

Parameters

Parameter Default Description
stack Name of the stack
service name Name of the target service
server name (optional) Name of the target server

Example

$ cx services info -s mystack my_web_service
$ cx services info -s mystack a_backend_service
$ cx services info -s mystack --server my_server my_web_service

Result

NAME             VALUE
name             web
source type      git
git-ref          d33e491e5a33
container count  1
image name       web
image uid        92fd690d33fe43f55c80dc6687a7171c
image tag        20150824122440373
command          bundle exec rails s production
build command    bundle exec rake db:schema:load
deploy command

List your stack settings

Usage

$ cx settings list [-s <stack>] [-e <environment>]

Parameters

Parameter Description
stack Name of the stack
setting_name A valid setting from the list above
value The value for the setting
e (optional) Your stack environment

Example

$ cx settings set -s "My Awesome App" git.repository git://github.com/cloud66-samples/rails-mysql.git -e production

$ cx settings set -s my_stack deploy.parallel true

Settings Variables

These are the available settings:

Setting Default Description
allowed.web.source nil i.e. 0.0.0.0 IP addresses that are allowed to access a stacks web servers (with IP addresses in the command or a CSV file with IP addresses as input)
asset.prefix nil If you change your default Rails assets folder, you can set it here
continuous.deploy false Enable or disable continuous deployment on Github.
custom.build.command - Set custom build command. Only applies to Sinatra or Padrino stacks
custom.deploy.command - Set custom deploy command. Only applies to Sinatra or Padrino stacks
db.check.backup.size true Enable/Disable Check free space before taking backup
deploy.parallel true Enable or disable parallel deployments on the stack.
git.branch - Change the Git branch of the stack repository
git.repository - Change the Git repository URL
logrotate.app.frequency daily For application specific log files accpetd value: hourly, daily, weekly and monthly
logrotate.app.keep.count 14 The number of log files to keep for each logfile
logrotate.server.frequency daily For server specific log files accpetd value: hourly, daily, weekly and monthly
logrotate.server.keep.count 14 The number of log files to keep for each logfile
maintenance.mode false Enable or disable maintenance mode on the stack.
reconfigure.nginx true If set to true, it will regenerate Nginx configuration and restart it (only on the next deployment)
run.deploy.command true Enable or disable option run deploy command on every deployment (database migrations for Rails stacks).
stack.name   View your stack name
  1. To enable, you can use the values 1, true, on or enable, and to disable you can use the values 0, false, off or disable

SSHing to your server

Allows direct SSH shell into your servers by opening the firewall temporarily for the source IP address, downloading the SSH key and starting a SSH session with one command.

Your server SSH key is downloaded to ~/.ssh and re-used in subsequent SSH connections via the toolbelt. You need to have shell to server rights over the stack to use this command.

If your server deployed behind a bastion server, you need to provide the private key needed to connecting to bastion server to be able to connect to your server.

Usage

$ cx ssh  [--gateway-key <The path to the key of gateway server>]    [-s <stack>] <server name>|<server ip>|<server role>

Parameters

Parameter Default Description
stack name Name of the stack to access
gateway-key (optional) The path to the key of gateway server
server name (optional) Name of the server to access
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)
e (optional) Your stack environment

Example

$ cx ssh -s "My Awesome App" Lion -e production
$ cx ssh --gateway-key ~/.ssh/bastion_key  -s "My Awesome App" Lion -e production

List your stacks

Lists all the stacks available to your account.

Usage

$ cx stacks list [-e <environment>]

Parameters

Parameter Description
stack Name of your stack
y (optional) Answer yes to confirmations
group (default web) Group of servers you wish to reboot (all, web, haproxy, db, mysql, redis, postgresql, mongodb)
strategy Reboot in serial or parallel
e (environment) (optional) Full or partial environment name

The group parameter specifies which group of servers you wish to reboot. Valid values are “all”, “web”, “haproxy”, “db”; DB specific values like “mysql” or “redis” for example are also supported. If this value is left unspecified, the default value of “web” will be used

The strategy parameter specifies whether you want all your servers to be rebooted in parallel or in serial. Valid values for this parameter are “serial” or “parallel”; “serial” reboots involves web servers being removed/re-added to the LB one by one. Note that for this only applies to web servers; non-web server will still be rebooted in parallel. If this value is left unspecified, Cloud 66 will determine the best strategy based on your infrastructure layout.

Example

$ cx stack reboot -s mystack
$ cx stack reboot -s mystack --group web
$ cx stack reboot -s mystack --group all
$ cx stack reboot -s mystack --strategy parallel
$ cx stack reboot -s mystack --group web --strategy serial

Clear caches

For improved performance, volatile code caches exist for your stack. It is possible for a those volatile caches to become invalid if you switch branches, change git repository URL, or rebase or force a commit. Since switching branch or changing git repository URL is done via the Cloud 66 interface, your volatile caches will automatically be purged. However, rebasing or forcing a commit doesn’t have any association with Cloud 66, so this command can be used to purge the exising volatile caches.

Usage

$ cx stacks clear-caches [-s <stack>]

Parameters

Parameter Description
  :
stack Name of your stack

Example

$ cx stacks listen -s "My Awesome App" -e production

You can leave the command by pressing Ctrl-C at any time.


Manage your configuration files

List, download and upload of configuration files such as a service.yml or manifest.yml.

Usage

$ cx stacks configure list [-s <stack>]

Parameters

Parameter Description
list List of all versions of a configuration file
download Download a configuration file
uplaod Upload a new version of configuration file
stack (optional) Name of your stack, this can be omitted if the current directory is a stack directory
f (file) (optional) File name, accepted values are service.yml and manifest.yml
e (environment) (optional) Full or partial environment name

Show help pages for a command

Shows a list of commands or help for one command.

Usage

$ cx stacks help [<command>]

Parameters

Parameter Description
command The command you wish to see help pages for

Usage

$ cx tail [-s <stack>] <server name>|<server ip>|<server role> <log filename>

Parameters

At least one of the optional parameters are necessary in order to identify which server to run the command on.

Parameter Default Description
stack Name of the stack
server name (optional) Name of the server to access
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)
log filename The logfile to tail (eg. nginx_error.log)

Example

$ cx tail -s "My Awesome App" web nginx_error.log

Environment variable setup

These commands allow you to list and set environment variables on your stack.

List environment variables

Usage

$ cx env-vars list [-s <stack>] [--history] [environment_variables] 

Parameters

Parameter Default Description
stack Name of the stack
setting Name of environment variable
value Value for environment variable

Example

$ cx env-vars set My_Awesome_App FIRST_VAR=123

Listing processs

Usage

$ cx processes list [-s <stack>] [--server <server name>]

List all the processes running on a stack or a server. Optionally provide the server to list only the processes running on that server.

Parameters

Parameter Default Description
stack Name of the stack
process name Name of the target process
server name (optional) Name of the target server
count Desired relative count or absolute count (i.e. [+2],[-3] or 5)

Example

$ cx processes scale -s mystack --server backend1 --name worker [+5]
$ cx processes scale -s mystack --server backend2 --name worker [-5]
$ cx processes scale -s mystack --server backend3 --name worker 15
$ cx processes scale -s mystack --name worker 2

Tunnel command

This command opens an SSH tunnel from your local machine to a remote server on the given ports. It does this by first opening the firewall for SSH from your IP address temporarily (20 minutes), downloads your SSH key if you don’t have it and opens an SSH tunnel.

Usage

$ cx tunnel -s <stack> --server <server name>|<server ip>|<server role> --remote <remote port> --local <local port>

Parameters

At least one of the optional server parameters are necessary in order to identify which server to run the command on.

Also, you need to specify at least the remote port. If local is missing, remote + 1 will be used as local. For example, --remote 3306 without local will use 3307 as local.

Parameter Default Description
stack Name of the stack
server Specify a server
server name (optional) Name of the target server
server ip (optional) IP of the server to access
server role (optional) Role of the server to access (eg. web)
remote Remote port for the tunnel
local (optional) Local port for the tunnel. If not specified, remote + 1 is used.

Examples

$ cx tunnel -s "My Awesome App" --server mysql --remote 3306 --local 13306

Upload

Use this command to copy a file from your local computer to the remote server.

Usage

$ cx upload [-s <stack>] [--server <server name>] [source file] [target directory]

If you don’t specify a target directory, the file will be uploaded to /tmp on your remote server.

Parameters

Parameter Default Description
stack Name of the stack
server name (optional) Name of the server to access
source file The path to the file on your local computer
target directory (optional) Your remote server target path

Example

$ cx upload -s "My Awesome App" --server web /tmp/file.txt /tmp/file.txt

List command

This command shows a list of all users you have access to. This is a list of all users within the organization you specify and have enough access rights to manage users for.

Usage

$ cx --org <organization_name> users list

Parameters

Parameter Default Description
organization_name Name of the organization -you can find it by using cx info-
json_file_path File path to the saved json’s file

Examples

$ cx --org My_Awesome_org users show jim@gmail.com
$ cx --org My_Awesome_org users show jim@gmail.com --json /tmp/jim_profile.json

You can change the json file to suite any changes you require (or use it as it is) and apply it to other users in your account using the apply-profile command.

Note

You can download the same Access Profile from the web dashboard, under each user’s access rights page under the Teams left hand menu (click on the Accounts on top right to get there).

Apply Profile command

Apply Profile allows you to apply a user’s Access Profile to another one. To use this command you need to have an Access Profile as a json file. This can be generated using the users show command with the json option. Once you have the file you can modify it to make any changes you require in the Access Profile.

Usage

$ cx --org <organization_name> users apply-profile <username> --json <json_file_path> [--override]

Parameters

Parameter Default Description
organization_name Name of the organization -you can find it by using cx info-
json_file_path File path to the saved json’s file
override Will override the access rights instead of append

Examples

$ cx --org My_Awesome_org users apply-profile jack@gmail.com --json /tmp/jim_profile.json
$ cx --org My_Awesome_org users apply-profile jack@gmail.com --json /tmp/jim_profile.json --override

These will apply Jim’s profile to Jack’s; first one will append the access rights and the second one will overwrite them.

A note on overwriting Access Profiles

Any missing attribute for the json Access Profile will be left unchanged even if the override is used. Also, overrirde doesn’t have any effects on the contents of the account_profile section.