~ubuntu-branches/ubuntu/lucid/rsyslog/lucid : revision 1

1

<html>

2

<head>

3

<title>rsyslog.conf file</title>

4

</head>

5

<body>

6

<h1>rsyslog.conf configuration file</h1>

7

This document is currently being enhanced. Please pardon its current

8

appearance.

9

Rsyslogd is configured via the rsyslog.conf file, typically found in

10

/etc. By default, rsyslogd reads the file /etc/rsyslog.conf. This may be changed

11

by a command line option.

12

13

Configuration file examples can be found in the rsyslog wiki</a>.

14

While rsyslogd contains enhancements over standard syslogd, efforts have been

15

made to keep the configuration file as compatible as possible. While, for

16

obvious reasons, <a href="features.html">enhanced features</a> require a

17

different config file syntax, rsyslogd should be able to work with a standard

18

syslog.conf file. This is especially useful while you are migrating from syslogd

19

to rsyslogd.

20

<h2>Global Directives</h2>

21

All global directives need to be specified on a line by their own and must

22

start with a dollar-sign. Here is a list in alphabetical order. Follow links for

23

a description.

24

<ul>

25

<li><a href="rsconf1_actionexeconlyifpreviousissuspended.html">$ActionExecOnlyIfPreviousIsSuspended</a></li>

26

<li><a href="rsconf1_actionresumeinterval.html">$ActionResumeInterval</a></li>

27

<li><a href="rsconf1_allowedsender.html">$AllowedSender</a></li>

28

<li><a href="rsconf1_controlcharacterescapeprefix.html">$ControlCharacterEscapePrefix</a></li>

29

<li><a href="rsconf1_debugprintcfsyslinehandlerlist.html">$DebugPrintCFSyslineHandlerList</a></li>

30

<li><a href="rsconf1_debugprintmodulelist.html">$DebugPrintModuleList</a></li>

31

<li><a href="rsconf1_debugprinttemplatelist.html">$DebugPrintTemplateList</a></li>

32

<li><a href="rsconf1_dircreatemode.html">$DirCreateMode</a></li>

33

<li><a href="rsconf1_dirgroup.html">$DirGroup</a></li>

34

<li><a href="rsconf1_dirowner.html">$DirOwner</a></li>

35

<li><a href="rsconf1_dropmsgswithmaliciousdnsptrrecords.html">$DropMsgsWithMaliciousDnsPTRRecords</a></li>

36

<li><a href="rsconf1_droptrailinglfonreception.html">$DropTrailingLFOnReception</a></li>

37

<li><a href="rsconf1_dynafilecachesize.html">$DynaFileCacheSize</a></li>

38

<li><a href="rsconf1_escapecontrolcharactersonreceive.html">$EscapeControlCharactersOnReceive</a></li>

39

<li><a href="rsconf1_failonchownfailure.html">$FailOnChownFailure</a></li>

40

<li><a href="rsconf1_filecreatemode.html">$FileCreateMode</a></li>

41

<li><a href="rsconf1_filegroup.html">$FileGroup</a></li>

42

<li><a href="rsconf1_fileowner.html">$FileOwner</a></li>

43

<li><a href="rsconf1_includeconfig.html">$IncludeConfig</a></li>

44

<li><a href="rsconf1_mainmsgqueuesize.html">$MainMsgQueueSize</a></li>

45

<li><a href="rsconf1_moddir.html">$ModDir</a></li>

46

<li><a href="rsconf1_modload.html">$ModLoad</a></li>

47

<li><a href="rsconf1_repeatedmsgreduction.html">$RepeatedMsgReduction</a></li>

48

<li><a href="rsconf1_resetconfigvariables.html">$ResetConfigVariables</a></li>

49

<li><a href="rsconf1_umask.html">$UMASK</a></li>

50

</ul>

51

<h2>Basic Structure</h2>

52

Rsyslog supports standard sysklogd's configuration file format and extends

53

it. So in general, you can take a "normal" syslog.conf and use it together with

54

rsyslogd. It will understand everything. However, to use most of rsyslogd's

55

unique features, you need to add extended configuration directives.Rsyslogd

56

supports the classical, selector-based rule lines. They are still at the heart

57

of it and all actions are initiated via rule lines. A rule lines is any line not

58

