Using rsv-control¶
Warning
This document is for software that will no longer be supported after the OSG 3.5 retirement (February 2022). See the Release Series Support Policy for details.
Overview¶
This document is for System Administrators. It details the usage of the rsv-control command for enabling, disabling, testing and running RSV probes.
rsv-control provides an interface to many RSV tasks. rsv-control can view RSV jobs, run metrics, enable or disable metrics and consumers, and allow advanced configuration.
Warning
rsv-control can be used to configure RSV as described here and in the advanced configuration document. Most site admins will be able to configure RSV by editing /etc/osg/config.d/30-rsv.ini and running osg-configure as described in the installation doc.
Using rsv-control to configure is for advanced RSV use including enabling non-default metrics. Admins who don't use rsv-control for configuration can still use it to view their RSV jobs, run RSV tests, and help debug RSV problems. Anyone can view the jobs, but you must be root or the RSV user (rsv by default) to execute other commands, e.g. run, enable and disable probes, or to turn RSV on and off.
Viewing RSV jobs¶
rsv-control provides two different views: viewing the desired state and viewing the current actual state.
- Desired = what metrics and consumers will start the next time RSV is started
- Actual = what metrics and consumers are currently running
Desired state¶
To view the desired state, use the --list (-l for short) flag. This will create one table for each host showing the metrics that are enabled to run against that host.
[email protected]# rsv-control --list
Metrics enabled for host: osgitb1.nhn.ou.edu | Service
----------------------------------------------------------+--------------------
org.osg.batch.jobmanager-default-status | OSG-CE
org.osg.batch.jobmanagers-available | OSG-CE
org.osg.certificates.cacert-expiry | OSG-CE
org.osg.certificates.crl-expiry | OSG-CE
org.osg.general.osg-directories-CE-permissions | OSG-CE
org.osg.general.osg-version | OSG-CE
org.osg.general.ping-host | OSG-CE
org.osg.general.vdt-version | OSG-CE
org.osg.general.vo-supported | OSG-CE
org.osg.globus.gram-authentication | OSG-CE
org.osg.globus.gridftp-simple | OSG-GridFTP
org.osg.gratia.condor | OSG-CE
org.osg.gratia.metric | OSG-CE
Metrics enabled for host: osg-edu.cs.wisc.edu:10443 | Service
----------------------------------------------------------+--------------------
org.osg.srm.srmcp-readwrite | OSG-SRM
org.osg.srm.srmping | OSG-SRM
Other options:
- To view all installed metrics use the
--all(-a) flag along with--list. This will print an extra table showing metrics that are disabled on all hosts. - If you are having problems with the output being truncated, try the
--wide(-w) flag.
Actual state¶
To view the current, running state of RSV jobs, use the --job-list flag (-j for short). This will show all metrics and consumers running in RSV. (It queries the underlying Condor Cron system that we use to run the metrics).
[email protected]# rsv-control --job-list
Hostname: osg-edu.cs.wisc.edu
ID OWNER ST NEXT RUN TIME METRIC
154.0 rsvuser I 11-19 12:15 org.osg.certificates.cacert-expiry
155.0 rsvuser R 11-19 11:23 org.osg.gratia.metric
156.0 rsvuser I 11-19 18:47 org.osg.general.vdt-version
157.0 rsvuser I 11-19 12:30 org.osg.certificates.crl-expiry
158.0 rsvuser I 11-19 11:31 org.osg.globus.gram-authentication
159.0 rsvuser I 11-19 11:41 org.osg.general.osg-version
160.0 rsvuser R 11-19 11:25 org.osg.batch.jobmanager-default-status
161.0 rsvuser I 11-20 04:59 org.osg.batch.jobmanagers-available
162.0 rsvuser I 11-19 11:37 org.osg.general.osg-directories-CE-permissions
163.0 rsvuser I 11-19 12:08 org.osg.globus.gridftp-simple
164.0 rsvuser I 11-19 12:09 org.osg.gratia.condor
165.0 rsvuser R 11-19 11:27 org.osg.general.ping-host
166.0 rsvuser I 11-19 18:47 org.osg.general.vo-supported
Hostname: osg-edu.cs.wisc.edu:10443
ID OWNER ST NEXT RUN TIME METRIC
113.0 rsvuser I 11-19 11:33 org.osg.srm.srmping
114.0 rsvuser R 11-19 11:28 org.osg.srm.srmcp-readwrite
ID OWNER ST CONSUMER
198.0 rsvuser R html-consumer
199.0 rsvuser R gratia-consumer
The ST field indicates the current job status:
- R = the metric is currently running
- I = the metric is idle and will be run at the next scheduled interval
- Any other letter may indicate a problem
- Consumers will always appear to be running even though they will only run once every five minutes.
Running a metric¶
rsv-control can be used to run metrics one time against a host. This can be useful for:
- updating the status of a metric that had a problem instead of waiting until the next scheduled run time
- testing a metric against a host before deciding whether to enable it
Note that the record for each run will be published to all active consumers. That is, it will be published to Gratia or will show up on your local web page, if you have those enabled.
Simplest test¶
Use the --run (-r) flag. You must also provide the --host flag. The syntax is:
rsv-control --run --host <HOST> <METRIC> [ <METRIC2> ...]
where <METRIC> is the full metric name (e.g. org.osg.general.osg-version). You can get the metric names from the --list output.
[email protected]# rsv-control --run \
--host osg-edu.cs.wisc.edu org.osg.general.osg-version
Running metric org.osg.general.osg-version:
metricName: org.osg.general.osg-version
metricType: status
timestamp: 2010-11-19 11:40:19 CST
metricStatus: OK
serviceType: OSG-CE
serviceURI: osg-edu.cs.wisc.edu
gatheredAt: vdt-itb.cs.wisc.edu
summaryData: OK
detailsData: OSG 1.2.15
EOT
Note the metricStatus in the example above: that's where you can see if it was successful or not. In this case, it was successful, because it printed OK.
You may run multiple metrics against a single host by specifying multiple metrics to rsv-control.
In order to run metrics against multiple hosts you must run rsv-control multiple times, once for each host.
Running all enabled metrics¶
When RSV is first installed it can take up to a day for each enabled metric to run once. A new option is provided to force each metric to run immediately, for all hosts. Use the --all-enabled flag along with --run. With this option it is not necessary to specify a host - all enabled metrics for all configured hosts will be run (in fact, if you do specify a host it will be ignored).
[email protected]# rsv-control -r --all-enabled
Running metric org.osg.certificates.cacert-expiry (1 of 15)
metricName: org.osg.certificates.cacert-expiry
metricType: status
timestamp: 2010-11-19 13:44:08 CST
metricStatus: OK
serviceType: OSG-CE
serviceURI: osg-edu.cs.wisc.edu
gatheredAt: vdt-itb.cs.wisc.edu
summaryData: OK
detailsData: Security Probe Version: 1.1
OK: CAs are in sync with OSG distribution
EOT
...
Passing extra configuration¶
If you want to pass extra configuration when running a metric without editing its configuration file you can make an INI-formatted file and pass it on the command line. For example, you can make a file like this for the org.osg.srm.srmclient-ping metric (tmp-srm.ini):
[org.osg.srm.srmclient-ping args]
srm-destination-dir=/srmcache/~
srm-webservice-path=srm/v2/server
Then use the --extra-config-file parameter and pass the path to the INI file:
[email protected]# rsv-control -r --extra-config-file tmp-srm.ini \
--host osg-edu.cs.wisc.edu:10443 org.osg.srm.srmclient-ping
Running metric org.osg.srm.srmclient-ping:
metricName: org.osg.srm.srmclient-ping
metricType: status
timestamp: 2010-11-19 14:12:35 CST
metricStatus: OK
serviceType: OSG-SRM
serviceURI: osg-edu.cs.wisc.edu:10443
gatheredAt: vdt-itb.cs.wisc.edu
summaryData: OK
detailsData: SRM server running on osg-edu.cs.wisc.edu is alive and responding to the srmping command.
. Details: Storage Resource Manager (SRM) Client version 2.1.5-16
Copyright (c) 2002-2009 Fermi National Accelerator Laboratory
...
Enabling and disabling metrics and consumers¶
Metrics and consumers can be enabled or disabled by rsv-control using the --enable and --disable flags. Note that "enable" and "disable" are desired states (this is similar to osg-control). After enabling a metric you should turn it on if you want it to be running immediately. After disabling a metric that is running, you should still turn it off (a message will print after each of these actions to remind you of this behavior).
Enabling¶
The syntax for enabling metrics looks similar to the syntax for running metrics:
rsv-control --enable --host <HOST> <METRIC> [ <METRIC2> ...]
You must provide a host to enable the metric against (in order to enable a metric on multiple hosts you must run rsv-control once per host).
[email protected]# rsv-control --enable \
--host osg-edu.cs.wisc.edu org.osg.gip.consistency
Enabling metric 'org.osg.gip.consistency' for host 'osg-edu.cs.wisc.edu'
One or more metrics have been enabled and will be started the next time RSV is started. To turn them on immediately run 'rsv-control --on'.
Consumers do not run against a specific host, they process records for all hosts. When enabling consumers a host is not required (if a host is passed it will be ignored).
[email protected]# rsv-control --enable nagios-consumer
Enabling consumer nagios-consumer
Disabling¶
The syntax for disabling metrics looks similar to the syntax for running metrics:
rsv-control --disable --host <HOST> <METRIC> [ <METRIC2> ...]
You must provide a host to disable the metric against (in order to disable a metric on multiple hosts you must run rsv-control once per host).
[email protected]# rsv-control --disable \
--host vdt-itb.cs.wisc.edu org.osg.local.containercert-expiry
Disabling metric 'org.osg.local.containercert-expiry' for host 'vdt-itb.cs.wisc.edu'
One or more metrics have been disabled and will not start the next time RSV is started. You may still need to turn them off if they are currently running.
Consumers do not run against a specific host, they process records for all hosts. When disabling consumers a host is not required (if a host is passed it will be ignored).
[email protected]# rsv-control --disable html-consumer gratia-consumer
Disabling consumer html-consumer
Disabling consumer gratia-consumer
Consumer already disabled
Metrics and consumers can both be listed in the same disable command.
Troubleshooting¶
Getting more information from rsv-control¶
The first step to getting more information is to run rsv-control with more verbosity. Use the --verbose (-v) flag. This flag can be used with any of rsv-control's abilities (run, enable, list, etc). The verbosity levels are:
- 0 = print nothing
- 1 = print warnings and errors along with usual output of command being run (1 is the default level)
- 2 = adds informational messages
- 3 = full debugging output
Using the RSV verify tool¶
The --verify flag will run some basic checks for your RSV installation:
[email protected]# rsv-control --verify
Testing if Condor-Cron is running...
OK
Testing if metrics are running...
OK (98 running metrics)
Testing if consumers are running...
OK (1 running consumers)
Checking which consumers are configured...
The following consumers are enabled: html-consumer
WARNING: The gratia-consumer is not enabled. This indicates that your
resource is not reporting to OSG.
This tool is still under development and it does only basic checks, but it is a good first step when debugging issues.
Running the RSV profiler¶
RSV has a tool to collect information useful for troubleshooting into a tarball that can be shared with the developers and support staff. To use it:
[email protected]# rsv-control --profile
Running the rsv-profiler...
OSG-RSV Profiler
Analyzing...
Making tarball (rsv-profiler.tar.gz)
Note
If you are getting assistance via the trouble ticket system, you must add a .txt extension to the tarball so it can be uploaded.
[email protected]# mv rsv-profiler.tar.gz rsv-profiler.tar.gz.txt