$darkmode
Elektra 0.11.0
Plugin: process

This plugin spawns a new process with a user-defined executable and delegates all operations to the new process.

Usage

Set the config key executable and the arrays args/#, env/# to the path of an executable, the arguments that shall be passed and the environment variables to be set.

1 kdb mount test.dump /tests/process process 'executable=/usr/bin/pluginproc' 'args=#1' 'args/#0=--load-plugin' 'args/#1=myplugin'

During elektraStdprocioOpen the plugin will collect the args/# and env/# values into two arrays argv and envp. Additionally, the array copyenv/# is read as a list of environment variables. Each variable will be looked up via getenv and then added to envp.

The plugin then forks a new process and the child calls execve with the path from app as well as argv andenvp. The child process is expected to listen to stdin and write to stdout according to the protocol described below.

If communication can be established, the child process will be kept running until elektraStdprocioClose.

Protocol

The entire protocol is text-based (apart from binary key values) and request-response-based, and happens over stdin/stdout. The parent process sends request to the child process. The child then processes the request and sends a response back.

To encode keysets and keys we use the format of the dump plugin. It is important to note that the dump plugin is instructed to write the full keynames (normally it removes the parent prefix). There is, however, an exception during initialization, which is described in the appropriate section. The child process may also delegate directly to the dump plugin, or reimplement the encoding.

The communications protocol used by the plugin has 3 phases:

Note: In the sections below we use the following format to describe messages:

1 Parent > Child
2 
3 HELLO WORLD
4 [users]
5 (user)
6 {ok|error}

This denotes a message sent from parent to child, containing

  • the literal text HELLO WORLD
  • followed by a newline
  • followed by a keyset called users
  • followed by a newline
  • followed by dynamic text called user
  • followed by either the literal text ok or the literal text error

The names users and user don't actually appear in the message. They are only used as a reference for the descriptions of the message.

The actual message sent could look like this:

1 HELLO WORLD
2 kdbOpen 2
3 $key string 3 5
4 joe
5 12345
6 $end
7 appleseed

Initialization

The parent writes the protocol header to stdin of the child.

1 Parent > Child
2 
3 ELEKTRA_PROCESS INIT v1

The child must respond with an acknowledgement, followed by a contract keyset.

1 Child > Parent
2 
3 ELEKTRA_PROCESS ACK v1
4 (name)
5 [contract]

Here (name) is the module name the child uses. This will be used to replace process in the contract of the plugin. The [contract] keyset must contain the infos keys, which will be used replace the ones at the top of this README and the ones in process.c. It must also contain exports/_ keys for every operation that is implemented by the child. All keys in [contract] should be below system:/elektra/modules/process. The parent will rename these keys appropriately.

A child that implements all operations should include these keys (in addition to the relevant infos keys):

1 system:/elektra/modules/process/exports/open = 1
2 system:/elektra/modules/process/exports/close = 1
3 system:/elektra/modules/process/exports/get = 1
4 system:/elektra/modules/process/exports/set = 1

After this initial handshake, the child should simply wait for further requests from the parent.

Note: Under normal circumstances this handshake will always be followed by an open request immediately.

Operation

When the parent needs the child to process an operation (open, get, ...), it will send a request like this:

1 Parent > Child
2 
3 {open|get|set|close}
4 [parent]
5 [data]

First we send the opname (one of open, get, set or close) of the operation that shall be performed by the child. The keyset [parent] always consists of a single key, namely the parentKey (or errorKey) that was passed to the plugin. Finally, [data] is the keyset that was passed to the plugin. The [data] keyset is not present in open and close operations, since those don't receive a KeySet in the C API. However, in the open operation [data] is replaced [config] which is the KeySet returned by elektraPluginGetConfig in the C API. This is needed, because the child process cannot request the config keyset otherwise.

The child should then perform the requested operation and respond with

1 Child > Parent
2 
3 {success|noupdate|error}
4 [parent]
5 [returned]

Here (result) is one of success, noupdate and error, which correspond to ELEKTRA_PLUGIN_STATUS_SUCCESS, ELEKTRA_PLUGIN_STATUS_NO_UPDATE and ELEKTRA_PLUGIN_STATUS_ERROR respectively. The keysets [parent] and [returned] are the modified versions of the one sent by the parent.

Termination

When the parent no longer needs the child process, it will send a final termination request.

1 Parent > Child
2 
3 ELEKTRA_PROCESS TERMINATE

The child process should now exit (and thereby close its ends of the stdin/stdout pipes).

Note: Under normal circumstances this only happens, when plugin is being closed, i.e. during a elektraPluginClose call for a process instance.

Errors

If an unexpected error occurs on either side of the protocol, the connection should be terminated and the child process shall exit.

Examples

1 # mount the Whitelist Java Plugin via process
2 # NOTE: the copyenv and copyenv/#0 are normal not needed, but we need them to make this script work as an automated test
3 sudo kdb mount config.file user:/tests/process dump process 'executable=/usr/bin/java' 'args=#3' 'args/#0=-cp' "args/#1=$BUILD_DIR/src/bindings/jna/plugins/whitelist/build/libs/whitelist-$(kdb --version | sed -nE 's/KDB_VERSION: (.+)/\1/gp')-all.jar" 'args/#2=org.libelektra.process.PluginProcess' 'args/#3=org.libelektra.plugin.WhitelistPlugin' 'copyenv=#0' "copyenv/#0=LD_LIBRARY_PATH"
4 
5 # Define whitelist
6 kdb meta-set user:/tests/process/key "check/whitelist/#0" ""
7 kdb meta-set user:/tests/process/key "check/whitelist/#1" allowed0
8 kdb meta-set user:/tests/process/key "check/whitelist/#2" allowed1
9 
10 # Should be allowed
11 kdb set user:/tests/process/key allowed0
12 #> Set string to "allowed0"
13 
14 kdb set user:/tests/process/key allowed1
15 #> Set string to "allowed1"
16 
17 # Should cause error
18 kdb set user:/tests/process/key not_allowed
19 # RET: 5
20 # STDERR:.*Validation Semantic: .*'not_allowed' does not adhere to whitelist.*
21 
22 # cleanup
23 kdb rm -r user:/tests/process
24 sudo kdb umount user:/tests/process

Note: The mount line of the snippet above can be simplified by using the mount-java helper:

1 sudo kdb mount-java config.file user:/tests/process dump java:org.libelektra.plugin.WhitelistPlugin

Limitations