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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<meta http-equiv="Content-Language" content="en">
<title>File Output Module</title></head>
<body>
<a href="rsyslog_conf_modules.html">back</a>
<h1>File Output Module</h1>
<p><b>Module Name: omfile</b></p>
<p><b>Author: </b>Rainer Gerhards <rgergards@adiscon.com></p>
<p><b>Description</b>:</p>
<p>The omfile plug-in provides the core functionality of writing messages to files residing inside the local file system (which may actually be remote if methods like NFS are used). Both files named with static names as well files with names based on message content are supported by this module. It is a built-in module that does not need to be loaded. </p>
<p><b>Module Parameters</b>:</p>
<ul>
<li><strong>Template </strong>[templateName]<br>
Set the default template to be used if an action is not
configured to use a specific template.<br></li>
<li><strong>DirCreateMode </strong>[default 0700]<br>
Sets the default DirCreateMode to be used for an action
if no explicit one is specified.</br>
<li><strong>FileCreateMode </strong>[default 0644]<br>
Sets the default DirCreateMode to be used for an action
if no explicit one is specified.</br>
</ul>
<p> </p>
<p><b>Action Parameters</b>:</p>
<ul>
<li><strong>Template </strong>[templateName]<br>
Sets the template to be used for this action. If not specified, the
default template is applied.<br></li><br>
<li><strong>DynaFileCacheSize </strong>(not mandatory, default 10)<br>
Applies only if dynamic filenames are used.<br>
Specifies the number of DynaFiles that will be kept open. The default is
10. Note that this is a per-action value, so if you have multiple
dynafile actions, each of them have their individual caches (which means
the numbers sum up). Ideally, the cache size exactly matches the
need. You can use <a href="impstats.html">impstats</a> to tune this
value. Note that a too-low cache size can be a very considerable
performance bottleneck.<br></li><br>
<li><strong>ZipLevel </strong>0..9 [default 0]<br>
if greater 0, turns on gzip compression of the output file. The higher the number, the better the compression, but also the more CPU is required for zipping.<br></li><br>
<li><b>VeryRobustZip</b> [<b>on</b>/off] (v7.3.0+) - if ZipLevel is greater 0,
then this setting controls if extra headers are written to make the resulting file
extra hardened against malfunction. If set to off, data appended to previously unclean
closed files may not be accessible without extra tools.
Note that this risk is usually expected to be bearable, and thus "off" is the default mode.
The extra headers considerably
degrade compression, files with this option set to "on" may be four to five times as
large as files processed in "off" mode.
</li><br>
<li><strong>FlushInterval </strong>(not mandatory, default will be used)<br>
Defines, in seconds, the interval after which unwritten data is
flushed.<br></li><br>
<li><strong>ASyncWriting </strong>on/off [default off]<br>
if turned on, the files will be written in asynchronous mode via a separate thread. In that case, double buffers will be used so that one buffer can be filled while the other buffer is being written. Note that in order to enable FlushInterval, AsyncWriting must be set to "on". Otherwise, the flush interval will be ignored. Also note that when FlushOnTXEnd is "on" but AsyncWriting is off, output will only be written when the buffer is full. This may take several hours, or even require a rsyslog shutdown. However, a buffer flush can be forced in that case by sending rsyslogd a HUP signal. <br></li><br>
<li><strong>FlushOnTXEnd </strong>on/off [default on]<br>
Omfile has the capability to write output using a buffered writer. Disk writes are only done when the buffer is full. So if an error happens during that write, data is potentially lost. In cases where this is unacceptable, set FlushOnTXEnd to on. Then, data is written at the end of each transaction (for pre-v5 this means after each log message) and the usual error recovery thus can handle write errors without data loss. Note that this option severely reduces the effect of zip compression and should be switched to off for that use case. Note that the default -on- is primarily an aid to preserve the traditional syslogd behaviour.<br></li><br>
<li><strong>IOBufferSize </strong><size_nbr>, default 4k<br>
size of the buffer used to writing output data. The larger the buffer, the potentially better performance is. The default of 4k is quite conservative, it is useful to go up to 64k, and 128K if you used gzip compression (then, even higher sizes may make sense)<br></li><br>
<li><strong>DirOwner </strong><br>
Set the file owner for directories newly created. Please note that this setting does not affect the owner of directories already existing. The parameter is a user name, for which the userid is obtained by rsyslogd during startup processing. Interim changes to the user mapping are not detected.<br></li><br>
<li><strong>DirOwnerNum </strong> available in 7.5.8+ and 8.1.4+<br>
Set the file owner for directories newly created. Please note that this setting does not affect the owner of directories already existing. The parameter is a numerical ID, which is used regardless of whether the user actually exists. This can be useful if the user mapping is not available to rsyslog during startup.<br></li><br>
<li><strong>DirGroup </strong><br>
Set the group for directories newly created. Please note that this setting does not affect the group of directories already existing. The parameter is a group name, for which the groupid is obtained by rsyslogd on during startup processing. Interim changes to the user mapping are not detected.<br></li><br>
<li><strong>DirGroupNum </strong available in 7.5.8+ and 8.1.4+><br>
Set the group for directories newly created. Please note that this setting does not affect the group of directories already existing. The parameter is a numerical ID, which is used regardless of whether the group actually exists. This can be useful if the group mapping is not available to rsyslog during startup.<br></li><br>
<li><strong>FileOwner </strong><br>
Set the file owner for files newly created. Please note that this setting does not affect the owner of files already existing. The parameter is a user name, for which the userid is obtained by rsyslogd during startup processing. Interim changes to the user mapping are not detected.<br></li><br>
<li><strong>FileOwnerNum </strong> available in 7.5.8+ and 8.1.4+<br>
Set the file owner for files newly created. Please note that this setting does not affect the owner of files already existing. The parameter is a numerical ID, which which is used regardless of whether the user actually exists. This can be useful if the user mapping is not available to rsyslog during startup.<br></li><br>
<li><strong>FileGroup </strong><br>
Set the group for files newly created. Please note that this setting does not affect the group of files already existing. The parameter is a group name, for which the groupid is obtained by rsyslogd during startup processing. Interim changes to the user mapping are not detected.<br></li><br>
<li><strong>FileGroupNum </strong> available in 7.5.8+ and 8.1.4+<br>
Set the group for files newly created. Please note that this setting does not affect the group of files already existing. The parameter is a numerical ID, which is used regardless of whether the group actually exists. This can be useful if the group mapping is not available to rsyslog during startup.<br></li><br>
<li><strong>FileCreateMode </strong>[default equelly-named module parameter]<br>
The FileCreateMode directive allows to specify the creation mode with which rsyslogd creates new files. If not specified, the value 0644 is used (which retains backward-compatibility with earlier releases). The value given must always be a 4-digit octal number, with the initial digit being zero. <br>Please note that the actual permission depend on rsyslogd's process umask. If in doubt, use "$umask 0000" right at the beginning of the configuration file to remove any restrictions. <br>FileCreateMode may be specified multiple times. If so, it specifies the creation mode for all selector lines that follow until the next $FileCreateMode directive. Order of lines is vitally important.<br></li><br>
<li><strong>DirCreateMode </strong>[default equelly-named module parameter]<br>
This is the same as FileCreateMode, but for directories automatically generated.<br></li><br>
<li><strong>FailOnCHOwnFailure </strong>on/off [default on]<br>
This option modifies behaviour of file creation. If different owners or groups are specified for new files or directories and rsyslogd fails to set these new owners or groups, it will log an error and NOT write to the file in question if that option is set to "on". If it is set to "off", the error will be ignored and processing continues. Keep in mind, that the files in this case may be (in)accessible by people who should not have permission. The default is "on".<br></li><br>
<li><strong>CreateDirs </strong>on/off [default on]<br>
create directories on an as-needed basis<br></li><br>
<li><strong>Sync </strong>on/off [default off]<br>
enables file syncing capability of omfile. Note that this causes
an enormous performance hit if enabled.<br></li><br>
<li><strong>File </strong><br>
If the file already exists, new data is appended to it. Existing data is not truncated. If the file does not already exist, it is created. Files are kept open as long as rsyslogd is active. This conflicts with external log file rotation. In order to close a file after rotation, send rsyslogd a HUP signal after the file has been rotated away. <br></li><br>
<li><strong>DynaFile </strong><br>
For each message, the file name is generated based on the given template. Then, this file is opened. As with the ``file'' property, data is appended if the file already exists. If the file does not exist, a new file is created. A cache of recent files is kept. Note that this cache can consume quite some memory (especially if large buffer sizes are used). Files are kept open as long as they stay inside the cache. Currently, files are only evicted from the cache when there is need to do so (due to insufficient cache size). To force-close (and evict) a dynafile from cache, send a HUP signal to rsyslogd. <br></li><br>
<li><b>Sig.Provider </b>[ProviderName]<br>
Selects a signature provider for log signing. Currently,
there only is one provider called
"<a href="sigprov_gt.html">gt</a>".<br></li><br>
<li><b>Cry.Provider </b>[ProviderName]<br>
Selects a crypto provider for log encryption. Currently,
there only is one provider called
"<a href="cryprov_gcry.html">gcry</a>".<br></li><br>
</ul>
<p><b>See Also</b>
<ul>
<li><a href="http://www.rsyslog.com/how-to-sign-log-messages-through-signature-provider-guardtime/">Sign log messages through signature provider Guardtime</a></li>
</ul>
</p>
<p><b>Caveats/Known Bugs:</b></p>
<ul>
<li>One needs to be careful with log rotation if signatures and/or encryption
are being used. These create side-files, which form a set and must be kept
together.
<br>
For signatures, the ".sigstate" file must NOT be rotated away if
signature chains are to be build across multiple files. This is because
.sigstate contains just global information for the whole file set. However,
all other files need to be rotated together. The proper sequence is to
<ol>
<li> move all files inside the file set
<li> only AFTER this is completely done, HUP rsyslog
</ol>
This sequence will ensure that all files inside the set are atomically
closed and in sync. HUPing only after a subset of files have been moved
results in inconsistencies and will most probably render the file set
unusable.
</li>
</ul>
<p><b>Sample:</b></p>
<p>The following command writes all syslog messages into a file.</p>
<textarea rows="5" cols="60">action(type="omfile"
DirCreateMode="0700"
FileCreateMode="0644"
File="/var/log/messages")
</textarea>
<br><br>
<p><b>Legacy Configuration Directives</b>:</p>
<ul>
<li><strong>$DynaFileCacheSize </strong><br>
equivalent to the "dynaFileCacheSize" parameter<br></li><br>
<li><strong>$OMFileZipLevel </strong><br>
equivalent to the "zipLevel" parameter<br></li><br>
<li><strong>$OMFileFlushInterval </strong><br>
equivalent to the "flushInterval" parameter<br></li><br>
<li><strong>$OMFileASyncWriting </strong><br>
equivalent to the "asyncWriting" parameter<br></li><br>
<li><strong>$OMFileFlushOnTXEnd </strong><br>
equivalent to the "flushOnTXEnd" parameter<br></li><br>
<li><strong>$OMFileIOBufferSize </strong><br>
equivalent to the "IOBufferSize" parameter<br></li><br>
<li><strong>$DirOwner </strong><br>
equivalent to the "dirOwner" parameter<br></li><br>
<li><strong>$DirGroup </strong><br>
equivalent to the "dirGroup" parameter<br></li><br>
<li><strong>$FileOwner </strong><br>
equivalent to the "fileOwner" parameter<br></li><br>
<li><strong>$FileGroup </strong><br>
equivalent to the "fileGroup" parameter<br></li><br>
<li><strong>$DirCreateMode </strong><br>
equivalent to the "dirCreateMode" parameter<br></li><br>
<li><strong>$FileCreateMode </strong><br>
equivalent to the "fileCreateMode" parameter<br></li><br>
<li><strong>$FailOnCHOwnFailure </strong><br>
equivalent to the "failOnChOwnFailure" parameter<br></li><br>
<li><strong>$F$OMFileForceCHOwn </strong><br>
equivalent to the "ForceChOwn" parameter<br></li><br>
<li><strong>$CreateDirs </strong><br>
equivalent to the "createDirs" parameter<br></li><br>
<li><strong>$ActionFileEnableSync </strong><br>
equivalent to the "enableSync" parameter<br></li><br>
<li><strong>$ActionFileDefaultTemplate </strong><br>
equivalent to the "template" module parameter<br></li><br>
<li><strong>$ResetConfigVariables </strong><br>
Resets all configuration variables to their default value.<br></li><br>
</ul>
<p><b>Legacy Sample:</b></p>
<p>The following command writes all syslog messages into a file.</p>
<textarea rows="5" cols="60">$ModLoad omfile
$DirCreateMode 0700
$FileCreateMode 0644
*.* /var/log/messages
</textarea>
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>] [<a href="manual.html">manual
index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
Copyright © 2008-2013 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
version 3 or higher.</font></p>
</body></html>
|
