Note: Please go to docs.rightscale.com to access the current RightScale documentation set.
Home > Guides > RightLink 6 > Using RightLink > Command Line Utilities - v6.x

Command Line Utilities - v6.x

Overview

The following command line utilities are useful for setting and getting information between RightLink enabled images and the RightScale platform.

Availability

The following command line utilities are available for use on instances with RightLink v5.8 and above. For example, if you are using a RightImage (e.g. RightImage_CentOS_5.6_x64_v5.8) or a custom RightScale-enabled image that includes RightLink v5 and above. If you are using older RightImages, some RightLink utilities might not be supported.

Warning!

We encourage you to use our ServerTemplates and RightImages. However, if you do create custom images and would like to RightLink-enable them, please see Creating RightScale-enabled Images with RightLink.

 

Table of Contents (abbreviated)

General Information

RightScale's command line utilities are found in /usr/bin on Linux systems*.  To see all installed "rs" utilities:


ls /usr/bin/rs_*

From within a running instance you can issue a "--help" or "-h" command line flag to see synopsis, example and usage information. For example:


rs_log_level -h
rs_run_recipe --help

Below is documentation for the more commonly used RightScale command line utilities for Chef.


Note: The following utility also exists in the /usr/bin directory.

  • rs_reenroll and rs_thunk - Not designed to be used by RightScale customers or partners.  (This is an Internal tool used by RightScale.)

Windows Support

Although the example screenshots below are from a Linux system, these command line utilities are part of RightLink on Windows systems as well.

  • Usage is the same as Linux systems
  • /usr/bin is part of the PATH environment variable in Linux and an equivalent is added to the Windows PATH as well.

RightLink Utilities

rs_connect

RightScale Server Import Utility (rs_connect).

This utility allows an arbitrary virtual or physical machine to be managed by the RightScale dashboard.

Usage

rs_connect [options]

Options

--attach, -a Attach this machine to a server
--force, -f Force attachment even if server appears already connected
--cloud, -c Name of cloud in which instance is running or 'none' to indicate instance is not running in any cloud. If a cloud has already been selected during installation of RightLink then this option will override that choice. If no choice has been made then the default is 'none'.
--help: Display help
--version: Display version information

 


rs_log_level

Synopsis

RightScale Log Level Manager (rs_log_level)
RightLink has two different log levels to set: Chef and the RightLink agent itself. Generally the Chef log level is more useful, so that is what the utility and any external tags modifying the log level will default to setting.

To set the log level for Chef, don't pass the --agent parameter. You may also set the log level for Chef by setting a tag on your RightScale Server of the form rs_agent_dev:log_level=(debug|info|warn|error|fatal). The tag will always override the value specified on the command line. The Chef log level is evaluated on every converge. This means you must set the Server tag before launch to get debug logging for the boot bundle.  

To set the level for the RightLink agent itself, pass the --agent parameter. The RightLink agent log level is evaluated every time RightLink is started. You must restart RightLink with a "service restart rightlink" in Linux or via the Service manager in Windows for agent debug logging to take effect.

Usage

rs_log_level [--agent] [--log-level, -l debug|info|warn|error|fatal]

 

Options

--log-level, -l LVL Set log level of either Chef or the RightLink Agent.  If --agent is also specified, the Agent log will be set.  Otherwise, the Chef log level will be set
--agent, -a Modal flag to view or set the agent log level. Without this flat the Chef log level will be set instead.
--verbose, -v Display debug information
--help Display help
--version Display version information

 

 

No options prints the current RightLink agent log level.

Examples

Retrieve log level


rs_log_level

Set Chef log level to debug


rs_log_level --log-level debug
Or tag set on your RightScale Server: rs_agent_dev:log_level=debug

Retrieve agent log level


rs_log_level --agent

Set RightLink Agent log level to debug (restart restart of RightLink agent to take effect)


rs_log_level --agent --log-level debug

rs_ohai

Synopsis