starting with a $ or the comment sign (#). Lines starting with $ carry

59

rsyslog-specific directives.Every rule line consists of two fields, a selector field and an action field.

60

These two fields are separated by one or more spaces or tabs. The selector field

61

specifies a pattern of facilities and priorities belonging to the specified

62

action.

63

64

Lines starting with a hash mark ("#'') and empty lines are ignored.

65

66

<h2>Templates</h2>

67

Templates are a key feature of rsyslog. They allow to specify any format a user

68

might want. They are also used for dynamic file name generation. Every output in rsyslog uses templates - this holds true for files,

69

user messages and so on. The database writer expects its template to be a proper

70

SQL statement - so this is highly customizable too. You might ask how does all

71

of this work when no templates at all are specified. Good question ;) The answer

72

is simple, though. Templates compatible with the stock syslogd formats are

73

hardcoded into rsyslogd. So if no template is specified, we use one of these

74

hardcoded templates. Search for "template_" in syslogd.c and you will find the

75

hardcoded ones.

76

A template consists of a template directive, a name, the actual template text

77

and optional options. A sample is:

78

<blockquote><code>$template MyTemplateName,"\7Text %property% some more text\n",<options></code></blockquote>

79

The "$template" is the template directive. It tells rsyslog that this line

80

contains a template. "MyTemplateName" is the template name. All

81

other config lines refer to this name. The text within quotes is the actual

82

template text. The backslash is an escape character, much as it is in C. It does

83

all these "cool" things. For example, \7 rings the bell (this is an ASCII

84

value), \n is a new line. C programmers and perl coders have the advantage of

85

knowing this, but the set in rsyslog is a bit restricted currently.

86

87

All text in the template is used literally, except for things within percent

88

signs. These are properties and allow you access to the contents of the syslog

89

message. Properties are accessed via the property replacer (nice name, huh) and

90

it can do cool things, too. For example, it can pick a substring or do

91

date-specific formatting. More on this is below, on some lines of the property

92

replacer.

93

94

The <options> part is optional. It carries options influencing the template as

95

whole. See details below. Be sure NOT to mistake template options with property

96

options - the later ones are processed by the property replacer and apply to a

97

SINGLE property, only (and not the whole template).

98

99

Template options are case-insensitive. Currently defined are:

100

sql - format the string suitable for a SQL statement in MySQL format. This will

101

replace single quotes ("'") and the backslash character by their

102

backslash-escaped counterpart ("\'" and "\\") inside each field. Please note

103

that in MySQL configuration, the <code class="literal">NO_BACKSLASH_ESCAPES</code>

104

mode must be turned off for this format to work (this is the default).

105

stdsql - format the string suitable for a SQL statement that is to be

106

sent to a standards-compliant sql server. This will

107

replace single quotes ("'") by two single quotes ("''") inside each field.

108

You must use stdsql together with MySQL if in MySQL configuration the

109

<code class="literal">NO_BACKSLASH_ESCAPES</code> is turned on.

110

Either the sql or stdsql

111

option must be specified when a template is used for writing to a database,

112

otherwise injection might occur. Please note that due to the unfortunate fact

113

that several vendors have violated the sql standard and introduced their own

114

escape methods, it is impossible to have a single option doing all the work. 

115

So you yourself must make sure you are using the right format. If you choose

116

the wrong one, you are still vulnerable to sql injection.

117

118

Please note that the database writer *checks* that the sql option is present in

119

the template. If it is not present, the write database action is disabled. This

120

is to guard you against accidental forgetting it and then becoming vulnerable

121

to SQL injection. The sql option can also be useful with files - especially if

122

you want to import them into a database on another machine for performance

123

reasons. However, do NOT use it if you do not have a real need for it - among

124

others, it takes some toll on the processing time. Not much, but on a really

125

busy system you might notice it ;)

126

The default template for the write to database action has the sql option set.

127

As we currently support only MySQL and the sql option matches the default MySQL

128

configuration, this is a good choice. However, if you have turned on

129

<code class="literal">NO_BACKSLASH_ESCAPES</code> in your MySQL config, you need

130

to supply a template with the stdsql option. Otherwise you will become

131

vulnerable to SQL injection.

132

133

To escape:

134

% = \%

135

\ = \\ --> '\' is used to escape (as in C)

136

$template TraditionalFormat,%timegenerated% %HOSTNAME% %syslogtag%%msg%\n"

137

138

Properties can be accessed by the <a href="property_replacer.html">property replacer</a>

139

(see there for details).

140

Please note that as of 1.15.0, templates can also by used to generate

141

selector lines with dynamic file names. For example, if you would like to

142

split syslog messages from different hosts to different files (one per host),

143

you can define the following template:

144

<blockquote><code>$template DynFile,"/var/log/system-%HOSTNAME%.log"</code></blockquote>

145

This template can then be used when defining an output selector line. It will

146

result in something like "/var/log/system-localhost.log"

147

<h2>Output Channels</h2>

148

Output Channels are a new concept first introduced in rsyslog 0.9.0. As of this

149

writing, it is most likely that they will be replaced by something different in

150

the future. So if you

151

use them, be prepared to change you configuration file syntax when you upgrade

152

to a later release.

153

154

The idea behind output channel definitions is that it shall provide an umbrella

155

for any type of output that the user might want. In essence,

156

this is the "file" part of selector lines (and this is why we are not sure

157

output channel syntax will stay after the next review). There is a

158

difference, though: selector channels both have filter conditions (currently

159

facility and severity) as well as the output destination. Output channels define

160

the output definition, only. As of this build, they can only be used to write to

161

files - not pipes, ttys or whatever else. If we stick with output channels, this

162

will change over time.

163

In concept, an output channel includes everything needed to know about an

164

output actions. In practice, the current implementation only carries

165

a filename, a maximum file size and a command to be issued when this file size

166

is reached. More things might be present in future version, which might also

167

change the syntax of the directive.

168

Output channels are defined via an $outchannel directive. It's syntax is as

169

follows:

170

171

$outchannel name,file-name,max-size,action-on-max-size

172

173

name is the name of the output channel (not the file), file-name is the file

174

name to be written to, max-size the maximum allowed size and action-on-max-size

175

a command to be issued when the max size is reached. This command always has

176

exactly one parameter. The binary is that part of action-on-max-size before the

177

first space, its parameter is everything behind that space.

178

179

Please note that max-size is queried BEFORE writing the log message to the file.

180

