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.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.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. |
| components | Short form of "components list". |
| components list | Lists components published by reachable RCE nodes. |
| 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). |
| 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. |
| restart | Restarts RCE. |
| shutdown | Shuts down the local RCE instance. |
| stop | Shuts down the local RCE instance (alias of "shutdown"). |
| version | Shows version information. |
| wf | Short form of "wf list" |
| wf list | Lists all current workflows, their states and execution ids. |
| wf details <workflow execution id> | Shows details about one workflow. |
| 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 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 files in the data management of it 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 "--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" 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 ("..."). |
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) |