RightScale Ohai (rs_ohai) is an implementation of Ohai by RightScale
rs_ohai is a utility that inspects a running instance and discovers relevant system-specific data.

Usage

Options

-d,  --directory DIRECTORY A directory to add to the Ohai search path
-f,  --file FILE A file to run Ohai against
-l,  --log_level LEVEL Set the log level (debug, info, warn, error, fatal)
-L,  --logfile LOGLOCATION Set the log file location, defaults to STDOUT - recommended for daemonizing
-v,  --version Show chef version
-h,  --help Show this message

 

Examples

Retrieve system data:


rs_ohai

Set the log level to debug*:


rs_ohai --log_level debug
rs_ohai -l debug

*Note: most commands invoked by Ohai/Chef are logged with the debug severity for easier debugging of troublesome providers or recipes. 


rs_reenroll

Designed for RightScale internal use only. Not intended for use by end users.


rs_run_recipe

Synopsis

rs_run_recipe runs Chef recipes attached to your ServerTemplate.  With RightLink 5.7 and above, you can also execute Chef recipes on other instances within the deployment based upon tags.  Like any tag used with the RightScale platform, these tags can be plain tags ("foo") or machine tags ("foo:bar=baz") Their values are arbitrary and user-defined; users may apply tags through UI or API, or RightScripts/recipes included in ServerTemplates may cause servers to tag themselves.

Usage 

rs_run_recipe --name, -n NAME [--json, -j JSON_FILE] [--verbose, -v]

 

Options

--name, -n NAME Chef recipe name to run
--json, -j JSON_FILE JSON file name for JSON to be merged into attributes before running recipe
--thread, -t THREAD Schedule the operation on a specific thread name -t THREAD for concurrent execution. Thread names must begin with a letter and can consist only of lower-case alphabetic characters, digits, and the underscore character.
--policy, -P POLICY Audits for the executable to be run will be grouped under the given policy name. All detail will be logged on the instance, but limited detail will be audited.
--audit_period -a PERIOD_IN_SECONDS Specifies the period of time that should pass between audits
--recipient_tags, r TAG_LIST Tags for selecting which instances the script will be run on.  RightScripts will be run on instances which contain ALL tags supplied.  Note that TAG_LIST is a single parameter. When supplying multiple tags, provide a single quoted string with the tags separated with spaces.   Because of this tags supplied this way can not contain any spaces. Available with RightLink 5.7 and above.  Like any tag used with the RightScale platform, these tags can be plain tags ("foo") or machine tags ("foo:bar=baz") Their values are arbitrary and user-defined; users may apply tags through UI or API, or RightScripts/recipes included in ServerTemplates may cause servers to tag themselves.
--scope, -s SCOPE Scope for selecting tagged recipients: single or all (default all)
--timeout, -t TIMEOUT Maximum time to wait for response from RightScale platform.  Defaults to 60 seconds.
--cfg-dir, -c DIR Set directory containing configuration for all agents
--verbose, -v Display progress information
--help Display help
--version Display version information
Examples

Run the recipe web_apache::do_restart on the currently running server with verbose output


rs_run_recipe --name "web_apache::do_restart" --verbose

Run the recipe web_apache::do_restart on all servers with the tag foo


rs_run_recipe --name "web_apache::do_restart" -r "foo"

Run the recipe recipe mysql::backup on all servers with tags to denote its a database server and the master database.


rs_run_recipe -n "mysql::backup" -r "app:role=database database:master=true"

Run the recipe rightscale::setup_hostname with a created node.json override file:


# ensure root can only read the json file if on a shared system
touch /root/node.json && chmod -v 770 /root/node.json

# simple bash heredoc for creating the node.json
cat <<EOF> /root/node.json
{
  "rightscale" : {
     "timezone":"Australia/Sydney"
  }
}
EOF

# run rs_run_recipe with the node.json created
rs_run_recipe -v --name="rightscale::setup_timezone" --json /root/node.json

rs_run_right_script

 

Synopsis