So be sure to set this limit reasonably low so that any message might fit. For

181

the current release, setting it 1k lower than you expected is helpful. The

182

max-size must always be specified in bytes - there are no special symbols (like

183

1k, 1m,...) at this point of development.

184

185

Keep in mind that $outchannel just defines a channel with "name". It does not

186

activate it. To do so, you must use a selector line (see below). That selector

187

line includes the channel name plus an $ sign in front of it. A sample might be:

188

189

*.* $mychannel

190

191

In its current form, output channels primarily provide the ability to size-limit

192

an output file. To do so, specify a maximum size. When this size is reached,

193

rsyslogd will execute the action-on-max-size command and then reopen the file

194

and retry. The command should be something like a log rotation script or a

195

similar thing.

196

If there is no action-on-max-size command or the command did not resolve the

197

situation, the file is closed and never reopened by rsyslogd (except, of course,

198

by huping it). This logic was integrated when we first experienced severe issues

199

with files larger 2gb, which could lead to rsyslogd dumping core. In such cases,

200

it is more appropriate to stop writing to a single file. Meanwhile, rsyslogd has

201

been fixed to support files larger 2gb, but obviously only on file systems and

202

operating system versions that do so. So it can still make sense to enforce a

203

2gb file size limit.

204

<h2>Filter Conditions</h2>

205

Rsyslog offers two different types "filter conditions":

206

<ul>

207

<li>"traditional" severity and facility based selectors</li>

208

<li>property-based filters</li>

209

</ul>

210

<h3>Blocks</h3>

211

Rsyslogd supports BSD-style blocks inside rsyslog.conf. Each block of lines

212

is separated from the previous block by a program or hostname specification. A

213

block will only log messages corresponding to the most recent program and

214

hostname specifications given. Thus, a block which selects �ppp� as the program,

215

directly followed by a block that selects messages from the hostname �dialhost�,

216

then the second block will only log messages from the ppp program on dialhost.

217

218

A program specification is a line beginning with �!prog� and the following

219

blocks will be associated with calls to syslog from that specific program. A

220

program specification for �foo� will also match any message logged by the kernel

221

with the prefix �foo: �. Alternatively, a program specification �-foo� causes the

222

following blocks to be applied to messages from any program but the one specified.

223

224

A hostname specification of the form �+hostname� and

225

the following blocks will be applied to messages received from the specified

226

hostname. Alternatively, a hostname specification �-hostname� causes the

227

following blocks to be applied to messages from any host but the one specified.

228

229

If the hostname is given as �@�, the local hostname will be used. (NOT YET

230

IMPLEMENTED) A program or hostname specification may be reset by giving the

231

program or hostname as �*�.

232

Please note that the "#!prog", "#+hostname" and "#-hostname" syntax available

233

in BSD syslogd is not supported by rsyslogd. By default, no hostname or program

234

is set.

235

<h3>Selectors</h3>

236

Selectors are the traditional way of filtering syslog messages. They

237

have been kept in rsyslog with their original syntax, because it is well-known,

238

highly effective and also needed for compatibility with stock syslogd

239

configuration files. If you just need to filter based on priority and facility,

240

you should do this with selector lines. They are not second-class

241

citizens in rsyslog and offer the best performance for this job.

242

The selector field itself again consists of two parts, a facility and a

243

priority, separated by a period (``.''). Both parts are case insensitive and can

244

also be specified as decimal numbers, but don't do that, you have been warned.

245

Both facilities and priorities are described in rsyslog(3). The names mentioned

246

below correspond to the similar LOG_-values in /usr/include/rsyslog.h. The facility is one of the following keywords: auth, authpriv, cron, daemon,

247

kern, lpr, mail, mark, news, security (same as auth), syslog, user, uucp and

248

local0 through local7. The keyword security should not be used anymore and mark

249

is only for internal use and therefore should not be used in applications.

250

Anyway, you may want to specify and redirect these messages here. The facility

251

specifies the subsystem that produced the message, i.e. all mail programs log

252

with the mail facility (LOG_MAIL) if they log using syslog. Please note that the upcoming next syslog-RFC specifies many more facilities.

253

Support for them will be added in a future version of rsyslog, which might

254

require changes to existing configuration files. The priority is one of the following keywords, in ascending order: debug, info,

255

notice, warning, warn (same as warning), err, error (same as err), crit, alert,

256

emerg, panic (same as emerg). The keywords error, warn and panic are deprecated

257

and should not be used anymore. The priority defines the severity of the message

258

The behavior of the original BSD syslogd is that all messages of the specified

259

priority and higher are logged according to the given action. Rsyslogd behaves the same, but has some extensions. In addition to the above mentioned names the rsyslogd(8) understands the

260

following extensions: An asterisk (``*'') stands for all facilities or all

261

priorities, depending on where it is used (before or after the period). The

262

keyword none stands for no priority of the given facility. You can specify multiple facilities with the same priority pattern in one

263

statement using the comma (``,'') operator. You may specify as much facilities

264

as you want. Remember that only the facility part from such a statement is

265

taken, a priority part would be skipped.

266

Multiple selectors may be specified for a single action using the semicolon

267

(``;'') separator. Remember that each selector in the selector field is capable

268

to overwrite the preceding ones. Using this behavior you can exclude some

269

priorities from the pattern.

270

Rsyslogd has a syntax extension to the original BSD source, that makes its

