Chapter 9. Command Reference

9.1. Broker Administration Commands

These tools are installed with the openshift-origin-broker and openshift-origin-broker-util RPMs.

9.1.1. oo-accept-broker

This command checks that your broker setup is valid and functional. It is run without options on a broker host.
If there are no errors, it displays PASS and exits with return code 0. With the -v option added, it displays the current checks that are being performed.
If there are errors, they are displayed, and the return code is the number of errors.

Example 9.1. Checking For Errors With oo-accept-broker

# oo-accept-broker -v

INFO: SERVICES: DATA: mongo, Auth: mongo, Name bind
INFO: AUTH_MODULE: rubygem-openshift-origin-auth-mongo
INFO: NAME_MODULE: rubygem-openshift-origin-dns-bind
INFO: Broker package is: openshift-origin-broker
INFO: checking packages
INFO: checking package ruby
INFO: checking package rubygems
INFO: checking package rubygem-rails
INFO: checking package rubygem-passenger
INFO: checking package rubygem-openshift-origin-common
INFO: checking package rubygem-openshift-origin-controller
INFO: checking package openshift-origin-broker
INFO: checking ruby requirements
INFO: checking ruby requirements for openshift-origin-controller
INFO: checking ruby requirements for config/application
INFO: checking firewall settings
INFO: checking services
INFO: checking datastore
INFO: checking cloud user authentication
INFO: auth plugin = /var/www/openshift/broker/config/initializers/broker.rb:2: uninitialized constant ApplicationObserver (NameError) from -:6
INFO: checking dynamic dns plugin
INFO: checking messaging configuration
PASS

9.1.2. oo-accept-systems

This command checks that node host PUBLIC_HOSTNAME and PUBLIC_IP configuration settings are globally valid and unique. It also checks the cartridges installed on the nodes and the status of the broker's cache. It is run without options on the broker host.
If there are no errors, the command displays PASS and exits with return code 0. With the -v option added, it displays the current checks that are being performed.
If there are errors, they are displayed, and the return code is the number of errors.

Example 9.2. Checking For Errors With oo-accept-systems

# oo-accept-systems -v

INFO: checking that each public_hostname resolves to external IP
INFO: PUBLIC_HOSTNAME node1.example.com for node2.example.com resolves to 10.4.59.136
INFO: PUBLIC_HOSTNAME node2.example.com for node1.example.com resolves to 10.4.59.133
INFO: checking that each public_hostname is unique
INFO: checking that public_ip has been set for all nodes
INFO: PUBLIC_IP 10.4.59.136 for node1.example.com
INFO: PUBLIC_IP 10.4.59.133 for node2.example.com
INFO: checking that public_ip is unique for all nodes
INFO: checking that all node hosts have cartridges installed
INFO: cartridges for node1.example.com: cron-1.4|ruby-1.9|perl-5.10|jenkins-client-1.4|diy-0.1|jenkins-1.4|php-5.3|haproxy-1.4|abstract|abstract-jboss|jbosseap-6.0|mysql-5.1|postgresql-8.4|ruby-1.8|jbossews-1.0|python-2.6|abstract-httpd
INFO: cartridges for node2.example.com: diy-0.1|jenkins-client-1.4|cron-1.4|jbossews-1.0|php-5.3|abstract-httpd|ruby-1.9|python-2.6|jbosseap-6.0|perl-5.10|abstract|postgresql-8.4|abstract-jboss|ruby-1.8|jenkins-1.4|haproxy-1.4|mysql-5.1
INFO: checking that same cartridges are installed on all node hosts
INFO: checking that broker's cache is not stale
INFO: API reports carts: diy-0.1|jbossews-1.0|php-5.3|ruby-1.9|python-2.6|jbosseap-6.0|perl-5.10|ruby-1.8|jenkins-1.4|jenkins-client-1.4|cron-1.4|postgresql-8.4|haproxy-1.4|mysql-5.1
PASS

9.1.3. oo-admin-chk

This command checks that application records in the MongoDB datastore are consistent with the gears that are present on the node hosts. With the -v option added, it displays the current checks that are being performed.

Example 9.3. Checking For MongoDB Consistency with oo-admin-chk

# oo-admin-chk -v

Started at: 2013-05-03 03:36:28 +1000
Time to fetch mongo data: 0.005s
Total gears found in mongo: 3
Time to get all gears from nodes: 20.298s
Total gears found on the nodes: 3
Total nodes that responded : 1
Checking application gears and ssh keys on corresponding nodes:
51816f026892dfec74000004 : String...	OK
518174556892dfec74000040 : String...	OK
518176826892dfec74000059 : String...	OK
Checking node gears in application database:
51816f026892dfec74000004...	OK
518174556892dfec74000040...	OK
518176826892dfec74000059...	OK
Success
Total time: 20.303s
Finished at: 2013-05-03 03:36:49 +1000
With the -l option added, additional levels of checks can be included: 
# oo-admin-chk -l 1 -v

