Chapter 15. RLS Admin Guide

Home -> Toolkit -> Docs -> 4.0 -> Admin -> Docbook	Website Email Lists Search:

Chapter 15. RLS Admin Guide
Prev		Next

1. Building and Installing

For detailed instructions on building and installing RLS, see Appendix A, Building and Installing RLS.

2. Configuring

2.1. Configuration overview

Configuration settings for the RLS are specified in the globus-rls-server.conf file.

If the configuration file is not specified on the command line (see the -c option) then it is looked for in both:

$GLOBUS_LOCATION/etc/globus-rls-server.conf
/usr/local/etc/globus-rls-server.conf if GLOBUS_LOCATION is not set

NOTE: command line options always override items found in the configuration file.

The configuration file is a sequence of lines consisting of a keyword, whitespace, and a value. Comments begin with # and end with a newline.

2.2. Syntax of the interface

Table 15.1. Settings

`acl user: permission [permission]`	`acl` entries may be a combination of DNs and local usernames. If a DN is not found in the gridmap file then the file is used to search the `acl` list. A gridmap file may also be used to map DNs to local usernames, which in turn are matched against the regular expressions in the `acl` list to determine the user's permissions. `user` is a regular expression matching distinguished names (or local usernames if a gridmap file is used) of users allowed to make calls to the server. There may be multiple `acl` entries, with the first match found used to determine a user's privileges. `[permission]` is one or more of the following values: `lrc_read` Allows client to read an LRC. `lrc_update` Allows client to update an LRC. `rli_read` Allows client to read an RLI. `rli_update` Allows client to update an RLI. `admin` Allows client to update an LRC's list of RLIs to send updates to. `stats` Allows client to read performance statistics. `all` Allows client to do all of the above.
`authentication true\|false`	Enable or disable GSI authentication. The default value is `true`. If authentication is enabled (`true`), clients should use the URL schema `rls:` to connect to the server. If authentication is not enabled (`false`), clients should use the URL schema `rlsn:`.
`db_pwd password`	Password to use to connect to the database server. The default value is `changethis`.
`db_user databaseuser`	Username to use to connect to database server. The default value is `dbperson.`
`idletimeout seconds`	Seconds after which idle connections close. The default value is `900.`
`loglevel N`	Sets loglevel to N (default is `0`). Higher levels mean more verbosity.
`lrc_bloomfilter_numhash N`	Number of hash functions to use in Bloom filters. The default value is `3`. Possible values are 1 through 8. This value, in conjunction with`lrc_bloomfilter_ratio`, will determine the number of false positives that may be expected when querying an RLI that is updated via Bloom filters. Note: The default values of `3` and `10` give a false positive rate of approximately 1%.
`lrc_bloomfilter_ratio N`	Sets ratio of bloom filter size (in bits) to number of LFNs in the LRC catalog (in other words, size of the Bloom filter as a multiple of the number of LFNs in the LRC database.) This is only meaningful if Bloom filters are used to update an RLI. Too small a value will generate too many false positives, while too large a value wastes memory and network bandwidth. The default value is `10`. Note: The default values of `3` and `10` give a false positive rate of approximately 1%.
`lrc_buffer_time N`	LRC to RLI updates are buffered until either the buffer is full or this much time in seconds has elapsed since the last update. The default value is `30`.
`lrc_dbname`	Name of LRC database. The default value is `lrcdb.`
`lrc_server true\|false`	If LRC server, the value should be `true`. The default value is `false.`
`lrc_update_bf seconds`	Interval in seconds between LRC to RLI updates when the RLI is updated by Bloom filters. In other words, how often an LRC server does a Bloom filter soft state update. This can be much smaller than the interval between updates without using Bloom filters (`lrc_update_ll`). The default value is `300`.
`lrc_update_factor N`	If `lrc_update_immediate` mode is on, and the LRC server is in sync with an RLI server (an LRC and RLI are synced if there have been no failed updates since the last full soft state update), then the interval between RLI updates for this server (`lrc_update_ll`) is multiplied by the value of this option.
`lrc_update_immediate true\|false`	Turns LRC to RLI immediate mode updates on (`true`) or off (`false`). The default value is `false`.
`lrc_update_ll seconds`	Number of seconds before an LRC server does an LFN list soft state update. The default value is `86400`.
`lrc_update_retry seconds`	Seconds to wait before an LRC server will retry to connect to an RLI server that it needs to update. The default value is `300`.
`maxbackoff seconds`	Maximum seconds to wait before re-trying listen in the event of an I/O error. The default value is `300.`
`maxfreethreads N`	Maximum number of idle threads. Excess threads are killed. The default value is `5.`
`maxconnections N`	Maximum number of simultaneous connections. The default value is `100`.
`maxthreads N`	Maximum number of threads running at one time. The default value is `30`.
`myurl URL`	URL of server. The default value is `rls://<hostname>:port`
`odbcini filename`	Sets environment variable `ODBCINI`. If not specified, and `ODBCINI` is not already set, then the default value is `$GLOBUS_LOCATION/var/odbc.ini.`
`pidfile filename`	Filename where pid file should be written. The default value is `$GLOBUS_LOCATION/var/<programname>.pid`.
`port N`	Port the server listens on. The default value is `39281.`
`result_limit limit`	Sets the maximum number of results returned by a query. The default value is `0` (zero), which means no limit. If a query request includes a limit greater than this value, an error (`GLOBUS_RLS_BADARG`) is returned. If the query request has no limit specified, then at most `result_limit` records are returned by a query.
`rli_bloomfilter true\|false`	RLI servers must have this set to accept Bloom filter updates. If `true`, then only Bloom filter updates are accepted from LRCs. If `false`, full LFN lists are accepted. Note: If Bloom filters are enabled, then the RLI does not support wildcarded queries.
`rli_bloomfilter_dir none\|default\|pathname`	If an RLI is configured to accept bloom filters (`rli_bloomfilter true`), then Bloom filters may be saved to this directory after updates. This directory is scanned when an RLI server starts up and is used to initialize Bloom filters for each LRC that updated the RLI. This option is useful when you want the RLI to recover its data immediately after a restart rather than wait for LRCs to send another update. If the LRCs are updating frequently, this option is unnecessary and may be wasteful in that each Bloom filter is written to disk after each update. `none` Bloom filters are not saved to disk. This is the default. `default` Bloom filters are saved to the default directory: `$GLOBUS_LOCATION/var/rls-bloomfilters` if `GLOBUS_LOCATION` is set else, `/tmp/rls-bloomfilters` `pathname` Bloom filters are saved to the named directory. Any other string is used as the directory name unchanged. The Bloom filter files in this directory have the name of the URL of the LRC that sent the Bloom filter, with slashes(/) changed to percent signs (%) and ".bf" appended.
`rli_dbname database`	Name of the RLI database. The default value is `rlidb`.
`rli_expire_int seconds`	Interval (in seconds) between RLI expirations of stale entries. In other words, how often an RLI server will check for stale entries in its database. The default value is `28800`.
`rli_expire_stale seconds`	Interval (in seconds) after which entries in the RLI database are considered stale (presumably because they were deleted in the LRC). The default value is `86400`. This value should be no smaller than `lrc_update_ll`. Stale RLI entries are not returned in queries. Note: If the LRC server is responding, this value is not used. Instead the value of `lrc_update_ll` or `lrc_update_bf` is retrieved from the LRC server, multiplied by 1.2, and used as the value for this option.
`rli_server true\|false`	If an RLI server, the value should be `true`. The default value is `false.`
`rlscertfile filename`	Name of the X.509 certificate file identifying the server. This value is set by setting environment variable `X509_USER_CERT`.
`rlskeyfile filename`	Name of the X.509 key file for the server. This value is set by setting environment variable `X509_USER_KEY`.
`startthreads N`	Number of threads to start initially. The default value is `3`.
`timeout seconds`	Timeout (in seconds) for calls to other RLS servers (e.g., for LRC calls to send an update to an RLI).