271

use more intuitively. You may precede every priority with an equation sign

272

(``='') to specify only this single priority and not any of the above. You may

273

also (both is valid, too) precede the priority with an exclamation mark (``!'')

274

to ignore all that priorities, either exact this one or this and any higher

275

priority. If you use both extensions than the exclamation mark must occur before

276

the equation sign, just use it intuitively.

277

<h3>Property-Based Filters</h3>

278

Property-based filters are unique to rsyslogd. They allow to filter on any

279

property, like HOSTNAME, syslogtag and msg. A list of all currently-supported

280

properties can be found in the <a href="property_replacer.html">property

281

replacer documentation</a> (but keep in mind that only the properties, not the

282

replacer is supported). With this filter, each properties can be checked against

283

a specified value, using a specified compare operation. Currently, there is only

284

a single compare operation (contains) available, but additional operations will be added in the

285

future.

286

A property-based filter must start with a colon in column 0. This tells

287

rsyslogd that it is the new filter type. The colon must be followed by the

288

property name, a comma, the name of the compare operation to carry out, another

289

comma and then the value to compare against. This value must be quoted. There

290

can be spaces and tabs between the commas. Property names and compare operations

291

are case-sensitive, so "msg" works, while "MSG" is an invalid property name. In

292

brief, the syntax is as follows:

293

<code>:property, [!]compare-operation, "value"</code>

294

The following compare-operations are currently supported:

295

296

<tr>

297

<td>contains</td>

298

<td>Checks if the string provided in value is contained in the property.

299

There must be an exact match, wildcards are not supported.</td>

300

</tr>

301

<tr>

302

<td>isequal</td>

303

<td>Compares the "value" string provided and the property contents.

304

These two values must be exactly equal to match. The difference to

305

contains is that contains searches for the value anywhere inside the

306

property value, whereas all characters must be identical for isequal. As

307

such, isequal is most useful for fields like syslogtag or FROMHOST,

308

where you probably know the exact contents.</td>

309

</tr>

310

<tr>

311

<td>startswith</td>

312

<td>Checks if the value is found exactly at the beginning of the

313

property value. For example, if you search for "val" with<code>:msg,

314

startswith, "val"</code>

315

it will be a match if msg contains "values are in this message" but

316

it won't match if the msg contains "There are values in this message"

317

(in the later case, contains would match). Please note that "startswith"

318

is by far faster than regular expressions. So even once they are

319

implemented, it can make very much sense (performance-wise) to use "startswith".</td>

320

</tr>

321

<tr>

322

<td>regex</td>

323

<td>Compares the property against the provided regular expression.</td>

324

</tr>

325

</table>

326

You can use the bang-character (!) immediately in front of a

327

compare-operation, the outcome of this operation is negated. For example, if msg

328

contains "This is an informative message", the following sample would not match:

329

<code>:msg, contains, "error"</code>

330

but this one matches:

331

<code>:msg, !contains, "error"</code>

332

Using negation can be useful if you would like to do some generic processing

333

but exclude some specific events. You can use the discard action in conjunction

334

with that. A sample would be:

335

<code>*.* /var/log/allmsgs-including-informational.log

336

:msg, contains, "informational"  ~

337

*.* /var/log/allmsgs-but-informational.log</code>

338

Do not overlook the red tilde in line 2! In this sample, all messages are

339

written to the file allmsgs-including-informational.log. Then, all messages

340

containing the string "informational" are discarded. That means the config file

341

lines below the "discard line" (number 2 in our sample) will not be applied to

342

this message. Then, all remaining lines will also be written to the file

343

allmsgs-but-informational.log.

344

Value is a quoted string. It supports some escape sequences:

345

\" - the quote character (e.g. "String with \"Quotes\"")

346

\\ - the backslash character (e.g. "C:\\tmp")

347

Escape sequences always start with a backslash. Additional escape sequences

348

might be added in the future. Backslash characters must be escaped. Any

349

other sequence then those outlined above is invalid and may lead to

350

unpredictable results.

351

Probably, "msg" is the most prominent use case of property based filters. It

352

is the actual message text. If you would like to filter based on some message

353

content (e.g. the presence of a specific code), this can be done easily by:

354

<code>:msg, contains, "ID-4711"</code>

355

This filter will match when the message contains the string "ID-4711". Please

356

note that the comparison is case-sensitive, so it would not match if "id-4711"

357

would be contained in the message.

358

Getting property-based filters right can sometimes be challenging. In order

359

to help you do it with as minimal effort as possible, rsyslogd spits out debug

360

information for all property-based filters during their evaluation. To enable

361

this, run rsyslogd in foreground and specify the "-d" option.

362