9.1.4. oo-admin-clear-pending-ops

The oo-admin-clear-pending-ops removes stuck user operations from the application queue, so that they no longer hold up the queue preventing other operations from proceeding on that application. 
 oo-admin-clear-pending-ops [options]
The available options are:
Option Description
-t, --time n
Deletes pending operations older than n hours. (Default: 1)
-u, --uuid uuid Prunes only applications with the given UUID.

Note

In most scenarios, you should not need to use the oo-admin-clear-pending-ops command directly. It is most commonly run automatically by the ose-upgrade tool as part of the upgrade process described in the OpenShift Enterprise Deployment Guide. This ensures the database is in a consistent state before data migrations happen.

9.1.5. oo-admin-console-cache

The oo-admin-console-cache command manages the Management Console Rails application's cache. 
 oo-admin-console-cache [-c | --clear] [-q | --quiet]
The available options are:
Option Description
-c, --clear
Removes all entries from the Management Console Rails application's cache.
-q, --quiet Shows as little output as possible.

See Also:

9.1.6. oo-admin-broker-auth

This command recreates broker authentication keys. If AUTH_SALT is changed in /etc/openshift/broker.conf, restart the broker service and run the oo-admin-broker-auth command to recreate authentication tokens for all applicable gears. 
# oo-admin-broker-auth

9.1.7. oo-admin-broker-cache

This command clears the broker Rails application cache. 
# oo-admin-broker-cache --clear

9.1.8. oo-admin-ctl-app

This command provides administration command options for applications. 
# oo-admin-ctl-app
Modifying the HAProxy Multiplier

The HAProxy multiplier sets the ratio of how many HAproxy cartridges are enabled for application scaling. Setting the multiplier number to 2 means that for every two gears, one will have HAProxy enabled. Alternatively, you can set the minimum and maximum number of HAProxy cartridges allowed in scaling.

Modify the number of HAProxy multplier using the oo-admin-ctl-app command with the --multiplier option. 
# oo-admin-ctl-app -l username -a appname --cartridge haproxy-1.4 -c set-multiplier --multiplier 2

9.1.9. oo-admin-ctl-authorization

Use this command to either delete only expired authorization tokens for a user, or to delete both valid and expired authorization tokens for a user.
On the broker host, delete all expired authorization tokes for a user with: 
# oo-admin-ctl-authorization -c expire
On the broker host, delete all valid and expired authorization tokens for a user with: 
# oo-admin-ctl-authorization -c revoke_all

9.1.10. oo-admin-ctl-district

This command performs district operations, such as creating or removing districts and adding or removing nodes from districts. It can also be used to tag nodes in districts with a region and zone.

See Also:

9.1.11. oo-admin-ctl-domain

This command is used to query and control a user's domain. It produces detailed output in YAML format. 
# oo-admin-ctl-domain

See Also:

9.1.12. oo-admin-ctl-region

The oo-admin-ctl-region command is used to create, list, or destroy regions and add or remove zones within a given region.

See Also:

9.1.13. oo-admin-ctl-team

The oo-admin-ctl-team tool manages global teams and is invoked with a set of commands using the -c or --command option: 
 oo-admin-ctl-team -c command [options]
The available commands are:
Command Description
list
Lists all teams.
create
Creates a new team. Requires either both the --name and --maps-to options, or both the --groups and --config-file options. For example: 
# oo-admin-ctl-team create --name team_name --maps-to group_name
Alternatively: 
# oo-admin-ctl-team create --groups group_name_1,group_name_2 --config-file file_name
update Updates an existing team LDAP correspondance. Requires both the --name and --maps-to options.
delete Deletes a team. Requires the --name option.
show Displays a team and its members. Requires either the --name or --maps-to option.
sync Syncs global teams with the LDAP groups. Requires the --config-file option.
sync-to-file Generates a sync file for review. No changes are made to the teams and their members. Requires the --out-file and --config-file options.
sync-from-file Syncs from a file. Requires the --in-file option.
Other options are:
Option Description
--broker path
Specifies the path to the broker.
--create-new-users Creates new users in OpenShift if they do not exist.
--remove-old-users Removes members from a team that are no longer in the group.

See Also:

9.1.14. oo-admin-ctl-usage

The oo-admin-ctl-usage displays usage data for all users. The output includes user names, gears, usage type and duration. 
 oo-admin-ctl-usage --list [--enable-logger]
The following options are available for OpenShift Enterprise:
Option Description
--list
List usage data.
--enable-logger Print error and warning messages to the log file instead of to the terminal.
The following table provides more information on the output of the --list option.
Field Description
User User names the user accumulating the resource usage.
Gear Gear indicates the UUID of the relevant gear.
UsageType
GEAR_USAGE is related to how long a gear has been in use.
ADDTL_FS_GB is related to how long additional storage has been in use on a gear.
Usage Usage lists the duration of the gear (in hours).

