-
Notifications
You must be signed in to change notification settings - Fork 34
CLI User's Guide
This page introduces basic usage of the pScheduler command-line interface.
You may wish to familiarize yourself with the nomenclature and data types before proceeding.
NOTE: The CLI is not intended for programmatic control of pScheduler. There is a ReST interface available for that purpose, and using that instead is strongly recommended.
Everything in the pScheduler CLI begins by running the pscheduler program and specifying a command and, optionally, arguments:
% pscheduler command [ arguments ]
A short-form alias, psc, is provided and can be used as a substitute. This will be used throughout the rest of this guide. Note that psc is an alias; if invoking the CLI in a script, it should be done in its longer form (pscheduler).
At all points along the command line, using the --help switch will cause pScheduler to display a synopsis of the command so far, available options and, where appropriate, examples.
These commands are used to give pScheduler work to do, monitor progress and display the results.
Synopsis: psc task [ task-options ] test-type test-options
This command submits a task to pScheduler.
The simplest task that can be run is a one-shot test with no special options, such as this one which conducts a round-trip time (rtt) test betwen the local host and ps.example.net and display the results:
psc task rtt --dest ps.example.net
Note that the --dest option following rtt is a test option specific to the test type being requested. Each test has its own set of options, so what follows the test type will vary. Most tests that have an option in common that serves the same purpose have consistent names between them. For example, any test that involves sending data to another host (rtt, trace, throughput, latency) will specify the other hosts using the --dest option.
The task command has a set of its own options (task options) that go before the test type. These options are related to how the task is run rather than what test is being conducted. For example, the --quiet switch suppresses the diagnostic information that is usually produced.
psc task --quiet rtt --dest www.perfsonar.net
Many tests have a --source switch which specifies where the test should originate:
host1% psc task latency --source 12.34.56.78 --dest host3
If the source is an address on another host, pScheduler will contact the pScheduler system on that host and attempt to submit the task there. For example:
host1% psc task latency --source host2 --dest host3
This will cause host1 to contact host2 ask it to measure latency between there and host3.
By default, pScheduler will automatically select a tool for a task based on three factors:
- Availability of tools on each of the participating nodes that can conduct the type of test requested.
- The ability of those tools to carry out the test according to the parameters. Not all tools are capable of making good on all of the parameters. For example,
tracerouteis capable of setting the number of hops allowed by adjusting the time to live buttracepathis not. In atracetest where this is requested,traceroutewill list itself as able to participate buttracepathwill not. - A preference value hard-wired into each tool by its authors. If multiple tools can carry out a task as requested, pScheduler will select one with the highest preference value or, in the event of a tie, the one that is alphabetically first. The preference value is used to promote the use of newer, better tools while still keeping older, deprecated tools available for situations where they're required.
Using the --tool switch, the user can control what tool(s) pScheduler selects for a task:
psc task --tool tracepath trace --dest www.perfsonar.net
This will specify that the tracepath tool should be used for running the test. Similarly, repeating the switch forms a list of acceptable tools with those specified earlier being preferred over those specified later. For example:
psc task --tool tracepath --tool paris-traceroute trace --dest www.perfsonar.net
Whether or not tools are specified, a task where no available tool is capable of making the measurement will be rejected.
Any pScheduler task can be configured to run repeatedly by adding options to the task command:
-
--starttimestamp - Run the first iteration of the task at timestamp. -
--repeatduration - Repeat runs at intervals of duration. -
--max-runsn - Allow the task to run up to n times. -
--untiltimestamp - Repeat runs of the task until timestamp. -
--slipduration - Allow the start of each run to be as much as duration later than their ideal scheduled time. If the environment variablePSCHEDULER_SLIPis present, its value will be used as a default, and. Failing that, the default will bePT5M. (Note that the slip value also applies to non-repeating tasks.)
For example, to measure round-trip time 50 times once per hour:
psc task --repeat PT1H --max-runs 50 rtt --dest pingme.example.com
It is strongly recommended that repeating tasks apply as much slip as is tolerable to allow pScheduler to work around scheduling conflicts. Larger slip values will will give tasks a better chance of executing. For example: psc task --repeat PT1H --slip PT30M rtt --dest pingme.example.com
Repeating tasks can be stopped using the cancel command.
The JSON version of a task specification can be sent to the standard output without scheduling using the --export switch:
psc task --export throughput --dest wherever --udp --ip-version 6 > mytask.json
NOTE: Tasks are not validated until submitted for scheduling, so it is possible to export invalid tasks.
A JSON file that was previously exported or generated elsewhere can be imported using the --import switch:
psc task --import mytask.json throughput
Test parameters may be changed on the fly by adding them to the command line after the test type:
psc task --import mytask.json throughput --dest somewhere.else
Synopsis: psc watch task-url
This command waits for runs of a task to complete and displays their results as they're produced. The task-url is the URL provided by the task command when a task is submitted.
Breaking out of the program will have no effect on the task continuing to run.
Example: psc watch https://ps.example.org/pscheduler/tasks/f1fc3a56-080c-46ec-a777-91c26460a233
Synopsis: psc cancel task-url
This command cancels any future runs of the task specified by task-url, which is the URL provided by the task command when a task is submitted. Any run of the task which is underway will continue to completion.
Example: psc cancel https://ps.example.org/pscheduler/tasks/f1fc3a56-080c-46ec-a777-91c26460a233
Synopsis: psc schedule [ --host host ] [ delta | start end ]
This command asks pScheduler to fetch scheduled task runs from the past, present or future.
With no arguments, all runs for the next hour will be displayed.
With one (delta) argument, the schedule between now and some point in the past or future will be shown. Deltas are ISO 8601 durations, with -PT1H meaning one hour in the past and P1D meaning one day in the future.
With two (start and end) arguments, the schedule within a range of times will be shown. Either argument can be a delta as described above (e.g. -P2D) or a ISO 8601 timestamp (e.g., 2016-09-04T12:34:56+0400).
Example: psc schedule -PT1H PT2H
Synopsis: psc result run-url
This command retrieves and displays the results of a previous run of a task.
Note that pScheduler systems have a configurable retention period for old data (default one week), so run URLs will only be valid until the results have been purged from the system.
Example: psc result https://somehost/pscheduler/tasks/8035c79c-5a08-41bf-8fef-639739d1850c/runs/f2ee21f2-e49b-40b1-be5f-ee6e7efc1640
Synopsis: psc debug [ on | off ] [ service ... ]
The debug command enables or disables the sending of debug output from pScheduler's internal components to the system log. Specify the state by providing on or off as the first argument and optionally list the service(s) whose debug state you want to change. The valid services are:
-
api- REST API -
archiver- Transfer of run results to long-term storage -
runner- Execution of measurements -
scheduler- Scheduling of tests -
ticker- Periodic activities
If no services are specified, debugging on all are turned on or off.
This command must be run as the pscheduler user or root.
Synopsis: psc diags
The diags command produces a very long file of diagnostic information useful in troubleshooting problems. Normally, the output will be redirected to a file and sent to someone on the perfSONAR development team who will have requested it. You must be the superuser (root) to run this command.