.. _rlm-options-file: #################### The RLM Options File #################### The RLM options file allows control over access to the *status*, *reread*, *shutdown* administration commands as well as control over the editing of options files. Options are provided to either allow (INCLUDE or INCLUDEALL) or disallow (EXCLUDE or EXCLUDEALL) administration command usage. Additionally, options are provided to create groups of users (GROUP) or hosts (HOST_GROUP) or IP addresses (INTERNET_GROUP). In addition, the RLM options file allows you to turn off logging of status requests (to the debug log) via the NOLOG option. Finally, the RLM options file allows you to set the defaults for the "Activate License" command in the menu. The RLM options file is called **rlm.opt**, and should be placed in the directory from which you run the RLM (or rlm.exe) binary. If you would like to add comments to the options file, start the line with the '#' character. There are 8 privileges which can be controlled in the RLM options file. Each privilege is specified with the appropriate privilege name in the RLM options file. Note that these privilege names are the same names that are used in the *RLM password file* if you are controlling access to the RLM web interface via user login. If you use the RLM password file, you should not use these lines in the RLM options file - in other words, you should use one mechanism or the other, but not both. ------ .. _rlm-privileges: ************************************************* RLM privileges controlled by the RLM options file ************************************************* .. list-table:: :header-rows: 1 * - Privilege Name - Meaning * - edit_meter - Allows modifying count for meter counters. * - edit_xfer - Allows editing server-server license transfer settings for ISV servers. * - logfiles - Enables the functions which change log files - switch, switchr, newlog. * - *edit_options* - *Removed in v16.0. Options now read-only.* * - *edit_rlm_options* - *Removed in v16.0. Options now read-only.* * - *remove* - *Removed in v16.0. Now restricted to Manage and Admin roles.* * - *reread* - *Removed in v16.0. Now restricted to Manage and Admin roles.* * - *shutdown* - *Removed in v16.0. Now restricted to Manage and Admin roles.* * - *status* - *Removed in v16.0. Now restricted to Manage and Admin roles.* The RLM options file syntax is a subset of :ref:`isv-options-file` syntax. The **privilege** names listed in the table above are used, where as in the ISV options file a **product** name would be used. By default, all privileges are granted to all users unless otherwise restricted in the RLM options file. ------ **************************************** Legal characters in the RLM options file **************************************** In general, all options file fields are white-space delimited, meaning that no data item can contain embedded spaces, tabs, newlines or carriage returns. In addition, the following four characters are illegal in data items in the ISV or RLM options (and license) file: "<", ">", "&", and double quote ("). The characters "<", ">", and "&" are legal in comments (lines beginning with "#") but nowhere else. .. warning:: All lines in option files (RLM or ISV) as well as license files must be shorter than 1024 characters. Anything over 1024 characters will be truncated. .. note:: Everything in the RLM options file is case-insensitive. In the following example RLM options file, status commands are only allowed from hosts on subnet 172.16.7.*, no one on host "excluded_host" can do a reread command, and only users on IP address 172.16.7.93 can do a shutdown. Each command (INCLUDE, EXCLUDE, etc) must be on a separate line. Also, RLM will not process reread or shutdown requests from pre-v9 command-line utilities. .. code-block:: text NO_OLD_RLMUTIL INCLUDE status internet 172.16.7.* EXCLUDE reread host excluded_host INCLUDE shutdown internet 172.16.7.93 For a detailed description of each option, see the section below. .. note:: *privilege* should be **one** of the privilege names from the table above. ------ .. _activate-option: ******** ACTIVATE ******** .. code-block:: text ACTIVATE [ url URL | isv ISVNAME] The ACTIVATE line allows you to set the defaults for the URL and ISV name for activation. The 2 forms of the ACTIVATE line are: * ACTIVATE url URL * ACTIVATE isv ISVNAME In the first form "URL" is the default URL used for activation. For example: .. code-block:: text ACTIVATE url www.reprisesoftware.com In the second form "ISVNAME" is the default ISV name used for activation. For example: .. code-block:: text ACTIVATE isv reprise .. note:: In v15.2 and earlier a third form was available (ACTIVATE off). Activation is now restricted to user with Manage or Admin roles. ------ .. _activate-test: ************* ACTIVATE_TEST ************* .. note:: This option is not currently available in v16.0. .. code-block:: text ACTIVATE_TEST [activation_key [hostid [count]]] The ACTIVATE_TEST line allows you to specify the parameters for the “Test License Activation” button in the GUI. You must specify the URL and the ISV on this line. The defaults for the other parameters are: .. list-table:: * - **activation_key** - “test” * - **hostid** - “12345678” * - **count** - 1 Example: .. code-block:: text ACTIVATE_TEST activate.yourwebsite.com yourISVName 1234-1234-1234-1234 ab12cd34 5 No special privileges are required to use the “Test License Activation” button. ACTIVATE_TEST is new in RLM v15.0 ------ ******* EXCLUDE ******* .. code-block:: text EXCLUDE [user|host|group|host_group|internet|project] [id=nnn] The EXCLUDE line removes the specified *privilege* from a particular user, host, group, host_group, IP address, or project. If you specify group or host_group, it must be defined by a GROUP or HOST_GROUP line in the RLM options file. Portions of the INTERNET address can be specified with a '*' (wildcard) which matches any address, e.g., 172.16.7.* If specified, the *id* applies this option to the license with an *id* of “*nnn*”. Example excluding the user group "engineers" (see GROUP below) from editing meter: .. code-block:: text EXCLUDE edit_meter group engineers .. note:: To use PROJECT the user needs to specify the project name in the environment variable RLM_PROJECT prior to starting RLM. To use INTERNET specify the internal (vs. external) IP address of the client machine. For a list of the privileges available, see :ref:`rlm-privileges` above. ------ ********** EXCLUDEALL ********** .. code-block:: text EXCLUDEALL [user|host|group|host_group|internet|project] The EXCLUDEALL line prevents usage of all capabilities defined by all privileges by a particular user, host, group, host_group, IP address, or project. If you specify group or host_group, it must be defined by a :ref:`group-option` or :ref:`host-group-options` line in the RLM options file. Portions of the INTERNET address can be specified with a '*' (wildcard) which matches any address, e.g., 172.16.7.* Example exluding the user "mike" from all privileges: .. code-block:: text EXCLUDEALL user mike .. note:: To use PROJECT the user needs to specify the project name in the environment variable RLM_PROJECT prior to starting RLM. To use INTERNET specify the internal (vs. external) IP address of the client machine. For a list of the privileges available, see :ref:`rlm-privileges` above. ------ .. _group-option: ***** GROUP ***** .. code-block:: text GROUP The GROUP line defines a group of users to be used in an EXCLUDE, EXCLUDEALL, INCLUDE, or INCLUDEALL line. Separate the usernames in the list by spaces. Multiple lines that specify the same GROUP name will have their lists of usernames concatenated. Example for a group named "engineers" with 3 users: .. code-block:: text GROUP engineers tom dick harry This example results in a group with 6 users: .. code-block:: text GROUP engineers tom dick harry GROUP engineers larry curly moe ------ .. _host-group-options: ********** HOST_GROUP ********** .. code-block:: text HOST_GROUP The HOST_GROUP line defines a group of hosts to be used in an EXCLUDE, EXCLUDEALL, INCLUDE or INCLUDEALL line. Separate the hostnames in the list by spaces. Multiple lines that specify the same HOST_GROUP name will have their lists of hostnames concatenated. Example for a group named "corporate" with 3 hosts: .. code-block:: text HOST_GROUP corporate node_a node_b node_c This example results in a group of 6 hosts: .. code-block:: text HOST_GROUP corporate node_a node_b node_c HOST_GROUP corporate node_d node_e node_f ------ ************** INTERNET_GROUP ************** .. code-block:: text INTERNET_GROUP The INTERNET_GROUP line defines a group of IP addresses to be used in an EXCLUDE, EXCLUDEALL, INCLUDE, INCLUDEALL, MAX or RESERVE line. Separate the IP addresses in the list by spaces. Multiple lines that specify the same INTERNET_GROUP name will have their lists of IP addresses concatenated. IP addresses can contain the wildcard ('*') character. Example: .. code-block:: text INTERNET_GROUP corporate 192.168.1.4 2.*.*.7 172.16.7.* This example results in a group of 6 IP addresses: .. code-block:: text INTERNET_GROUP corporate 192.168.17.2 192.168.17.2 192.168.17.2 INTERNET_GROUP corporate 172.16.7.4 172.16.7.5 172.16.7.6 ------ ******* INCLUDE ******* .. code-block:: text INCLUDE [user|host|group|host_group|internet|project] [id=nnn] The INCLUDE line grants the specified privilege to a particular user, host, group, host_group, IP address, or project. If you specify group or host_group, it must be defined by a GROUP or HOST_GROUP line in the RLM options file. Anyone not specified by the INCLUDE line is not allowed access to the capabilities defined by privilege. If specified, the *id* applies this option to the license with an *id* of “nnn”. Portions of the INTERNET address can be specified with a '*' which matches any address, e.g., 172.16.7.* Example granting the *status* privilege to the host group "engineers": .. code-block:: text INCLUDE status host_group corporate .. note:: To use PROJECT the user needs to specify the project name in the environment variable RLM_PROJECT prior to starting RLM. To use INTERNET specify the internal (vs. external) IP address of the client machine. For a list of the privileges available, see :ref:`rlm-privileges` above. ------ ********** INCLUDEALL ********** .. code-block:: text INCLUDEALL [user|host|group|host_group|internet|project] The INCLUDEALL line grants all privileges to a particular user, host, group, host_group, IP address, or project. If you specify group or host_group, it must be defined by a GROUP or HOST_GROUP line in the RLM options file. Anyone not on the INCLUDEALL list is not allowed to use a capability controlled by any privilege. Portions of the INTERNET address can be specified with a '*' which matches any address, e.g., 172.16.7.* Example granting all privileges to the user group "admins": .. code-block:: text INCLUDEALL group admins .. note:: To use PROJECT the user needs to specify the project name in the environment variable RLM_PROJECT prior to starting RLM. To use INTERNET specify the internal (vs. external) IP address of the client machine. For a list of the privileges available, see :ref:`rlm-privileges` above. ------ ************** NO_OLD_RLMUTIL ************** The NO_OLD_RLMUTIL line prevents pre-RLM-v9 command-line utilities from performing a reread, remove, or shutdown operation. The pre-v4.0 RLM utilities do not respect the RLM permissions for the reread or shutdown commands, and the pre-v9.0 utilities do not respect the permissions for the remove command. Adding NO_OLD_RLMUTIL to your ISV options file will prevent these older utilities from performing these commands, and only a v9 (or newer) RLM command-line utility can be used for this purpose. By default, all operations can be performed by all versions of the RLM command-line utilities. In order for NO_OLD_RLMUTIL to be effective, **it must be specified in both the RLM and the ISV** **server options files**. Example: .. code-block:: text NO_OLD_RLMUTIL ------ ***** NOLOG ***** NOLOG status ============ The NOLOG option instructs the RLM server to omit logging of status requests to the debug log. Example: .. code-block:: text NOLOG status This example causes the RLM server to omit the logging of status requests in the debug log.