Process Agent¶
IoT-LAB MQTT process agent¶
Process agent allows running and managing processes.
Process agent base topic:
{prefix}/iot-lab/process/{site}
Every topics from process agent topics start by this topic prefix
| param prefix: | configured prefix |
|---|---|
| param site: | site where the agent is run |
Note
iot-lab/process/{site} part can be replaced with the --agenttopic
option to allow running it on other servers than IoT-LAB.
Topics Summary¶
| Topic | Type | |
|---|---|---|
| Process agent | ||
{prefix}/iot-lab/process/{site} |
||
{processagenttopic}/error/ |
Error | |
| Process ids management | ||
{processagenttopic}/ctl/new |
Request | |
{processagenttopic}/ctl/free |
Request | |
{processagenttopic}/ctl/list |
Request | |
| Process control | ||
{processagenttopic}/process/{procid}/ctl/run |
Request | |
{processagenttopic}/process/{procid}/ctl/poll |
Request | |
{processagenttopic}/process/{procid}/ctl/kill |
Request | |
{processagenttopic}/process/{procid}/ctl/rerun |
Request | |
| Process file descriptors | ||
{processagenttopic}/process/{procid}/fd/stdin |
Input | |
{processagenttopic}/process/{procid}/fd/stdout |
Output | |
{processagenttopic}/process/{procid}/fd/stderr |
Output | |
| Process events | ||
{processagenttopic}/process/{procid}/event/returncode |
Output | |
Process Agent global topics¶
Error Topic¶
Asynchronous error messages are posted to error topic. Failure on requests are not duplicated here.
{processagenttopic}/error/
For format see: Error topic
Process ids management topics¶
To run a process, a process id should first be allocated. This id will be used for every commands on the process.
Note
Seperating this from the procrun command allows registering first to
all interesting topics (e.g. fd/stdout, event/returncode) so no
messages are missed.
New process id¶
Allocate a new process id, if a procid is given it will use this one or
if empty, an uniq integer one will be provided.
Process ids will either be the provided ones, or a string representation of integers.
| param procid: | procid can be given or empty to get an uniq int one.
An error is returned if given one is already used.
It cannot contain {}/+#. |
|---|---|
| type procid: | utf-8 encoded string |
| returns: | utf-8 allocated procid, which is either the given one or
an int string.
If message does not match above rules, its an error message. |
new request: |
||
|---|---|---|
| Topic: | {processagenttopic}/ctl/new |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | empty or procid |
| Reply | {topic}/reply/{clientid}/{requestid} | procid or error_msg |
Free process id¶
Free given process id. Process should be idle.
| param procid: | utf-8 procid to release |
|---|---|
| type procid: | utf-8 encoded string |
free request: |
||
|---|---|---|
| Topic: | {processagenttopic}/ctl/free |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | procid |
| Reply | {topic}/reply/{clientid}/{requestid} | empty or error_msg |
List processes ids¶
List processes ids.
| returns: | utf-8 encoded json list of ids |
|---|
list request: |
||
|---|---|---|
| Topic: | {processagenttopic}/ctl/list |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | empty |
| Reply | {topic}/reply/{clientid}/{requestid} | utf-8 json list |
Process control¶
Control process execution.
Process run¶
Run given command for given process id. The process should currently be idle.
| param command: | utf-8 encoded json list of arguments |
|---|
Warning
Care should be taken when running an infinite running process with sudo as it cannot be killed by its original user. Read more
run request: |
||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid}/ctl/run |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | command |
| Reply | {topic}/reply/{clientid}/{requestid} | empty or error_msg |
Process poll¶
Check if given process is still running. If stopped, it returns returncode else an empty message.
| returns: | empty if running, returncode int string if stopped or
an error message. |
|---|
poll request: |
||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid}/ctl/poll |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | empty |
| Reply | {topic}/reply/{clientid}/{requestid} | empty or
returncode or
error_msg |
Process kill¶
Kill given process.
Note
A SIGTERM is first sent, then a SIGKILL one second after if still running.
kill request: |
||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid}/ctl/kill |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | empty |
| Reply | {topic}/reply/{clientid}/{requestid} | empty or error_msg |
Process rerun¶
Re-run given process with the same command. The process should currently be idle.
rerun request: |
||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid}/ctl/rerun |
|
| Message | Topic | Payload |
| Request | {topic}/request/{clientid}/{requestid} | empty |
| Reply | {topic}/reply/{clientid}/{requestid} | empty or error_msg |
Process file descriptors¶
Process standard input, output and error topics. They transport raw data to allow exchanging everything with the application.
This implies that messages may not be utf-8 data,
or not seperated on new lines characters or even split in the middle of
an utf-8 code-point.
Sent messages are only empty on process termination,
where fd/stdout and fd/stderr receive a final empty message.
During normal execution output messages are never empty.
| Process file descriptors | ||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid} |
|
| Message | Topic | Payload |
| Input | fd/stdin |
RAW bytes |
| Output | fd/stdout |
RAW bytes |
| Output | fd/stderr |
RAW bytes |
Process events¶
Sends process returncode as a int string on process termination.
| Events file descriptors | ||
|---|---|---|
| Topic: | {processagenttopic}/process/{procid} |
|
| Message | Topic | Payload |
| Output | event/returncode |
returncode string |