Boolean operations inside property based filters (like 'message contains

363

"ID17" or message contains "ID18"') are currently not supported

364

(except for "not" as outlined above). Please note

365

that while it is possible to query facility and severity via property-based filters,

366

it is far more advisable to use classic selectors (see above) for those

367

cases.

368

<h2>ACTIONS</h2>

369

The action field of a rule describes what to do with the message. In general,

370

message content is written to a kind of "logfile". But also other actions might

371

be done, like writing to a database table or forwarding to another host.

372

373

Templates can be used with all actions. If used, the specified template is used

374

to generate the message content (instead of the default template). To specify a

375

template, write a semicolon after the action value immediately followed by the

376

template name.

377

378

Beware: templates MUST be defined BEFORE they are used. It is OK to define some

379

templates, then use them in selector lines, define more templates and use use

380

them in the following selector lines. But it is NOT permitted to use a template

381

in a selector line that is above its definition. If you do this, the action will be ignored.

382

You can have multiple actions for a single selector  (or more

383

precisely a single filter of such a selector line). Each action must be on its

384

own line and the line must start with an ampersand ('&') character and have no

385

filters. An example would be

386

<code>*.=crit rger

387

& root

388

& /var/log/critmsgs</code>

389

These three lines send critical messages to the user rger and root and also

390

store them in /var/log/critmsgs. Using multiple actions per selector is

391

convenient and also offers a performance benefit. As the filter needs to

392

be evaluated only once, there is less computation required to process the

393

directive compared to the otherwise-equal config directives below:

394

<code>*.=crit rger

395

*.=crit root

396

*.=crit /var/log/critmsgs</code>

397

398

<h3>Regular File</h3>

399

Typically messages are logged to real files. The file has to be specified with

400

full pathname, beginning with a slash "/''.

401

402

You may prefix each entry with the minus ``-'' sign to omit syncing the file

403

after every logging. Note that you might lose information if the system crashes

404

right behind a write attempt. Nevertheless this might give you back some

405

performance, especially if you run programs that use

406

logging in a very verbose manner.

407

If your system is connected to a reliable UPS and you receive lots of log

408

data (e.g. firewall logs), it might be a very good idea to turn of

409

syncing by specifying the "-" in front of the file name.

410

The filename can be either static (always the same) or dynamic

411

(different based on message received). The later is useful if you would

412

automatically split messages into different files based on some message

413

criteria. For example, dynamic file name selectors allow you to split messages

414

into different files based on the host that sent them. With dynamic file names,

415

everything is automatic and you do not need any filters.

416

It works via the template system. First, you define a template for the file

417

name. An example can be seen above in the description of template. We will use

418

the "DynFile" template defined there. Dynamic filenames are indicated by

419

specifying a questions mark "?" instead of a slash, followed by the template

420

name. Thus, the selector line for our dynamic file name would look as follows:

421

422

<code>*.* ?DynFile</code>

423

</blockquote>

424

That's all you need to do. Rsyslog will now automatically generate file names

425

for you and store the right messages into the right files. Please note that the

426

minus sign also works with dynamic file name selectors. Thus, to avoid syncing,

427

you may use

428

429

<code>*.* -?DynFile</code></blockquote>

430

And of course you can use templates to specify the output format:

431

432

<code>*.* ?DynFile;MyTemplate</code></blockquote>

433

A word of caution: rsyslog creates files as needed. So if a new host

434

is using your syslog server, rsyslog will automatically create a new file for

435

it.

436

437

Creating directories is also supported. For example you can use the hostname as directory

438

and the program name as file name:

439

440

<code>$template DynFile,"/var/log/%HOSTNAME%/%programname%.log"</code></blockquote>

441

442

<h3>Named Pipes</h3>

443

This version of rsyslogd(8) has support for logging output to named pipes (fifos).

444

A fifo or named pipe can be used as a destination for log messages by prepending

445

a pipe symbol (``|'') to the name of the file. This is handy for debugging. Note

446

that the fifo must be created with the mkfifo(1) command before rsyslogd(8) is

447

started.

448

<h3>Terminal and Console</h3>

449

If the file you specified is a tty, special tty-handling is done, same with

450

/dev/console.

451

<h3>Remote Machine</h3>

452

Rsyslogd provides full remote logging, i.e. is able to send messages to a

453

remote host running rsyslogd(8) and to receive messages from remote hosts.

454

Using this feature you're able to control all syslog messages on one host, if

455

all other machines will log remotely to that. This tears down

456

administration needs.

457

458

Please note that this version of rsyslogd by default does NOT forward messages

459

it has received from the network to another host. Specify the "-h" option to enable this.

460

To forward messages to another host, prepend the hostname with the at sign ("@").

461

A single at sign means that messages will be forwarded via UDP protocol (the

462

standard for syslog). If you prepend two at signs ("@@"), the messages will be

463

transmitted via TCP. Please note that plain TCP based syslog is not officially

464

standardized, but most major syslogds support it (e.g. syslog-ng or WinSyslog).

465

The forwarding action indicator (at-sign) can be followed by one or more options.

466

If they are given, they must be immediately (without a space) following the

467

final at sign and be enclosed in parenthesis. The individual options must be

468

separated by commas. The following options are right now defined:

469

470

<tr>

471

<td>

472

z<number></td>

473

<td>Enable zlib-compression for the message. The <number> is the

474

compression level. It can be 1 (lowest gain, lowest CPU overhead) to 9 (maximum

475

compression, highest CPU overhead). The level can also be 0, which means

476

"no compression". If given, the "z" option is ignored. So this does not

477

make an awful lot of sense. There is hardly a difference between level 1

478

and 9 for typical syslog messages. You can expect a compression gain

479

between 0% and 30% for typical messages. Very chatty messages may

480

compress up to 50%, but this is seldom seen with typically traffic.

481

Please note that rsyslogd checks the compression gain. Messages with 60

482

bytes or less will never be compressed. This is because compression gain

483

is pretty unlikely and we prefer to save CPU cycles. Messages over that

484

size are always compressed. However, it is checked if there is a gain in

485

compression and only if there is, the compressed message is transmitted.

486

Otherwise, the uncompressed messages is transmitted. This saves the

487

receiver CPU cycles for decompression. It also prevents small message to

488

actually become larger in compressed form.Please note that when a

489

TCP transport is used, compression will also turn on

490

syslog-transport-tls framing. See the "o" option for important

491

information on the implications.

492

Compressed messages are automatically detected and decompressed by

493

the receiver. There is nothing that needs to be configured on the

494

receiver side.</td>

495

</tr>

496

<tr>

497

<td>

498

o</td>

499

<td>This option is experimental. Use at your own risk and only if you

500

know why you need it! If in doubt, do NOT turn it on.This option

501

is only valid for plain TCP based transports. It selects a different

502

framing based on IETF internet draft syslog-transport-tls-06. This

503

framing offers some benefits over traditional LF-based framing. However,

504

the standardization effort is not yet complete. There may be changes in

505

upcoming versions of this standard. Rsyslog will be kept in line with

506

the standard. There is some chance that upcoming changes will be

507

incompatible to the current specification. In this case, all systems

508

using -transport-tls framing must be upgraded. There will be no effort

509

made to retain compatibility between different versions of rsyslog. The

510

primary reason for that is that it seems technically impossible to

511

provide compatibility between some of those changes. So you should take

512

this note very serious. It is not something we do not *like* to do (and

513

may change our mind if enough people beg...), it is something we most

514

probably *can not* do for technical reasons (aka: you can beg as much as

515

you like, it won't change anything...).

516

The most important implication is that compressed syslog messages via

517

TCP must be considered with care. Unfortunately, it is technically

518

impossible to transfer compressed records over traditional syslog plain

519

tcp transports, so you are left with two evil choices...</td>

520

</tr>

521

</table>

522

523

The hostname may be followed by a colon and the destination port.

524

The following is an example selector line with forwarding:

525

*.*    @@(o,z9)192.168.0.1:1470

526

In this example, messages are forwarded via plain TCP with experimental

527

framing and maximum compression to the host 192.168.0.1 at port 1470.

528

*.* @192.168.0.1

529

In the example above, messages are forwarded via UDP to the machine

530

192.168.0.1, the destination port defaults to 514. Messages will not be

531

compressed.

532

Note to sysklogd users: sysklogd does not support RFC 3164

533

format, which is the default forwarding template in rsyslog. As such, you will

534

experience duplicate hostnames if rsyslog is the sender and sysklogd is the

535

receiver. The fix is simple: you need to use a different template. Use that one:

536

$template sysklogd,"<%PRI%>%TIMESTAMP%

537

%syslogtag%%msg%\""

538

*.* @192.168.0.1;sysklogd

539

<h3>List of Users</h3>

540

Usually critical messages are also directed to ``root'' on that machine. You can

541

specify a list of users that shall get the message by simply writing the login.

542

You may specify more than one user by separating them with commas (",''). If

543

they're logged in they get the message. Don't think a mail would be sent, that

544

might be too late.

545

<h3>Everyone logged on</h3>

546

Emergency messages often go to all users currently online to notify them that

547

something strange is happening with the system. To specify this wall(1)-feature

548

use an asterisk ("*'').

549

<h3>Call Plugin</h3>

550

This is a generic way to call an output plugin. The plugin must support this

551

functionality. Actual parameters depend on the module, so see the module's doc

552

on what to supply. The general syntax is as follows:

553

:modname:params;template

554

Currently, the ommysql database output module supports this syntax (in

555

addtion to the ">" syntax it traditionally supported). For ommysql, the module

556

name is "ommysql" and the params are the traditional ones. The ;template part is

557

not module specific, it is generic rsyslog functionality available to all

558

modules.

559

As an example, the ommysql module may be called as follows:

560

:ommysql:dbhost,dbname,dbuser,dbpassword;dbtemplate

561

For details, please see the "Database Table" section of this documentation.

562

Note: as of this writing, the ":modname:" part is hardcoded into the module.

563

So the name to use is not necessarily the name the module's plugin file is

564

called.

565

<h3>Database Table</h3>

566

This allows logging of the message to a database table. Currently, only MySQL

567

databases are supported. However, other database drivers will most probably be

568

developed as plugins. By default, a <a href="http://www.monitorware.com/">MonitorWare</a>-compatible schema is required

569

for this to work. You can create that schema with the createDB.SQL file that

570

came with the rsyslog package. You can also

571

use any other schema of your liking - you just need to define a proper template

572

and assign this template to the action.

573

574

The database writer is called by specifying a greater-then sign (">") in front

575

of the database connect information. Immediately after that

576

sign the database host name must be given, a comma, the database name, another

577

comma, the database user, a comma and then the user's password. If a specific

578

template is to be used, a semicolon followed by the template name can follow

579

the connect information. This is as follows:

580

581

>dbhost,dbname,dbuser,dbpassword;dbtemplate

582

Important: to use the database functionality, the MySQL output module must be

583

loaded in the config file BEFORE the first database table action is used. This is done by

584

placing the

585

<code>$ModLoad MySQL</code>

586

directive some place above the first use of the database write (we recommend

587

doing at the the beginning of the config file).

588

<h3>Discard</h3>

589

If the discard action is carried out, the received message is immediately

590

discarded. No further processing of it occurs. Discard has primarily been added

591

to filter out messages before carrying on any further processing. For obvious

592

reasons, the results of "discard" are depending on where in the configuration

593

file it is being used. Please note that once a message has been discarded there

594

is no way to retrieve it in later configuration file lines.

595

Discard can be highly effective if you want to filter out some annoying

596

messages that otherwise would fill your log files. To do that, place the discard

597

actions early in your log files. This often plays well with property-based

598

filters, giving you great freedom in specifying what you do not want.

599

Discard is just the single tilde character with no further parameters:

600

~

601

For example,

602

*.*   ~

603

discards everything (ok, you can achive the same by not running rsyslogd at

604

all...).

605

<h3>Output Channel</h3>

606

Binds an output channel definition (see there for details) to this action.

607

Output channel actions must start with a $-sign, e.g. if you would like to bind

608

your output channel definition "mychannel" to the action, use "$mychannel".

609

Output channels support template definitions like all all other actions.

610

<h3>Shell Execute</h3>

611

This executes a program in a subshell. The program is passed the

612

template-generated message as the only command line parameter. Rsyslog waits

613

until the program terminates and only then continues to run.

614

^program-to-execute;template

615

The program-to-execute can be any valid executable. It receives the template

616

string as a single parameter (argv[1]).

617

WARNING: The Shell Execute action was added to serve an urgent need.

618

While it is considered reasonable save when used with some thinking, its

619

implications must be considered. The current implementation uses a system() call

620

to execute the command. This is not the best way to do it (and will hopefully

621

changed in further releases). Also, proper escaping of special characters is

622

done to prevent command injection. However, attackers always find smart ways to

623

circumvent escaping, so we can not say if the escaping applied will really safe

624

you from all hassles. Lastly, rsyslog will wait until the shell command

625

terminates. Thus, a program error in it (e.g. an infinite loop) can actually

626

disable rsyslog. Even without that, during the programs run-time no messages are

627

processed by rsyslog. As the IP stacks buffers are quickly overflowed, this

628

bears an increased risk of message loss. You must be aware of these implications.

629

Even though they are severe, there are several cases where the "shell execute"

630

action is very useful. This is the reason why we have included it in its current

631

form. To mitigate its risks, always a) test your program thoroughly, b) make

632

sure its runtime is as short as possible (if it requires a longer run-time, you

633

might want to spawn your own sub-shell asynchronously), c) apply proper

634

firewalling so that only known senders can send syslog messages to rsyslog.

635

Point c) is especially important: if rsyslog is accepting message from any hosts,

