3.3. Commands

This section introduces the list of commands available for the command line and the interactive shell.

3.3.1. Command Line Parameters

General syntax

>  rce --[RCE arguments] -[RCP arguments] -[VM arguments]

Table 3.10. Command line arguments for RCE

ArgumentTypeDescription
profile "<profile id or path>"RCESets 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.
profileRCEIf 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>"RCEBehaves like the "exec" command, but also implies the "--headless" option and always shuts down RCE after execution.
headlessRCEStarts 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 "stop" command at the end of the command sequence to shut down RCE after the other commands have been executed. However, any error during execution of these commands will cancel the sequence, and prevent the "stop" command from being executed. To ensure shut down at the end of the command sequence, use the --batch option instead of "--exec".

As an example, rce --headless --exec "wf run example.wf ; stop" will execute the "example.wf" workflow in headless mode and then shut down RCE. However, if the workflow fails to start, RCE will keep running, as the "stop" command is never executed. To attempt execution of the workflow file, but then always shut down regardless of the outcome, use rce --batch "wf run example.wf" instead.

configureRCEStarts 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 RCPSet the default workspace location to empty
consoleLog RCPLogs everything for log files on the console as well.
consoleRCPRuns 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>RCPSpecify the port that will be used to listen for telnet connections. (NOTE: this access is insecure; configure SSH access instead)
clean RCPCleans before startup
vmargsVMStandard JVM arguments
Dde.rcenvironment.rce.configuration.dir=<insert-config-path>VMSets 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)


3.3.2. Profile Selection UI

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".

Figure 3.6. Profile Selection UI

Profile Selection UI

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.

Note

The Profile Selection UI will only display profiles if they have been started once with RCE 7.0 or newer.

3.3.3. Command Shell

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

ArgumentDescription
helpLists all available commands.
authShort 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 listLists 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 listLists 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).
componentsShort 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-authShows 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 filterShows the status of the IP whitelist filter.
net filter reloadReloads the IP whitelist configuration.
net infoLists all reachable RCE nodes.
ra-admin list-wfsLists 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.
shutdownShuts down the local RCE instance.
sshShort form of "ssh list".
ssh add <displayName> <host> <port> <username> <keyfileLocation>Adds a new ssh connection.
ssh listLists 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).
stopShuts 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/-lPrints system monitoring data for the local instance.
sysmon remote/-rFetches system monitoring data from all reachable nodes in the network, and prints it in a human-readable format.
versionShows version information.
wfShort form of "wf list"
wf listLists 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 "Error " if the workflow could not be started. If (and only if) the start was successful, a second line will be printed once the workflow has terminated. The pattern of this second line is "<workflow id>: <final state>".

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 ("...").


3.3.3.1. Configuration Placeholder Value Files

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>

}

}

Note

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.

Note

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

ComponentComponent id and versionConfiguration placeholders
Clusterde.rcenvironment.cluster/3.2

authuser - user name

authphrase - password (base64 encoded)

Input Providerde.rcenvironment.inputprovider/3.2

<output name> - value of output

Output Writerde.rcenvironment.outputwriter/2.0targetRootFolder - path to target root folder
Scriptde.rcenvironment.script/3.4pythonExecutionPath - path to the Python executable (only required if Python is set as script language)