3. Deploying

This section does not apply to the RLS.

4. Testing

You can use the programs globus-rls-adminand globus-rls-cli to test functionality. See their respective man pages for details on their use.

Start the server in debug mode with the command:
```
$GLOBUS_LOCATION/bin/globus-rls-server -d [-N] 
```
The -N option is helpful: if you do not have a host certificate for the server host, or a user certificate for yourself, it disables authentication.
Ping the server using globus-rls-admin:
```
$GLOBUS_LOCATION/bin/globus-rls-admin -p rls://serverhost
```
If you disabled authentication (by starting the server with the -Noption), then use this command:
```
$GLOBUS_LOCATION/bin/globus-rls-admin -p rlsn://serverhost
```

5. Security Considerations

Security recommendations include:

Dedicated User Account: It is recommended that users create a dedicated user account for installing and running the RLS service (e.g., globus as recommended in the general GT installation instructions). This account may be used to install and run other services from the Globus Toolkit.
Key and Certificate: It is recommended that users do not use their hostkey and hostcert for use by the RLS service. Create a containerkey and containercert with permissions 400 and 644 respectively and owned by the globus user. Change the rlskeyfile and rlscertfile settings in the RLS configuration file ($GLOBUS_LOCATION/etc/globus-rls-server.conf) to reflect the appropriate filenames.
LRC and RLI Databases: Users must ensure security of the RLS data as maintained by their chosen database management system. Appropriate precautions should be made to protect the data and access to the database. Such precautions may include creating a user account specifically for RLS usage, encrypting database users' passwords, etc.
RLS Configuration: It is recommended that the RLS configuration file ($GLOBUS_LOCATION/etc/globus-rls-server.conf) be owned by and accessible only by the dedicated user account for RLS (e.g., globus account per above recommendations). The file contains the database user account and password used to access the LRC and RLI databases along with important settings which, if tampered with, could adversely affect the RLS service.

6. Troubleshooting

Information on troubleshooting can be found in the FAQ.

7. Usage statistics collection by the Globus Alliance

The following usage statistics are sent by RLS Server by default in a UDP packet:

Component identifier
Usage data format identifier
Time stamp
Source IP address
Source hostname (to differentiate between hosts with identical private IP addresses)
Version number
Uptime
LRC service indicator
RLI service indicator
Number of LFNs
Number of PFNs
Number of Mappings
Number of RLI LFNs
Number of RLI LRCs
Number of RLI Senders
Number of RLI Mappings
Number of threads
Number of connections

The RLS sends the usage statistics at server startup, server shutdown, and once every 24 hours when the service is running.

If you wish to disable this feature, you can set the following environment variable before running the RLS:

export GLOBUS_USAGE_OPTOUT=1

By default, these usage statistics UDP packets are sent to usage-stats.globus.org:4180 but can be redirected to another host/port or multiple host/ports with the following environment variable:

export GLOBUS_USAGE_TARGETS="myhost.mydomain:12345 myhost2.mydomain:54321"

You can also dump the usage stats packets to stderr as they are sent (although most of the content is non-ascii). Use the following environment variable for that:

export GLOBUS_USAGE_DEBUG=MESSAGES

Also, please see our policy statement on the collection of usage statistics.

Prev		Next
Chapter 14. CAS Admin Guide	Home	Appendix A. Building and Installing RLS