freightctl - Man Page

Control utility to manage freight-agent database


frieghtctl [options] <operation>


freightctl Is a command and control utility to manipulate the database for a freight-agent cluster.


freightctl [OPTIONS]
-h | --help

Display options and usage for the daemon

-c | --config </path/to/config/file>

Specify the config file to use with freight-agent (defaults to

-v | --verbose

Verbose output


host [add|del] <hostname> Adds or removes a host from the list of available nodes to execute containers. note! Admin only operation

host [subscribe|unsubscribe] <hostname> Marks the given host as elligible to serve containers for a given tennant (as defined by the login credentials in the freight configuration

host list [tennant] Querys the database to determine which hosts a tennant may use.  [tennant] option is only required if the db admin is querying

repo [add|del] <name> <url> Adds or removes a repository from the database for a given tennant

container [create] <cname> <iname> [chost] Request the creation of a container <cname> with instance name <iname> on host <chost>. Note that chost is optional, if left blank the freight-master process will be notified to schedule a host on behalf of the tennant.  chost may also be the reserved keyword all, which will cause all hosts belonging to the tennant to be notified, and the first to respond will create the container.  Note that created containers are created in the STAGED state, it is stared by issuing the boot command below

container boot <iname> Requests that the container named by <iname> be started.  Only containers in the STAGED or FAILED state may be booted

container poweroff <iname> Requests that the container named by <iname> be shutdown and returned to the STAGED state.  On containers in the RUNNING state may be powered off

container [delete] <iname> Deletes the requested container from the database.  Only containers in the staged or failed state may be deleted.

container [list] Lists the containers for the tennant and what state they are in

network [create] <name> <configuration> Creates a networked named <name> with configuration supplied in the file named by <configuration>.  For the configuration file format, see freight-network-config

network [delete] <name> Delete the named network from the cluster. No container may be using the named network, or the delete operation will fail

network [list] List the available networks for the tennant

network [attach] <container> <network> Attaches the refereced container to the referenced network

network [detach] <container> <network> Detaches the referenced container from the referenced network

Container Life Cycle

A container in freight as manged by freightctl exists in the following state table

STAGEDContainer is created in DBSTART-REQUESTED
START-REQUESTEDContainer has been requested to bootINSTALLING,RUNNING,FAILED
INSTALLINGContainer image is downloading to agent systemRUNNING,FAILED
RUNNINGContainer is operationalFAILED,EXITING
EXITINGContainer is shutting downFAILED,STAGED
FAILEDContainer has encountered a failure-

Config File Format

See the freight-agent man page for a description of the config file.  freghtctl only uses the db section of the configuration


freightctl has direct access to the freight database, and as such is completely insecure, in that any tennant has access to other tennants information.  If you wish to implement a production level multitennant environment, use a freight front end to gate access to the cluster.


Apr 2015 Neil Horman