In addition to the standard set of ROS Environment Variables, there are a few additional environment variables that you can set to affect the behavior of SROS. Of these, the most important to understand are SROS_SECURITY, and SROS_POLICY as they are commonly used in the system and frequently mentioned in documentation.

Environment variables serve a variety of roles in SROS:

• Effecting a Node runtime: First and foremost, the SROS_SECURITY and SROS_POLICY effect how a SROS Node runs. The SROS_SECURITY is an important environment variable that tells a Node what security method to use. SROS_POLICY affects the policy invocation of a the SROS security method set by SROS_SECURITY, (e.g. limiting a node network accsess over topics, services, parameters, and API calls by considering other nodes' certificates).

• Finding files: There are also several SROS environment variables that enable SROS to locate keystore and configuration files in the filesystem. Many of these can be overridden by Remapping Arguments as well, which have precedence over environment variables.

These environment variables and more are described in greater detail below.

Required SROS Environment Variables

The only required environment variables for SROS are SROS_SECURITY and SROS_POLICY. By default these are automatically set for you by sourcing /opt/ros/ROSDISTRO/setup.bash. (Replace ROSDISTRO with the desired ROS distribution, e.g. indigo.)

SROS_SECURITY

SROS_SECURITY sets the security implementation that SROS will use to secure ROS connections.

export SROS_SECURITY=TLSv1_2

SROS_POLICY

SROS_POLICY sets the policy implementation that SROS will use to secure ROS connections. A policy implementation it necessary for a given security implementation to more than simple certificate signature validation.

export SROS_POLICY=NAMESPACE

SROS_KEYSERVER_URI

SROS_KEYSERVER_URI is a required setting that tells nodes where they can locate the keyserver. It should be set to the XML-RPC URI of the keyserver. Great care should be taken when using localhost, as that can lead to unintended behaviors with remotely launched nodes. If the SROS_KEYSERVER_URI is not set, then this URI will default to that of the ROS_MASTER_URI, with the port set to one bellow (e.g. 11311 - 1 = 11310)

System Data Environment Variables

SROS_HOME

By default, SROS writes data to ROS_HOME/sros. This location can be changed by setting SROS_HOME. You can also change the location of certain individual directories in ROS_HOME/sros (e.g. SROS_KEYSTORE_PATH, SROS_CONFIG_DIR).

SROS_KEYSTORE_PATH

By default, SROS considers the location of the keystore to be SROS_HOME/keystore. If this location is not writable to SROS, or if you wish for save or load key files from a keystore elsewhere, set SROS_KEYSTORE_PATH to that path.

SROS_CONFIG_DIR

By default, SROS considers the location of SROS related configuration files to be SROS_HOME/config, (e.g. files such as keyserver settings and policy profiles). If this location is not writable to SROS, or if you wish for log files to be written elsewhere, set SROS_CONFIG_DIR to that directory.

SROS_KEYSERVER_VERIFY

By default, SROS expects the target keystore to contain a certificate authorities before contacting the keyserver. This permits nodes to securely verify a trusted keyserver before finalizing a connection handshake. SROS_KEYSERVER_VERIFY specifies whether a certificate is required from the other side of the connection, and whether it will be validated if provided. It must be one of the three values CERT_NONE (certificates ignored), CERT_OPTIONAL (not required, but validated if provided), or CERT_REQUIRED (required and validated).

Thus the default this is set to CERT_REQUIRED this necessitates that a the keyserver possess a valid and trusted certificate before connecting. If a node's local keystore is devoid of the necessary certificate authorities, the highly recommend course of action is to install them securely beforehand. However if you are within a network you completely and utterly trust, you may override this default setting using CERT_NONE, or CERT_OPTIONAL.

export SROS_KEYSERVER_VERIFY=CERT_REQUIRED

SROS_PASSWORD

If private keys within a Node's nodestore are encrypted by a secret cypher, the Node will require the secret password to unencrypt them for use upon runtime. This standard environment variable allows you share the secret password with the Node without being prompted for it before startup.

Optional SROS Environment Variables

There are optional environment variables for SROS. If these are not set, then secure conservative defaults will be made by SROS specific commands.

SROS_POLICY_MODE

Similar to AppArmor, a policy can invoked using different mode types. Currently there are four separate modes supported by the default NAMESPACE policy, with enforce bing default:

• enforce

  • This mode enforces the original policy given, as only permitted actions as specified by the policy profile are allowed.

• audit

  • This mode enforces the original policy given, as only permitted actions as specified by the policy profile are allowed. However all events logged, including allowed and unallowed actions.

• complain

  • This mode merely complains when the original policy is violated by logging all violations, but yet does not rejected any action.

• train

  • This mode is used to train policy profiles. When violations occur, the requested action is amended to the list of allowable action in the specified policy profile configuration. Much in the same way with complain, no action is rejected.

SROS_POLICY_CONFIG

The policy profile used when deliberating whether an action is allowed is often defined by the security and policy implementation, e.g. embedded within X.509 certificates following common PKI practices. However, there are time when it is useful to for SROS to know of deriving policy profile config for the derived embedded policies, e.g. when attempting to train an existing profile and amend additional policies to it, much like AppArmor's aa-genprof utility. This variable points to this config file, and if not set will point by default to $SROS_CONFIG_DIR/keyserver_config.yaml.