1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
****************************************
improg: Program integration input module
****************************************
================ ==============================================================
**Module Name:** **improg**
**Authors:** Jean-Philippe Hilaire <jean-philippe.hilaire@pmu.fr> & Philippe Duveau <philippe.duveau@free.fr>
================ ==============================================================
Purpose
=======
This module allows rsyslog to spawn external command(s) and consume message
from pipe(s) (stdout of the external process).
**Limitation:** `select()` seems not to support usage of `printf(...)` or
`fprintf(stdout,...)`. Only `write(STDOUT_FILENO,...)` seems to be efficient.
The imput module consume pipes form all external programs in a mono-threaded
`runInput` method. This means that data treatments will be serialized.
Optionally, the module manage the external program through keyword sent to
it using a second pipe to stdin of the external process.
An operational sample in C can be found @ "github.com/pduveau/jsonperfmon"
Also a bash's script is provided as tests/improg-simul.sh. The `echo` and `read` (built-in) can be used to communicate with the module.
External commands can not be used to communicate. `printf` is unable to send data directly to the module but can used through a variable and `echo`.
Compile
=======
To successfully compile improg module.
./configure --enable-improg ...
Configuration Parameters
========================
Action Parameters
-----------------
Binary
^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"string", "yes", "command arguments...",
Command line : external program and arguments
Tag
^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"string", "yes", ,"none"
The tag to be assigned to messages read from this file. If you would like to
see the colon after the tag, you need to include it when you assign a tag
value, like so: ``tag="myTagValue:"``.
Facility
^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"string", "no", "facility\|number", "local0"
The syslog facility to be assigned to messages read from this file. Can be
specified in textual form (e.g. ``local0``, ``local1``, ...) or as numbers (e.g.
16 for ``local0``). Textual form is suggested.
Severity
^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"string", "no", "severity\|number", "notice"
The syslog severity to be assigned to lines read. Can be specified
in textual form (e.g. ``info``, ``warning``, ...) or as numbers (e.g. 6
for ``info``). Textual form is suggested.
confirmMessages
^^^^^^^^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"binary", "no", "on\|off", "on"
Specifies whether the external program needs feedback from rsyslog via stdin.
When this switch is set to "on", rsyslog confirms each received message.
This feature facilitates error handling: instead of having to implement a retry
logic, the external program can rely on the rsyslog queueing capabilities.
The program receives a line with the word ``ACK`` from its standard input.
Also, the program receives a ``STOP`` when rsyslog ask the module to stop.
signalOnClose
^^^^^^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"binary", "no", "on\|off", "off"
Specifies whether a TERM signal must be sent to the external program before
closing it (when either the worker thread has been unscheduled, a restart
of the program is being forced, or rsyslog is about to shutdown).
closeTimeout
^^^^^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"number", "no", ,"200"
Specifies whether a KILL signal must be sent to the external program in case
it does not terminate within the timeout indicated by closeTimeout_
(when either the worker thread has been unscheduled, a restart of the program
is being forced, or rsyslog is about to shutdown).
killUnresponsive
^^^^^^^^^^^^^^^^
.. csv-table::
:header: "type", "mandatory", "format", "default"
:widths: auto
:class: parameter-table
"binary", "no", "on\|off", "on"
Specifies whether a KILL signal must be sent to the external program in case
it does not terminate within the timeout indicated by closeTimeout
(when either the worker thread has been unscheduled, a restart of the program
is being forced, or rsyslog is about to shutdown).
Stop sequence
=============
1. If `confirmMessages` is set to on, a `STOP` is written in stdin of the child.
2. If `signalOnClose` is set to "on", a TERM signal is sent to the child.
3. The pipes with the child process are closed (the child will receive EOF on stdin),
4. Then, rsyslog waits for the child process to terminate during closeTimeout,
5. If the child has not terminated within the timeout, a KILL signal is sent to it.
|