636

chances are much higher that an attacker might try to exploit the "shell execute"

637

action.

638

<h2>TEMPLATE NAME</h2>

639

Every ACTION can be followed by a template name. If so, that template is used

640

for message formatting. If no name is given, a hard-coded default template is

641

used for the action. There can only be one template name for each given action.

642

The default template is specific to each action. For a description of what a

643

template is and what you can do with it, see "TEMPLATES" at the top of this

644

document.

645

<h2>EXAMPLES</h2>

646

Below are example for templates and selector lines. I hope they are

647

self-explanatory. If not, please see www.monitorware.com/rsyslog/ for advise.

648

<h3>TEMPLATES</h3>

649

Please note that the samples are split across multiple lines. A template MUST

650

NOT actually be split across multiple lines.

651

652

A template that resembles traditional syslogd file output:

653

$template TraditionalFormat,"%timegenerated% %HOSTNAME%

654

%syslogtag%%msg:::drop-last-lf%\n"

655

656

A template that tells you a little more about the message:

657

$template precise,"%syslogpriority%,%syslogfacility%,%timegenerated%,%HOSTNAME%,

658

%syslogtag%,%msg%\n"

659

660

A template for RFC 3164 format:

661

$template RFC3164fmt,"<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%"

662

663

A template for the format traditonally used for user messages:

664

$template usermsg," XXXX%syslogtag%%msg%\n\r"

665

666

And a template with the traditonal wall-message format:

667

$template wallmsg,"\r\n\7Message from syslogd@%HOSTNAME% at %timegenerated%

668

669

A template that can be used for the database write (please note the SQL

670

template option)

671

$template MySQLInsert,"insert iut, message, receivedat values

672

('%iut%', '%msg:::UPPERCASE%', '%timegenerated:::date-mysql%')

673

into systemevents\r\n", SQL

674

675

The following template emulates <a href="http://www.winsyslog.com/en/">WinSyslog</a>

676

format (it's an <a href="http://www.adiscon.com/en/">Adiscon</a> format, you do

677

not feel bad if you don't know it ;)). It's interesting to see how it takes

678

different parts out of the date stamps. What happens is that the date stamp is

679

split into the actual date and time and the these two are combined with just a

680

comma in between them.

681

682

$template WinSyslogFmt,"%HOSTNAME%,%timegenerated:1:10:date-rfc3339%,

683

%timegenerated:12:19:date-rfc3339%,%timegenerated:1:10:date-rfc3339%,

684

%timegenerated:12:19:date-rfc3339%,%syslogfacility%,%syslogpriority%,

685

%syslogtag%%msg%\n"

686

<h3>SELECTOR LINES</h3>

687

# Store critical stuff in critical

688

#

689

*.=crit;kern.none /var/adm/critical

690

691

This will store all messages with the priority crit in the file /var/adm/critical,

692

except for any kernel message.

693

694

695

# Kernel messages are first, stored in the kernel

696

# file, critical messages and higher ones also go

697

# to another host and to the console. Messages to

698

# the host finlandia are forwarded in RFC 3164

699

# format (using the template defined above).

700

#

701

kern.* /var/adm/kernel

702

kern.crit @finlandia;RFC3164fmt

703

kern.crit /dev/console

704

kern.info;kern.!err /var/adm/kernel-info

705

706

The first rule direct any message that has the kernel facility to the file /var/adm/kernel.

707

708

The second statement directs all kernel messages of the priority crit and higher

709

to the remote host finlandia. This is useful, because if the host crashes and

710

the disks get irreparable errors you might not be able to read the stored

711

messages. If they're on a remote host, too, you still can try to find out the

712

reason for the crash.

713

714

The third rule directs these messages to the actual console, so the person who

715

works on the machine will get them, too.

716

717

The fourth line tells rsyslogd to save all kernel messages that come with

718

priorities from info up to warning in the file /var/adm/kernel-info. Everything

719

from err and higher is excluded.

720

721

722

# The tcp wrapper loggs with mail.info, we display

723

# all the connections on tty12

724

#

725

mail.=info /dev/tty12

726

727

This directs all messages that uses mail.info (in source LOG_MAIL | LOG_INFO) to

728

/dev/tty12, the 12th console. For example the tcpwrapper tcpd(8) uses this as

729

it's default.

730

731

732

# Store all mail concerning stuff in a file

733

#

734

mail.*;mail.!=info /var/adm/mail

735

736

This pattern matches all messages that come with the mail facility, except for

737

the info priority. These will be stored in the file /var/adm/mail.

738

739

740

# Log all mail.info and news.info messages to info

741

#

742

mail,news.=info /var/adm/info

743

744

This will extract all messages that come either with mail.info or with news.info

745

and store them in the file /var/adm/info.

746

747

748

# Log info and notice messages to messages file

749

#

750

*.=info;*.=notice;\

751

mail.none /var/log/messages

752

753

This lets rsyslogd log all messages that come with either the info or the notice

754

facility into the file /var/log/messages, except for all

755

messages that use the mail facility.

756

757

758

# Log info messages to messages file

759

#

760

*.=info;\

761

mail,news.none /var/log/messages

762

763

This statement causes rsyslogd to log all messages that come with the info

764

priority to the file /var/log/messages. But any message coming either with the

765

mail or the news facility will not be stored.

766

767

768

# Emergency messages will be displayed using wall

769

#

770

*.=emerg *

771

772

This rule tells rsyslogd to write all emergency messages to all currently logged

773

in users. This is the wall action.

774

775

776

# Messages of the priority alert will be directed

777

# to the operator

778

#

779

*.alert root,rgerhards

780

781

This rule directs all messages with a priority of alert or higher to the

782

terminals of the operator, i.e. of the users ``root'' and ``rgerhards'' if

783

they're logged in.

784

785

786

*.* @finlandia

787

788

This rule would redirect all messages to a remote host called finlandia. This is

789

useful especially in a cluster of machines where all syslog messages will be

790

stored on only one machine.

791

792

In the format shown above, UDP is used for transmitting the message. The

793

destination port is set to the default auf 514. Rsyslog is also capable of using

794

much more secure and reliable TCP sessions for message forwarding. Also, the

795

destination port can be specified. To select TCP, simply add one additional @ in

796

front of the host name (that is, @host is UPD, @@host is TCP). For example:

797

798

799

*.* @@finlandia

800

801

To specify the destination port on the remote machine, use a colon followed by

802

the port number after the machine name. The following forwards to port 1514 on

803

finlandia:

804

805

806

*.* @@finlandia:1514

807

808

This syntax works both with TCP and UDP based syslog. However, you will probably

809

primarily need it for TCP, as there is no well-accepted port for this transport

810

(it is non-standard). For UDP, you can usually stick with the default auf 514,

811

but might want to modify it for security rea-

812

sons. If you would like to do that, it's quite easy:

813

814

815

*.* @finlandia:1514

816

817

818

819

*.* >dbhost,dbname,dbuser,dbpassword;dbtemplate

820

821

This rule writes all message to the database "dbname" hosted on "dbhost". The

822

login is done with user "dbuser" and password "dbpassword". The actual table

823

that is updated is specified within the template (which contains the insert

824

statement). The template is called "dbtemplate" in this case.

825

:msg,contains,"error" @errorServer

826

This rule forwards all messages that contain the word "error" in the msg part

827

to the server "errorServer". Forwarding is via UDP. Please note the colon in

828

fron

829

<h2>CONFIGURATION FILE SYNTAX DIFFERENCES</h2>

830

Rsyslogd uses a slightly different syntax for its configuration file than the

831

original BSD sources. Originally all messages of a specific priority and above

832

were forwarded to the log file. The modifiers ``='', ``!'' and ``-'' were added

833

to make rsyslogd more flexible and to use it in a more intuitive manner.

834

835

The original BSD syslogd doesn't understand spaces as separators between the

836

selector and the action field.

837

838

When compared to syslogd from sysklogd package, rsyslogd offers additional

839

<a href="features.html">features</a> (like template and database support). For obvious reasons, the syntax for

840

defining such features is available

841

in rsyslogd, only.

842

843

</body>

844

</html>