RightScale RightScript Runner
rs_run_right_script allows running RightScripts from within an instance. With RightLink 5.7 and above, you can also execute RightScripts on other instances within the deployment based upon tags.  Like any tag used with the RightScale platform, these tags can be plain tags ("foo") or machine tags ("foo:bar=baz") Their values are arbitrary and user-defined; users may apply tags through UI or API, or RightScripts/recipes included in ServerTemplates may cause servers to tag themselves.

Usage

rs_run_right_script --identity, -i ID [--parameter, -p NAME=type:VALUE]* [--verbose, -v] [--recipient_tags, -r TAG_LIST]

rs_run_right_script --name, -n NAME [--parameter, -p "NAME=type:VALUE" -p "FOO=text:bar" -p "PING=text:pong"]* [--verbose, -v] [--recipient_tags, -r TAG_LIST]

* Can appear multiple times

Options

--identity, -i ID RightScript or ServerTemplateChefRecipe id.  For example, 
https://my.rightscale.com/acct/1/right_scripts/12345, where '12345' is the ID
--name, -n NAME RightScript name (overriden by id)
--parameter, -p NAME=type:VALUE Define or override RightScript input.  Can be specified multiple times.
Note: If you use rs_run_right_script with the -p option, you must pass a COMPLETE set of input values in which case the input values that are defined on the server are not merged. If you omit any inputs, e.g. do not use -p, then the values defined on the server are used. However we do not provide a way to mix and match.​
--thread, -t THREAD Schedule the operation on a specific thread name for the concurrent execution. Thread names must begin with a letter and can consist only of lower-case alphabetic characters, digits, and the underscore character.
--policy, -p POLICY Audits for the executable to be run will be grouped under the given policy name. All detail will be logged on the instance, but limited detail will be audited. Available with RightLink 5.8 and above.
--audit_period, -a PERIOD_IN_SECONDS Specifies the period of time that should pass between audits. Available with RightLink 5.8 and above.
--recipient_tags, -r TAG_LIST Tags for selecting which instances the script will be run on.  RightScripts will be run on instances which contain ALL tags supplied.  Note that TAG_LIST is a single parameter. When supplying multiple tags, provide a single quoted string with the tags separated with spaces.   Because of this tags supplied this way can not contain any spaces. Available with RightLink 5.7 and above.  Like any tag used with the RightScale platform, these tags can be plain tags ("foo") or machine tags ("foo:bar=baz") Their values are arbitrary and user-defined; users may apply tags through UI or API, or RightScripts/recipes included in ServerTemplates may cause servers to tag themselves.
--scope, -s SCOPE Scope for selecting tagged recipients: single or all (Default: all)
--timeout, -t TIMEOUT Maximum time to wait for response from RightScale platform.  Defaults to 60 seconds.
--cfg-dir, -c DIR Set directory containing configuration for all agents
--verbose, -v Display progress information
--help Display help
--version Display version information

 

Examples

Run RightScript with an ID of 34 and verbose output:


rs_run_right_script -i 34 -v
rs_run_right_script --identity 34 --verbose

Run RightScript with name, 'Install Nginx' and verbose output:


rs_run_right_script -n "Install Nginx" -v
rs_run_right_script --name "Install Nginx" --verbose

Run RightScript with and ID of 14 and override the input value for 'APPLICATION' with 'Mephisto':


rs_run_right_script -i 14 -p "APPLICATION=text:Mephisto"
rs_run_right_script --identity 14 --parameter "APPLICATION=text:Mephisto"

Run RightScript, 'Hello World!' with credential, 'HelloWorldText' for input, HW_TEXT:


rs_run_right_script --n "Hello World!" --p "HW_TEXT=cred:HelloWorldText"
rs_run_right_script --name "Hello World!" --parameter "HW_TEXT=cred:HelloWorldText"
Run the "register app server" RightScript on the server that is tagged as being a load balancer. This option takes a space-separated list of one or more tags, which will be used to select one or more target servers on which to run the script or recipe.

