This section is dedicated to the description of the usage and the effects of the different commands and subcommands bundled with the pas command line tool.
All operations involving the use of the pas command line utility require the use of a subcommand, nonetheless some options common to all subcommands can only be set directly on the main pas command.
The usage of the pas command (obtained running pas --help on the command line) is the following:
pas [-h] [--version] [-v] [-q] [--settings SETTINGS_MODULE]
{authorize,execute,jobmgr,compile,init,measure,report} ...
Exchanges the public keys between all VMs to allow direct ssh connections between them without user input.
Compiles the given test case on all hosts (by default) or on the hosts provided on the command line through the --host option.
Executes the given test case on all hosts having a role of client (normally only one).
Sets up a new measurement and analysis environment in the selected directory (or in the CWD if none is provided).
Commands suite to remotely manage jobmgr instances.
Commands suite to execute measures and collect results.
Commands suite process collected measure results.
| -h, --help | Show this help message and exit. |
| --version | Show program’s version number and exit. |
| -v, --verbose | Increments the verbosity (can be used multiple times). |
| -q, --quiet | Decrements the verbosity (can be used multiple times). |
| --settings SETTINGS_MODULE | |
| The path to the settings module | |
The next two sections are dedicated to the description of some common arguments and options and to the documentation of all built-in subcommands, respectively.
The settings option lets you define the path to a directory containing the settings module (simply a settings.py file). This module is needed by some commands to correctly identify a working environment.
It is possible to use this option when invoking a command from outside the environment working directory.
It is also possible to set the path in the PAS_SETTINGS_MODULE shell environment variable instead.
These flags increment and decrement the verbosity respectively and can be used multiple times.
The short version -v and -q flags are also available.
The host option or its argument alternative syntax are not a general pas argument but are used often enough by subcommands to being worth to be documented here.
Many subcommands execute actions on remote machines. By default these actions are carried out on a predefined list of hosts (normally all or all members of a given role). Using this argument or the respective option variant, it is possible to explicitly define one ore more hosts on which executed the command.
Both variants can be used multiple times to provide more than one host.
A similar argument as made for the inclusion of the host argument or option in this section can be made for the MEASURE_CASE argument too.
The MEASURE_CASE argument takes the name of a measure case from the cases directory. In most cases the value is then coerced to a valid value using the pas.commands.select_case() command decorator, which means that the value can also be left out and the subcommand will prompt the user to select the desired value from a list of choices.
The following subcommands are already built-in and come bundled with all pas installations. In the next section is explained how it is possible to add custom subcommands to an existing pas installation, on a global or per-environment basis.
Usage: pas init [-h] [DIR]
The directory inside which the environment shall be created.
| -h, --help | show this help message and exit |
Sets up a new measurement and analysis environment in the selected directory (or in the CWD if none is provided).
The directory has to be empty or inexistent. The command will fail if the directory already exists and is non-empty.
The environment is mainly set up by recursively copying all the files inside pas.conf.suite_template to the newly created directory.
Usage: pas authorize [-h]
| -h, --help | Show this help message and exit. |
Exchanges the public keys between all VMs and adds each host to the known_hosts file of each other, in order to allow direct ssh connections between VMs without need for external input.
This command operates only on the default rsa key and uses the shared configuration directory to keep a temporary list of all public keys.
The function to which this command is bound doesn’t need (and doesn’t provide) any specific command-line options and can thus be called in normal library usage without any argument, like in the following example:
from pas.commands.authorize import command as authorize
authorize()
Usage: pas compile [-h] [--host HOST] [MEASURE_CASE]
Measure case to compile on the different hosts.
| -h, --help | Show this help message and exit. |
| --host HOST | Use this option to specify one or more hosts on which this command has to be run. The –host option can be specifed multiple times to define multiple hosts. |
Compiles the given test case on all hosts (by default) or on the hosts provided on the command line through the --host option.
If no measure case is provided and only one is available, it is compiled; if more are available, the user is presented with a list of available cases and asked to make a choice.
Usage: pas execute [-h] [MEASURE_CASE]
Measure case to execute on all client hosts.
| -h, --help | Show this help message and exit. |
Executes the given test case on all hosts having a role of client (normally only one).
If no measure case is provided and only one is available, it is compiled; if more are available, the user is presented with a list of available cases and asked to make a choice.
Usage: pas jobmgr start [-h] [HOST [HOST ...]]
Use this option to specify one or more hosts on which this command has to be run.
| -h, --help | Show this help message and exit. |
Starts the jobmgr on one or more hosts.
If no hosts are provided, then the command first starts the master hosts and then, after accounting for a startup delay, the child hosts.
If one or more hosts are provided, the start command is sent to all hosts at the same time.
Usage: pas jobmgr stop [-h] [HOST [HOST ...]]
Use this option to specify one or more hosts on which this command has to be run.
| -h, --help | Show this help message and exit. |
Stops the jobmgr on one or more hosts.
If no hosts are provided, then the command first stops the child hosts and then, after accounting for a shutdown delay, the master hosts.
If one or more hosts are provided, the stop command is sent to all hosts at the same time.
Usage: pas jobmgr kill [-h] [HOST [HOST ...]]
Use this option to specify one or more hosts on which this command has to be run.
| -h, --help | Show this help message and exit. |
Kills the jobmgr on one or more hosts. If no hosts are provided, the job managers are killed on all known hosts.
Usage: pas jobmgr start [-h]
| -h, --help | Show this help message and exit. |
Starts a new measure on all hosts and for each interface as defined in the INTERFACES and ROLES settings directives.
The measure is started in a detached named screen session to be able to disconnect from the remote host while letting the measure run. The same name can then also be used to cleanly stop or to kill the measure.
All existing measure files in the remote measure desintation directory will be erased without asking for confirmations! Make sure to have collected all previously run measures you don’t want to lose.
Note that it is not possible to run parallel measures (and it doesn’t make much sens, as both tshark process will capture all the traffic).
Usage: pas jobmgr stop [-h]
| -h, --help | Show this help message and exit. |
Stops the measures running on all hosts and for each interface as defined in the INTERFACES and ROLES settings directives.
The measures are stopped by sending the quit command to each named screen session which matches the MEASURE_NAME and interface couple.
Usage: pas measure kill [-h] [HOST [HOST ...]]
Use this option to specify one or more hosts on which this command has to be run.
| -h, --help | Show this help message and exit. |
Kills all the running measures on the given host (or on all hosts if no host is given) independently from the capturing interface or the name with which they were started.
Usage: pas measure collect [-h] MEASURE_NAME
The name to give to the collected measure.
| -h, --help | Show this help message and exit. |
Collects the results of a measure by copying the remote files resulting from the last run measure to the local measures folder and by organizing them by host ip address.
In addition to the measures, the log files specified by the LOG_FILES settings directive are also copied.
This process does not alter the remote files, it is thus possible to repeat a collect command different times until a new measure is not started.
Usage: pas report toxml [-h] [MEASURE]
The name of the collected measure to convert to xml.
| -h, --help | Show this help message and exit. |
Converts the results of an already collected measure from the libpcap format to the corresponding XML format using the tshark command line utility.
If MEASURE is not provided, the user is presented with a list of already collected measures and asked to make a choice.
Usage: pas report simplify [-h] [MEASURE]
The name of the collected measure to simplify.
| -h, --help | Show this help message and exit. |
Converts the results of an already collected and converted measure from the wireshark XML format to a simplified POP oriented XML format.
If MEASURE is not provided, the user is presented with a list of already collected measures and asked to make a choice.
Usage: pas report decode [-h] [MEASURE] [MEASURE_CASE]
The name of the collected measure to decode.
The name of the measure case from which this measure was run. This is needed to be able to use the additionally defined types for the measured binary.
| -h, --help | Show this help message and exit. |
Decodes the results of an already collected and simplified measure by annotating the XML structure with the needed POP metadata, as extracted from the TCP payload.
The decoding of additional custom types can be defined on a per-measure-case basis and is bast described in the parser DSL document.
If MEASURE is not provided, the user is presented with a list of already collected measures and asked to make a choice.
Usage: pas report report [-h] [MEASURE]
The name of the collected measure for which to generate a report.
| -h, --help | Show this help message and exit. |
Generates an HTML report for each already collected, converted, simplified and decoded measure files of the measure named MEASURE.
Usage: pas run [-h] [MEASURE_CASE] [TARGET [TARGET ...]]
The name of the measure case of which run the Makefile.
The target to execute, defaults to the default Makefile target.
| -h, --help | Show this help message and exit. |
Locally runs the given targets of the Makefile of the given measure case.
This command is useful to create custom commands by simply combining multiple togheter. Refer to the composing commands section for more informations about this argument.
The pas utility allows to define custom commands to extend the built-in set of commands. The process of creating a new command and adding it to the pas utility is described in detail in the Custom subcommands document.