Command Reference

Stackato Client

Usage

stackato [options] command [] [command_options]

Try stackato help, stackato help [command], and stackato options for more information.

Getting Started

Administrative user privileges are required where “(admin)” is noted.

target [–allow-http] <url>

Reports current target or sets a new target. http targets will not be accepted without the --allow-http parameter.

login [email] [–email, –passwd] [–token-file <token_file_path>] [–group <groupname>]

Log in to the targeted server.

If --token-file is used, the authentication token is saved in the specified token file. Subsequent stackato commands will make use of the specified authentication and token file.

--group sets the group and maintains it for following commands.

info

System and account information

Applications

apps

List deployed applications

Application Creation

push [appname]

Create, push, map, and start a new application

push [appname] –path

Push application from specified path

push [appname] –url

Set the url for the application

push [appname] –instances <N>

Set the expected number <N> of instances

push [appname] –mem <memsize>

Set the memory reservation for the application. memsize can be specified in megabytes (M) as an integer (64M, 256M, 500M) or gigabytes (G) as an integer or float (1G, 1.5G, 1.75G)

push [appname] –runtime RUNTIME

Set the runtime to use for the application

push [appname] –framework|-f FRAMEWORK

Set the framework to use for the application

push [appname] –no-start

Do not auto-start the application

push [appname] –no-prompt|-n

Do not prompt user for details; Use defaults.

push [appname] –copy-unsafe-links

Copy links to outside of the application into it, instead of rejecting them with an error

Application Operations

start <appname>

Start the application

stop <appname>

Stop the application

restart <appname>

Restart the application

delete <appname>

Delete the application

Application Updates

update <appname> [–path]

Update the application bits

update <appname> –no-prompt|-n

Do not prompt user for details; Use defaults.

mem <appname> [memsize]

Update the memory reservation for an application. memsize can be specified in megabytes (M) as an integer (64M, 256M, 500M) or gigabytes (G) as an integer or float (1G, 1.5G, 1.75G)

map <appname> <url>

Register the application to the url

unmap <appname> <url>

Unregister the application from the url

instances <appname> <num|delta>

Scale the application instances up or down

Application Information

crashes <appname>

List recent application crashes

crashlogs <appname>

Display log information for crashed applications

logs <appname> [–instance N] [–all] [–prefix]

Display log information for the application

files <appname> [path] [–all]

Display directory listing or file download for [path]

ssh [–instance <instance>] <appname> [command]

Allows ssh access to an app in an interactive shell:

$ stackato ssh myapp

If a command is added, it is run and the connection exited:

$ stackato ssh myapp ls -l

By default, the first instance (0) is targeted. Specify other instances with the --instance parameter:

$ stackato ssh myapp --instance 1 ls -l

Note

This command is considered experimental.

ssh api [command]

Run interactive ssh to target

run [–instance <instance>] <appname> [command]

Run an arbitrary command on a running instance Please see ssh command above which is the replacement for run.

stats <appname>

Display resource usage for the application

instances <appname>

List application instances

open [appname]

Open primary application url in a browser

open <url>

Open any url in a browser

open api

Open target web console in a browser

Application Environment

env <appname>

List application environment variables

env-add <appname> <variable[=]value>

Add an environment variable to an application

env-del <appname> <variable>

Delete an environment variable to an application

Services

services

Lists of services available and provisioned

create-service <service> [–name,–bind]

Create a provisioned service

create-service <service> <name>

Create a provisioned service and assign it <name>

create-service <service> <name> <app>

Create a provisioned service and assign it <name>, and bind to <app>

delete-service [servicename]

Delete a provisioned service

bind-service <servicename> <appname>

Bind a service to an application

unbind-service <servicename> <appname>

Unbind service from the application

clone-services <src-app> <dest-app>

Clone service bindings from <src-app> application to <dest-app>

dbshell <appname> [<servicename>] [–print]

Invoke interactive db shell for a bound service.

tunnel [servicename] [–port port] [–allow-http]

Create a local tunnel to a service.

tunnel [servicename] [clientcmd] [–allow-http]

As above, and start a local client.

Administration

user

Display user account information

passwd

Change the password for the current user

logout

Logs current user out of the target system

add-user [–email, –passwd] (admin)

Register a new user

delete-user <user> (admin)

Delete a user and all apps and services

users (admin)

List all users and associated applications.

admin report [<filename>] (admin)

Retrieve a gzip compressed tarball of a Stackato system report for diagnosing server issues. If output filename is not specified, it defaults to stackato-report.tgz.

System

runtimes

Display the supported runtimes of the target system

frameworks

Display the recognized frameworks of the target system

Misc

aliases

List aliases

alias <alias[=]command>

Create an alias for a command

unalias <alias>

Remove an alias

targets

List known targets and associated authorization tokens

Users, Groups, and Limits

group

Show the current group. May be none.

group <name>

Make the named group the current group to use. Once set, the group name does not need to be specified for groups commands.

group reset

Unset the current group.

groups create <groupname> (admin)

Create a new named group

groups delete <groupname> (admin)

Remove the named group

groups (admin)

List the known groups, and the users belonging to them

limits [groupname|username] [–mem MEM] [–apps N] [–appuris N] [–services N] [–sudo BOOL]

Set (admin only) or retrieve limits for a group or user. Without group/user use current group. Without current group use current user.

groups limits <groupname>

Displays the current limits for a group

groups add-user <groupname> <username> (admin)