See Also:

9.1.15. oo-admin-ctl-user

This command administers users on the system. Some features are disabled for user accounts by default, such as the ability to add additional storage to gears or add private SSL certificates to aliases, and require this tool in order to enable them or set an explicit allowed value for the user.
Option Description
-l, --login Username
Login name for an OpenShift Enterprise user account. Required unless -f is used.
-f, --logins-file File_Name
File containing one login name per line. Required unless -l is used.
-c, --create
Create user account(s) for the specified login name(s) if they do not already exist.
--setmaxdomains Number
Set the maximum number of domains a user is allowed to use.
--setmaxgears Number
Set the maximum number of gears a user is allowed to use.
--setmaxteams Number Set the maximum number of teams a user is allowed to create.
--allowviewglobalteams true|false Add or remove the capability for a user to search and view any global team.
--allowprivatesslcertificates true|false Add or remove the capability for a user to add private SSL certificates.
--addgearsize Gear_Size Add a gear size to the capabilities for a user.
--removegearsize Gear_Size Remove a gear size from the capabilities for a user.
--allowha true|false Allow or disallow the high-availability applications capability for a user.
-q, --quiet Suppress non-error output.
-h, --help Show usage information.
Many common administrative tasks make use of the oo-admin-ctl-user command:

9.1.16. oo-admin-move

This command moves a gear from one node to another. Note that moving gears requires the rsync_id_rsa private key in the broker host's /etc/openshift/ directory and the public key in each node host's /root/.ssh/authorized_keys file as explained in the OpenShift Enterprise Deployment Guide at https://access.redhat.com/site/documentation. A gear retains its UNIX UID when moved, therefore cross-district moves are only allowed when the destination district has the same gear UID available.
To move a gear from one node to another, use the oo-admin-move command on the broker host, specifying the desired gear's UUID and the node host you wish to move the gear to:

Example 9.4. Moving a Gear From One Node to Another

# oo-admin-move --gear_uuid 3baf79139b0b449d90303464dfa8dd6f -i node2.example.com

9.1.17. oo-admin-repair

This command checks for and fixes various inconsistencies in the MongoDB datastore on the broker. For example, because a mismatch in SSH keys can be a potential security risk, the tool fixes any mismatches found by taking information from the broker datastore and pushing it to the gear. See the --help output for additional uses. 
# oo-admin-repair

9.1.18. oo-admin-upgrade

This command upgrades custom and community cartridges on a gear to the latest available version and applies gear-level changes that affect cartridges. See Section 5.3, “Upgrading Custom and Community Cartridges” for more information on the upgrade process and oo-admin-upgrade command usage.

Important

The oo-admin-upgrade tool is also often required when applying asynchronous errata updates provided by Red Hat for OpenShift Enterprise. See the latest OpenShift Enterprise Deployment Guide at https://access.redhat.com/site/documentation for usage instructions as it applies to these types of updates.

9.1.19. oo-admin-usage

The oo-admin-usage command displays a resource usage report for a particular user, or aggregated usage data of all users. The output includes usage type, gear ID, and duration. 
 oo-admin-usage [-l username] [options]
If -l username is omitted, the command displays aggregated data on all users.
Other options further restrict the output:
Option Description
-a, --app application_name
Filters usage data by the given application name.
-g, --gear gear_id Filters usage data by the given gear ID.
-s, --start start_date Filters usage data by the given start date, expressed as ISO dates (YYYY-MM-DD).
-e, --end end_date Filters usage data by the given end date, expressed as ISO dates (YYYY-MM-DD).
The following table provides more information on the output of this command:
Field Description
Usage Type
GEAR_USAGE is related to how long a gear has been in use with the gear size in parentheses.
ADDTL_FS_GB is related to how long additional storage has been in use on a gear with the number of GBs in parentheses.
Gear ID Gear ID indicates the UUID of the relevant gear with the associated application name in parentheses.
Duration Duration indicates the start and end time of the gear (or start time and PRESENT if still in use).

See Also:

9.1.20. oo-admin-ctl-cartridge

In OpenShift Enterprise 2.1, the oo-admin-ctl-cartridge command facilitates cartridge management on the broker, including importing cartridge manifests from nodes and activating or deactivating cartridges. This command must be used to ensure that newly installed or updated cartridges can be used in applications.

Note

This command is not used for cartridge management in OpenShift Enterprise 2.0.

See Also:

9.1.21. oo-register-dns

This command updates DNS A records in BIND by wrapping an nsupdate command. Normally this command is used for broker or node hosts, although it can be used for other infrastructure hosts. Do not use this command to change DNS records for applications and gears, because these are CNAME records. 
# oo-register-dns