rs_run_right_script -n "APP register app server" -r "app:role=load_balancer"
Run the MySQL backup recipe on servers that are tagged as being a database machine and also a master.

rs_run_right_script -n "MySQL Do Backup" -r "app:role=database database:master=true"

rs_shutdown

Synopsis

RightScale System Shutdown Utility (rs_shutdown).

This utility allows the given system to be shutdown or rebooted.

Usage

rs_shutdown [options]

Options

--reboot, -r Request reboot
--stop, -s Request stop (boot volume is preserved)
--terminate, -t Request termination (boot volume is discarded)
--immediately, -i       Request immediate shutdown (reboot, stop or terminate) bypassing any pending scripts and preserving instance state.  Note that the immediate flag only applies when called from a RightScript. When this flag is set within a script block in a Chef recipe the boot bundle will continue executing, behaving as a deferred shutdown. If you want to reboot immediately within Chef, you must call "exit 0" within a ruby_block resource after calling rs_shutdown.
--deferred, -d Request deferred shutdown (reboot, stop or terminate) pending finishing of any remaining scripts (default)
--verbose, -v Display debug information
--help Display help
--version Display version information

rs_tag

Synopsis

RightScale Tagger (rs_tag)

Tagger allows listing, adding and removing tags on the current instance and querying for all instances with a given set of tags.

Note: Spaces in tags are not supported in RightLink v5.7 and earlier.

Usage
 rs_tag (--list, -l | --add, -a TAG | --remove, -r TAG | --query, -q TAG[s])

Options

--list, -l List current instance tags
--add, -a TAG NAME Add tag NAME. 
--remove, -r TAG NAME Remove tag NAME
--query, -q TAG[s] Query tag information about instances in your deployment
--die, -e Exit with error if query/list fails
--timeout, -t TIMEOUT Maximum time to wait for response from RightScale platform. (Default = 60 seconds)
--verbose, -v Display debug information
--help Display help
--version Display version information
--format, -f FMT Output format: json, yaml, text
Examples

Retrieve all tags:


rs_tag --list
rs_tag -l

 

Add tag 'opinions:tags=awesome' to instance:


rs_tag --add 'opinions:tags=awesome'
rs_tag -a 'opinions:tags=awesome'

 

Remove tag 'opinions:tags=awesome' from instance:


rs_tag --remove 'opinions:tags=awesome'
rs_tag -r 'opinions:tags=awesome'

 

Get and print last tag value for 'opinions:tags':


