4. Modules¶
Table of Contents
The following sections detail the types of modules supported.
4.1. Config modules¶
All config modules are of schedule type config
, which means that they are executed once on bitd-agent
start, and are execute again each time the bitd-agent
is reloading its configuration (for example, because it received a Unix SIGHUP
signal, or because the bitd-agent
is running under systemd
control and the following command was executed: systemd reload bitd
).
4.1.1. bitd-config-log¶
The bitd-config-log` module controls the bitd-agent
log level. It is configured through the following input
parameters:
log-level
, which controls the global log level. The syntax of thelog-level
is:
log-level: none|crit|error|info|warn|debug|trace
log-key
, which can be specified multiple times, and controls a subsystem log level. The syntax of thelog-key
entry is:
log-key:
key-name: <key name>
log-level: none|crit|error|info|warn|debug|trace
Here is an example config-log
configuration:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | modules:
module-name: bitd-config-log
task-inst:
task-name: config-log
task-inst-name: Config log task instance
schedule:
type: config
input:
log-level: info
log-key:
key-name: module-mgr
log-level: trace
log-key:
key-name: module-agent
log-level: none
|
This will set the module-mgr
subsystem log level to trace
, the module-agent
subsystem log level to none
(disabling that subsystem log), and the global log level for all other log messages to info
.
4.2. Run modules¶
All run modules can execute periodically (with fixed or random start time), or can execute once.
4.2.1. bitd-echo module¶
The bitd-echo
module supports the echo
task.
4.2.1.1. echo task¶
The echo
task echoes back its args
as output
. If args
is void, it will instead echo back its input
as output
. Here is an example configuration:
1 2 3 4 5 6 7 8 9 10 11 | modules:
module-name: bitd-echo
task-inst:
task-name: echo
task-inst-name: Echo task instance
schedule:
type: periodic
interval: 1s
args:
name-int64: -128
name-int64: 127
|
Here is the bitd-agent
result output:
1 2 3 4 5 6 7 8 9 10 11 12 13 | $ bitd-agent -c echo.yml
---
tags:
task: echo
task-instance: Echo task instance
run-id: 0
run-timestamp: 1539717016893523079
exit-code: 0
output:
name-int64: -128
name-int64: 127
---
^C...
|
The same output will be displayed if the configuration is changed to replace args
with input
:
1 2 3 4 5 6 7 8 9 10 11 | modules:
module-name: bitd-echo
task-inst:
task-name: echo
task-inst-name: Echo task instance
schedule:
type: periodic
interval: 1s
input:
name-int64: -128
name-int64: 127
|
If both args
and input
are specified, only args
is echoed back as output
.
4.2.2. bitd-exec module¶
The bitd-exec
module supports the exec
task.
4.2.2.1. exec task¶
The exec
task spawns a child process and reports as results its exit code, its stdout
and stderr
. The following parameters can be configured:
args
holds the following subparameters:command
holds the executable command name and arguments. The command name and the arguments are space separated. This parameter is required.command-tmo
holds the maximum duration, in seconds, of the child process. If the child process does not exit within the configuredcommand-tmo
, it is terminated. This parameter is optional, and can be useful to set a limit to the run duration of the child process.input-type: {auto, string, blob, json, xml, yaml}
configures whether theinput
parameter is formatted as string, blob, json, xml or yaml before being passed asstdin
to the child process. If configured asauto
, theinput
will be formatted asyaml
, except ifinput
is ofblob
type, in which case it is formatted as blob. The default value of the parameter isauto
.output-type: {auto, string, blob, json, xml, yaml}
configures whether thestdout
is parsed as string, blob, json, xml or yaml. If configured asauto
, thestdout
is checked, in order, forjson
,xml
,yaml
,string
content, and is displayed respectively asjson
,xml
,yaml
,string
, or, if none of the above applies, asblob
. The default value of the parameter isauto
.The output is considered to be
json
,xml
oryaml
if thejson
,xml
, respectively theyaml
parser encounters no error. It is considered to bestring
format if it contains noNULL
characters aside from theNULL
termination.error-type: {auto, string, blob, json, xml, yaml}
configures whether thestderr
is parsed asstring
,blob
,json
,xml
oryaml
. If configured asauto
, thestderr
is checked, in order, forjson
,xml
,yaml
,string
content, and is displayed respectively asxml
,yaml
,string
, or, if none of the above applies, asblob
. The default value of the parameter isauto
.
The
input
parameter is passed as standard input to the child process. The format of thestdin
buffer is determined by theargs.input-type
parameter.
The task instance tags
are passed down to the child process as environment variables. Recall that tags
can be task instance scoped, module scoped, or globally scoped at the level of the configuration file. Tags from all three scopes are merged together, with module scope tags taking precedence over global scoped tags, and task instance scoped tags taking precedence over module scope tags.
The shell child process will have an exit code, and will output stdout
and stderr
:
- The exit code is reported back as the
exit-code
result. - The
stdout
is reported back as theoutput
result. Theargs.output-type
parameter controls howstdout
is parsed. - The
stderr
is reported back as theerror
result. Theargs.error-type
parameter controls howstdout
is parsed.
The shell command is specified by the command
subparameter of args
:
1 2 3 4 5 6 7 8 9 10 | modules:
module-name: bitd-exec
task-inst:
task-name: exec
task-inst-name: Exec task instance
schedule:
type: periodic
interval: 1s
args:
command: echo hi
|
Here is the output of this configuration file:
1 2 3 4 5 6 7 8 9 10 11 | $ bitd-agent -c exec.yml
---
tags:
task: echo
task-instance: Exec task instance
run-id: 0
run-timestamp: 1539717825481153340
exit-code: 0
output: hi
---
^C...
|
Here is an example with output sent both to stdout
and stderr
, and with a non-zero exit code:
1 2 3 4 5 6 7 8 9 10 | modules:
module-name: bitd-exec
task-inst:
task-name: exec
task-inst-name: Exec task instance
schedule:
type: periodic
interval: 1s
args:
command: echo hi; echo ho >&2; exit 3
|
And the output is:
1 2 3 4 5 6 7 8 9 10 11 12 | $ bitd-agent -c exec.yml
---
tags:
task: echo
task-instance: Exec task instance
run-id: 0
run-timestamp: 1539718218405943930
exit-code: 3
output: hi
error: ho
---
^C...
|