This section introduces the list of commands available for the command line and the interactive shell.
General syntax
> rce --[RCE arguments] -[RCP arguments] -[VM arguments]
Table 3.10. Command line arguments for RCE
| Argument | Type | Description |
|---|---|---|
| profile "<profile id or path>" | RCE | Sets a custom profile folder to use. If only an id (any valid
directory name) is given, the profile directory "<user
home>/.rce/id" is used.
Alternatively, a full filesystem path can be specified. |
| profile | RCE | If the profile argument is specified without a profile id or path, RCE launches the Profile Selection UI, which allows to select a profile folder for the startup as described in Section 3.3.2, “Profile Selection UI”. |
| batch "<command string>" | RCE | Behaves like the "exec" command, but also implies the "--headless" option and always shuts down RCE after execution. |
| headless | RCE | Starts RCE in a headless modus without GUI. It will remain in the OSGi console and waits for user input. |
| exec "<command string>" | RCE |
Executes one or more shell commands defined by <command string>. For the list of available commands, refer to the command shell documentation. This argument is usually used together with --headless to run RCE in batch mode. Multiple commands can be chained within <command string> by separating them with " ; " (note the spaces); each command is completed before the next is started. You can use the " As an example, |
| configure | RCE | Starts the RCE Configuration UI (Section 2.2.3, “Configuration UI”) which can be used to configure SSH accounts with passphrases or to configure e-mail support for the RCE instance. |
| data @noDefault | RCP | Set the default workspace location to empty |
| consoleLog | RCP | Logs everything for log files on the console as well. |
| console | RCP | Runs RCE with an additional OSGi console window, which allows you to execute RCE shell commands. See the Command Shell documentation for more information. |
| Deprecated: console <port> | RCP | Specify the port that will be used to listen for telnet connections. (NOTE: this access is insecure; configure SSH access instead) |
| clean | RCP | Cleans before startup |
| vmargs | VM | Standard JVM arguments |
| Dde.rcenvironment.rce.configuration.dir=<insert-config-path> | VM | Sets the configuration directory |
| Drce.network.overrideNodeId =<some-id> | VM | Sets the local node id, overriding any stored value. This is mostly used for automated testing. Example: "-Drce.network.overrideNodeId=a96db8fa762d59f2d2782f3e5e9662d4" |
| Dcommunication.uploadBlockSize=<block size in bytes> | VM |
Sets the block size to use when uploading data to a remote node. This is useful for very slow connections (less than about 10 kb/s) to avoid timeouts. The default value is 262144 (256 kb). Example: "-Dcommunication.uploadBlockSize=131072" - sets the upload block size to 128kb (half the normal size) |
During startup of the instance, the Profile Selection UI allows to select a profile folder which should be used for the current run of RCE. Furthermore it allows to specify a default profile for future runs. You can access the Profile Selection UI by executing RCE from the command line with the option "rce --profile".
If the first option "Select a profile and start RCE" is chosen, a list of available profiles is presented. On selection of one of these profiles, RCE is started using this profile.
If the second option "Select the default profile for future runs" is chosen, a list of available profiles is presented. On selection of one of these profiles, RCE will not be started using this profile, but instead the selected profile will be marked as the default profile for future runs. This selection can be temporarily overwritten again by using the '-profile "<profile id or path>"' option. The default profile setting will be stored for the current user and the current installation location of RCE. Different users on the same machine can therefore configure different default profiles. Furthermore, different installations of RCE can have different default profiles configured.
The Profile Selection UI will only display profiles if they have been started once with RCE 7.0 or newer.
RCE provides an integrated shell (sometimes referred to as "console") for executing commands. It can be accessed in three different ways:
Start RCE with the "-console" command-line option, or add "-console" to the rce.ini file before starting; this will open an OSGi console window. Due to the nature of an OSGi console, all RCE commands must be prefixed with "rce". For example, type "rce help" to show the available commands.
Deprecated: Start RCE with the "-console <port>" command-line option; this will accept telnet OSGi console sessions on that port. As with the "-console" option, RCE commands must be prefixed with "rce" (for example, type "rce help").
Note that this option is insecure, as there is no authentication nor encryption, so it should only be used in fully trusted networks. Whenever possible, use the SSH console (see below) instead .
Configure SSH access. To do so, refer to Section Configuration Parameters. After RCE has started, you can access the shell on the configured port with a standard SSH client. On Windows systems, the "putty" software works well as a client.
As this option creates a pure RCE shell (as opposed to the OSGi consoles created above), you can enter RCE commands without a prefix - for example, just type "help" to list the available commands. Note that to avoid confusion, adding a "rce" prefix still works, but it is not necessary.
The following table lists some shell commands; more documentation coming soon.
Table 3.11. Shell Commands
| Argument | Description |
|---|---|
| help | Lists all available commands. |
| auth | Short form of "auth list". |
| auth create <group id> | Creates a new authorization group whith the given <group id> (an identifier consisting of 2-32 letters, numbers, underscores ("_") and/or brackets). |
| auth delete <group id> | Deletes the local authorization group with the given <group id>. |
| auth export <group id> | Exports the group with the given group id as an <invitation string> that can be imported by another node, allowing that other node to join this group. |
| auth import <invitation string> | Imports a group from an <invitation string> that was previously exported on another node. |
| auth list | Lists the authorization groups that the local node belongs to. |
| cn | Short form of "cn list". |
| cn add <target> ["<description>"] | Adds a new network connection. (Example: cn add activemq-tcp:rceserver.example.com:20001 "Our RCE Server") |
| cn list | Lists all network connections, including ids and connection states. |
| cn start <id> | Starts/Connects a READY or DISCONNECTED connection (use "cn list" to get the id). |
| cn stop <id> | Stops/Disconnects an ESTABLISHED connection (use "cn list" to get the id). |
| components | Short form of "components list". |
| components list [--local] [--as-table] | Lists components published by reachable RCE nodes. The "--local" option only lists components provided by the local node. The "--as-table" option formats the output as a table that is especially suited for automated parsing. |
| components list-auth | Shows a list of all defined authorization settings. Note that these settings are independent of whether a matching component exists, which means that settings are kept when a component is removed and later added again. |
| components set-auth <component id> <groups> | Assigns a list of authorization groups to a component id. Note that authorization
settings always apply to all components with using this id,
regardless of the component's version. The <component id> needs to be defined as listed by the "components list" command, e.g. "rce/Parametric Study", "common/MyIntegratedTool", or "cpacs/MyCpacsTool". This id must be enclosed in double quotes if it contains spaces. The <groups> to assign need to be provided as comma-separated list of user-defined authorization groups. This replaces any previously assigned groups. Note that the specified groups must have been created or imported beforehand; see the "auth create" and "auth import" commands for details. Instead of a list of groups, the special value "public" can be used to grant access to any user within the visible network, while "local" revokes any previously granted access by remote users. |
| mail <recipient> <subject> <body> |
Sends an email to the specified recipient. |
| net |
Short form of "net info". |
| net filter | Shows the status of the IP whitelist filter. |
| net filter reload | Reloads the IP whitelist configuration. |
| net info | Lists all reachable RCE nodes. |
| ra-admin list-wfs | Lists the ids of all published workflows. |
| ra-admin publish-wf [-g <group name>] [-k] [-t] [-p <JSON placeholder file>] <workflow file> <id> | Publishes a workflow file for remote execution via "ra run-wf"
using <id>. -g name of the group in which the workflow will be shown in the Palette on the client instance -k (keep execution data): if set, the workflow execution data will not be deleted after the workflow is run -t (temporary/transient): if set, the workflow is automatically unpublished when the RCE instance is shut down -p: adds a placeholder file for the given workflow; see the "wf run" command's documentation for details. This operation verifies that the workflow contains the required standard elements before publishing. Note that a snapshot of the workflow file (and optionally, the given placeholder file) is taken before publishing; subsequent changes of the workflow file do NOT affect the published workflow. |
| ra-admin unpublish-wf <id> | Unpublishes (removes) the workflow file with the given <id> from remote execution. |
| restart | Restarts RCE. |
| shutdown | Shuts down the local RCE instance. |
| ssh | Short form of "ssh list". |
| ssh add <displayName> <host> <port> <username> <keyfileLocation> | Adds a new ssh connection. |
| ssh list | Lists all ssh connections, including ids and connection states. |
| ssh start <id> | Starts/connects the ssh connection with the given <id> (use " ssh list" to get the id). |
| ssh stop <id> | Stops/disconnects the ssh connection with the given <id> (use " ssh list" to get the id). |
| stop | Shuts down the local RCE instance (alias of "shutdown"). |
| sysmon api <operation> | Fetches system monitoring data from all reachable nodes in the
network, and prints it in a parser-friendly format. Available operations: avgcpu+ram <time span> <time limit> - fetches the average CPU load over the given time span and the current free RAM. Operation parameters: time span - the maximum time span (in seconds) to aggregate load data over time limit - the maximum time (in milliseconds) to wait for each node's load data response. |
| sysmon local/-l | Prints system monitoring data for the local instance. |
| sysmon remote/-r | Fetches system monitoring data from all reachable nodes in the network, and prints it in a human-readable format. |
| version | Shows version information. |
| wf | Short form of "wf list" |
| wf list | Lists all current workflows, their states and execution ids. |
| wf cancel <workflow execution id> | Cancels a running or paused workflow. |
| wf delete <workflow execution id> | Deletes a finished, cancelled or failed workflow from the data management and disposes it. |
| wf details <workflow execution id> | Shows details about one workflow. |
| wf open <workflow execution id> | Opens a runtime viewer of a workflow. Requires GUI. When using SSH, this command is only available to users with the role developer. |
| wf pause <workflow execution id> | Pause a running workflow. |
| wf resume <workflow execution id> | Resume a paused workflow. |
| wf run [--delete <onfinished|always|never>] [--compact-output] [-p <placeholder value file>] <workflow file> |
Executes the given workflow file and waits until it has completed. Workflow file paths containing spaces must be enclosed in double quotes ("..."). The "--delete" option defines the deletion behavior after workflow completion. Deleting a workflow deletes all of its files in the data management and releases certain resources that may or may not be used after it has finished, for example data to be visualized in component's runtime views. The default of this setting is "onfinished": The workflow is deleted if it terminates in state "Finished" (which means normal completion without errors), otherwise it is left unchanged for inspection. The "--dispose" option defines the deletion behavior from the workflow list. Disposing a workflow does not delete its data from the data management. The default of this setting is "onfinished". The "--compact-output" option reduces this command's output as
much as possible, which is intended to simplify scripted calls
of this command. The first line printed will either be the
workflow's assigned id if the start was successful, or a text
starting with The "-p" option can be used to define a placeholder value file (see below). |
| wf verify [--delete <onfinished|always|never>] [--pr <parallel runs>] [--sr <serial runs>] [-p <placeholder value file>] --basedir <directory> <workflow file> [<workflow file> ...] | Runs several workflows and creates a summary of which ones failed and
succeeded. The "--pr" option defines how often the workflow is started in parallel. The "--sr" options defines how often the workflow is started in serial. E.g. "--pr 5 --sr 3" starts the workflow three times with five in parallel. If "*" is used with the "--basedir" option or multiple workflow filenames are passed, "--pr" and "--sr" are applied for each of the workflows. For the "--delete", "dispose" and "-p" options refer to "wf run" above. The "--basedir <directory>" parameter specifies the directory containing the workflow files. File paths containing spaces must be enclosed in double quotes ("..."). The second parameter defines the workflow's filenames. Using "*" as workflow file runs all non-backup workflows in the basedir. Workflow file paths containing spaces must be enclosed in double quotes ("..."). |
The command wf open is only accessible to the role developer, as it influences the GUI of the server-instance.
Some workflow components use placeholders for configuration values. The values for the placeholders are defined at workflow start. When executing workflows from the command line (e.g. in headless or batch mode), the placeholder's values must be defined in a file, which will be passed to the command with the -p option. Placeholder value files have following format:
{
<component id>/<component version> : {
<configuration placeholder id> : <configuration value>
}
<component id>/<component version>/<component instance name> :
{
<configuration placeholder id> : <configuration value>
}
}
Every id and every value must be in enclosed in double quotes ("...").
The component id is the id string of a component (e.g.
de.rcenvironment.script), the component version is the version of the
component that is used in the workflow (e.g. 3.4).
There are two ways of defining values for configuration placeholders: per component type and
per component instance. When defined per component type, the id and version must be
specified (e.g. "de.rcenvironment.script/3.4"). When defined per component instance
the component id, component version, and the name of the component in the workflow
must be specified (e.g. "de.rcenvironment.script/3.4/MyScript"). In both cases, the
configuration placeholder id, which is the name of the
configuration placeholder, and the actual configuration value must be
specified.
Component instance values override component type values.
It is possible to mix component type and component instance values.
Below is an example placeholder value file, which defines one placeholder value (component type) for the script component, one placeholer value (component type) for the input provider component and a placeholder value (component instance) for a specified input provider component of the workflow:
{
"de.rcenvironment.script/3.4": {
"pythonExecutionPath": "C:/Python/python.exe"
},
"de.rcenvironment.inputprovider/3.2": {
"inputFile": "C:/input/globalInputFile.txt"
},
"de.rcenvironment.inputprovider/3.2/Provider 1" : {
"inputFile": "C:/input/Provider1.txt"
}
}
The following table lists components and their configuration placeholders.
Table 3.12. Components and their configuration placeholders
| Component | Component id and version | Configuration placeholders |
|---|---|---|
| Cluster | de.rcenvironment.cluster/3.2 | authuser - user name authphrase - password (base64 encoded) |
| Input Provider | de.rcenvironment.inputprovider/3.2 | <output name> - value of output |
| Output Writer | de.rcenvironment.outputwriter/2.0 | targetRootFolder - path to target root folder |
| Script | de.rcenvironment.script/3.4 | pythonExecutionPath - path to the Python executable (only required if Python is set as script language) |