tag=$(rs_tag --list | grep 'opinions:tags' | head -n 1) && tag_value=${tag##*=}
echo 'Opinion on tags: '"$tag_value"

 

Remove all tags:


for i in `rs_tag --list | grep - | awk '{print $2}'`; do $(rs_tag --remove $i) ; done

 

In a RightScript, manage a unique tag 'on itself' using an Input value:


#!/bin/bash -e

# RightScript: Set node DNS hostname tag

# NODE_HOSTNAME can be set to any type text, environment variable, credential etc.
# e.g. EC2_PUBLIC_HOSTNAME

# remove any existing rs_node:dns_hostname tags
tags_remove=$(rs_tag --list | grep 'rs_node:dns_hostname' | awk '{ print $2 }')

# remove existing tags
for tag in `echo $tags_remove`
do
	echo Removing "$tag"
	rs_tag --remove "$tag"
done

# Add rs_node dns hostname tag
rs_tag --add 'rs_node:dns_hostname='"$NODE_DNS_HOSTNAME"

# get and print 1st/last set rs node dns hostname
tag=$(rs_tag --list | grep 'rs_node:dns_hostname' | head -n 1) && node_dns_hostname=${tag##*=}
echo 'Current/latest node dns hostname: '"$node_dns_hostname"

echo 'Done.'

 

Querying for tags:

Use rs_tag with --query, -q TAG[s] to query tag information about instances in your deployment/account (depends on deployment settings). TAG[s] is a machine tag or a space-delimited list of machine tags. Starting with RightLink 6.0 TAG could contain spaces, in that case it has to be quoted (rs_tag -q "tag with spaces"). You can use some wildcard functions in the TAG[s] by substituting an asterisk (*) for the value part of the machine tag - for example, rs_tag -q "loadbalancer:app=*".

 

Note: This is not a fully supported wildcard function. Semi-wildcard functions will not work, such as rs_tag -q "loadbalancer:app=prod*"

 

This returns a JSON object to stdout with the following syntax:

{ <agentA_id> : { "tags": [ <tag_n> ] } }


# rs_tag --query "rs_logging:state=*"
{
  "rs-instance-05c03c0150c3b55b83a63b4eb8c0f2af5156d8ea-5013179": {
    "tags": [
      "rs_launch:type=auto",
      "rs_logging:state=active",
      "rs_login:state=active",
      "rs_monitoring:state=active"
    ]
  },
  "rs-instance-00f2710adb07e72bbabf42092c93c675098a9ef0-5013178": {
    "tags": [
      "rs_launch:type=auto",
      "rs_logging:state=active",
      "rs_login:state=active",
      "rs_monitoring:state=active"
    ]
  },
  "rs-instance-71334da6925feee899ee1e5d58cc8c8b2423a59a-5325028": {
    "tags": [
      "rs_logging:state=active",
      "rs_login:state=active",
      "rs_monitoring:state=active"
    ]
  }
}
 
Please note that this is not a full wildcard function. You will receive an error if you attempt to enter the following: 

# rs_tag --query "rs_logging:sta*"
# rs_tag --query "rs_logging:*"
# rs_tag --query "rs_logg*"
Any of these will instead produce an error about an invalid wildcard statement.

rs_config

Synopsis

RightScale configuration manager (rs_config).

Allows you get, set and list various RightLink configuration options which are saved to /etc/rightscale.d/right_link/config.yaml.

Note: The decommission_timeout feature takes effect immediately so it can be used in running scripts. Note, however, that the decommission_timeout option must be set before a decommission is triggered. Setting it during decommission will have no effect on the timeout. Other options take effect at boot time, so they should be used when creating or rebundling images.

Usage

 


 rs_config (--list, -l | --set, -s NAME VALUE | --get, -g NAME)

Options

 

--list, -l

Lists all supported feature configurations and their values

--format, -f FMT

Output format for --list action (json, yaml, text)

--set, -s NAME VALUE

Set feature NAME to specified VALUE

--get, -g NAME

Outputs the value of the given feature (NAME) to stdout

--help, -h

Display help

--version, -v

Display version information

Examples

Set decommission_timeout to 120 seconds (default value is 180):


rs_config --set decommission_timeout 120

 

Get decommission_timeout value:


rs_config --get decommission_timeout

 

Disable managed_login_enable feature:


rs_config --set managed_login_enable off

 

Enable motd_update:


rs_config --set motd_update true

 

rs_state

Synopsis

RightScale run state reporter (rs_state).

Allows to get the current server state. This utility is useful for idempotency in RightScripts and Chef recipes. For example, the utility can be called during a decommission script and an attached volume detached and destroyed based on whether the state is "shutting-down:reboot" or "shutting-down:terminate". 

Usage

rs_state --type, -t  TYPE

Options

--type, -t TYPE

Display desired state by provided TYPE (run or agent)

Possible "run" values: booting, booting:reboot, operational, stranded, shutting-down:reboot, shutting-down:terminate, shutting-down:stop

Possible "agent" values: pending, booting, operational, stranded, decommissioning, decommissioned

--help, -h

Display help

--version, -v

Display version information

 

rs_thunk

Designed for RightScale internal use only. Not intended for use by end users.


See also

You must to post a comment.
Last modified
16:41, 17 Feb 2015

Tags

Classifications

This page has no classifications.

Announcements

None

Glossary | 用語용어 Site Map | Site Help Community Corporate Site Get Support Dashboard Login
Doc Feedback Product Feedback Resources MultiCloud Marketplace Forums

Dashboard Status


© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.