Add the specified user to the named group

groups delete-user <groupname> <username> (admin)

Remove the specified user from the named group

groups users [groupname]

List users belonging to the named group. Without group, list for the current group. Non-admin users can only query groups for which they are a member.

Help

help [command]

Get general help or help on a specific command

options

Get help on available options

Stackato Admin

Most server-side Stackato configuration is done using the stackato-admin command-line tool. It consolidates all node management operations (starting, stopping, specialization, configuration, etc.).

Run stackato-admin help to get more information.

Usage

stackato-admin <command> [options]

Summary

• stackato-admin help
• stackato-admin admin grant|revoke <email-1> [ .. <email-n]
• stackato-admin become micro [-o <domain>] [-n <hostname>] [-e <endpoint>]
• stackato-admin become <role-1> [ .. <role-n>] -m <mbus> -e <endpoint> [ -o <FQDN> -n <hostname> ]
• stackato-admin configure [-m <mbus>] [-e <endpoint>]
• stackato-admin export [options] <filename>
• stackato-admin import [options] <filename>
• stackato-admin info
• stackato-admin max-client-upload <size (MB)>
• stackato-admin remap-hosts <old_host> <new_host>
• stackato-admin rename <hostname> [–skip-remap-hosts]
• stackato-admin report
• stackato-admin roles
• stackato-admin start|stop|restart [<service>]
• stackato-admin status [<service>]
• stackato-admin tail
• stackato-admin update-services-ip <ip>
• stackato-admin upstream-proxy [-h] [–auth-user <username> –auth-pass <password>] {set,delete} <proxy_addr>

Commands

help

Show the help screen.

admin grant <email-1> [ .. <email-n>]

Grant admin role to the given users. Granting an admin role implicitly turns the Restricted Mode on.

admin revoke <email-1> [ .. <email-n>]

Revoke admin role from the given users. It is OK to revoke the last admin role.

become micro [-o <domain-name>] [-n <hostname>] [-e <api-endpoint>]

Make this machine a microcloud (all-in-one).

-o –domain-name <domain-name>

Base domain name, must properly resolve to the host’s IP; deployed apps will appear as <appname>.<domain-name>. (default: hostname.local)

-n –hostname <hostname>

Same as –domain-name, except ‘.local’ will be appended to <hostname> if it isn’t a fully qualified domain name. –hostname is ignored if –domain-name is specified too.

-e –endpoint <api-endpoint>

The external API domain name (default: api.<domain-name>)

become [-h] <roles [roles ...]> -m <mbus-ip> -e <api-endpoint> [ -o <FQDN> -n <hostname> ]

Specialize this machine to fulfill the specified roles.

roles

The roles to assign to this node. The shorthand ‘all’ role will assign all the available roles

Available roles: controller router dea mysql postgresql redis mongodb stager

-e –endpoint <api-endpoint>

The API endpoint to register this nodes services with. The API endpoint can be found by running stackato-admin info on the cloud controller

-m –mbus-ip <mbus-ip>

The MBUS IP to connect to NATS subsystem, usually the external IP of the cloud controller

-o –domain <FQDN>

The resolvable fully qualified domain name to assign to this node, normally only needed for the cloud controller

-n –hostname <hostname>

The local hostname to apply to this node

-h –help

shows the help for this command

This form of the command turns the Restricted Mode on.

Note

Both ‘-o’ and ‘-n’ must be supplied together in order to trigger the renaming of this node.

Warning

This command might be destructive to the deployed apps. The apps might lose data and most likely will require an update. A full backup is recommended.

configure [-m <mbus-ip>] [-e <api-endpoint>]

Change the specified parameters.

export <options> [<filename>]

Dump all data from Stackato for later restore. You may provide a filename, the default is stackato-[datetime]-dump.zip.

The default is a bare dump (no services are dumped, just the internal Stackato DB and all droplets).

Run stackato-admin export -h for the full options list.

import <options> <filename>

Restore into Stackato from an existing dump file.

Restores nothing by default, you must specify what you want to restore using switches.

Run stackato-admin import -h for the full list of switches.

info

Show the current config.

max-client-upload <size (MB)>

Specify the maxmium application size (total size of all files and folders in the push directory) a user can push to the Stackato cloud.

remap-hosts <old_host> <new_host>

Update the cloud controller applications with the new URL mappings after a migration or import.

rename <hostname> [ –skip-remap-hosts ]

Change micro cloud’s hostname. For use only with .local networking. --skip-remap-hosts can be used to skip the automatic update of currently deployed application(s) base URIs.

report

Generate a system diagnosis report for detailed analysis of issues.

roles

Displays a list of available roles.

start|stop|restart [<service>]

Start, stop or restart VCAP components without restarting the whole system.

status [<service>]

Show the status of all services or a specified service.

tail

Tail on the VCAP logs.

update-services-ip <new ip>

Update the services IPs to new locations following a migration of data services (such as MySQL, MongoDB, PostgreSQL, Redis, etc.).

upstream-proxy [-h] [–auth-user <username> –auth-pass <password>] {set,delete} <proxy_addr>

Used to specify HTTP proxy authorization credentials if required by the upstream proxy. --auth-user and --auth-pass must be used together.

Restricted Mode

In Restricted Mode users can’t add themselves. This mode is assumed for all non-microcloud setups. New users can be added either:

1. remotely, by a logged-in admin user
2. directly on the controller machine