File: syslog-ng.xml

package info (click to toggle)
syslog-ng 2.0.0-1etch1
  • links: PTS
  • area: main
  • in suites: etch
  • size: 1,844 kB
  • ctags: 2,014
  • sloc: ansic: 9,125; xml: 2,125; sh: 1,210; yacc: 741; lex: 278; makefile: 191; awk: 94; python: 85; perl: 49
file content (2166 lines) | stat: -rw-r--r-- 87,542 bytes parent folder | download | duplicates (2)
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
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
<?xml version="1.0" encoding="iso-8859-2"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "/usr/share/sgml/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % docvars SYSTEM "../docvars.xml.in">
  %docvars;
]>

<book>
	<bookinfo>
		<title>syslog-ng v2.0 reference manual</title>
		<authorgroup>
			<author>
				<firstname>Bal&aacute;zs</firstname>
				<surname>Scheidler</surname>
			</author>
		</authorgroup>
		<releaseinfo>&syslogng_version; (&syslogng_revision;)</releaseinfo>
		<copyright>
			<year>1999-2006</year>
			<holder>Bal&aacute;zs Scheidler</holder>
		</copyright>
		<legalnotice>
			<para>This manual is free software; you may redistribute it and/or modify it under the
				terms of the GNU General Public License as published by the Free Software
				Foundation; either version 2, or (at your option) any later version. </para>
			<para>This is distributed in the hope that it will be useful, but without any warranty;
				without even the implied warranty of merchantability or fitness for a particular
				purpose. See the GNU General Public License for more details. </para>
		</legalnotice>
	</bookinfo>

	<chapter id="intro">
		<title>Introduction to syslog-ng</title>
		<para>One of the most neglected area of Unix is handling system events. Daily checks for
			system messages is crucial for the security and health conditions of a computer system. </para>
		<para>System logs contain much "noise" - messages having no importance - and important
			events which should not be lost in the tide of messages. With the current tools it is
			difficult to select which messages are interesting. </para>
		<para>A message is sent to different destinations based on the assigned facility/priority
			pair. There are 12+8 (12 real and 8 local) predefined facilities (mail, news, auth
			etc.), and 8 priorities (ranging from alert to debug). </para>
		<para>One problem is that there are facilities which are too general (e.g.: daemon), and are
			used by many programs, even if they do not relate each other. It is difficult to find
			the interesting bits from the enormous amount of messages. </para>
		<para>A second problem is that there are very few programs which allow setting their
			"facility code" to use for logging. It is at best a compile time parameter. </para>
		<para>Consequently, using facilities as a means of filtering is not an optimal approach. A
			better solution would be to make the syslog facility a runtime option for all
			applications, and add the ability to create new facilities in syslogd. Neither of these
			are available; the first one is not even feasible. </para>
		<para>One of the design principles of <emphasis>syslog-ng</emphasis> was to make message
			filtering much more finegrained. <emphasis>syslog-ng</emphasis> is able to filter
			messages based on the contents of messages in addition to the priority/facility pair.
			This way only the really important messages are sent to a specific destination. Another
			design principle was to make log forwarding between firewalled segments easier using
			long hostname format, which makes it easy to find the originating and the chain of
			forwarding hosts - even if a log message traverses several computers. The last principle
			was a clean and powerful configuration file format. </para>

		<sect1 id="timezone_handling">
			<title>Timezone handling</title>
			<para>One of the new features of syslog-ng 2.0 is the support for messages originating
				from different timezones. This is a difficult problem, as the original syslog
				protocol does not include timezone information. syslog-ng provides a solution by
				extending the syslog protocol to include this information and also by giving
				finegrained control to the administrator to supply timezone information for legacy
				devices which do not support the protocol extension. </para>
			<para>Timezone information is associated with messages entering syslog-ng using the
				following algorithm:</para>
			<procedure>
				<step>
					<para>The sender can specify the timezone of the messages. If the incoming
						message includes a timezone it is associated with the message. Otherwise,
						the local timezone is assumed.</para>
				</step>
				<step>
					<para>The administrator specifies the <link linkend="sourcecommonopts">
							<parameter>time_zone()</parameter>
						</link> parameter for the source driver that reads the message. This
						parameter overrides the original timezone of the message. Each source
						defaults to the value of the <link linkend="reference_options">
							<parameter>recv_time_zone()</parameter>
						</link> global option. </para>
				</step>
				<step>
					<para>The destination driver specifies the timezone via the <link
							linkend="destcommonopts">
							<parameter>timezone()</parameter>
						</link> parameter. Each destination driver might have an associated timezone
						value to which message timestamps are converted before they are sent to the
						final destination (file or network socket). Each destination defaults to the
						value of the <link linkend="reference_options">
							<parameter>send_time_zone()</parameter>
						</link> global option. A message can be sent to multiple destination
					zones.</para>
				</step>
				<step>
					<para> When macro expansions are used in the destination filenames, the local
						timezone is used. </para>
				</step>
			</procedure>
			<para>There is another case when message timestamps are formatted: </para>
		</sect1>
	</chapter>

	<chapter id="msgroute">
		<title>Global objects</title>
		<para>In <emphasis>syslog-ng</emphasis> a message path (or message route) consist of one or
			more sources, one or more filtering rules and one or more destinations. A message is
			entered to <emphasis>syslog-ng</emphasis> in one of its sources, if that message matches
			the filtering rules it is sent to the specified destinations. Note that a message goes
			to <emphasis>all</emphasis> matching destinations by default, although this behavior can
			be changed. </para>
		<sect1 id="sources">
			<title>Sources</title>
			<para>A source is a set of source drivers collecting messages using a given method. For
				instance, there is a source driver for <parameter>AF_UNIX</parameter>,
					<parameter>SOCK_STREAM</parameter> style sockets, used by the Linux
					<filename>syslog()</filename> call. </para>
			<para>To declare a source, the source statement has to be used in the configuration file
				with the following syntax: </para>
			<para>
				<synopsis>
					source &lt;identifier&gt; { source-driver(params); source-driver(params); ... };
				</synopsis>
			</para>
			<para>The identifier has to uniquely identify the given source, and may not clash with
				any of the reserved words (in case of a name clash, simply enclose the identifier in
				quotation marks). </para>
			<para>You can control exactly which drivers are used to gather log messages, thus you
				have to know how your system and its native <parameter>syslogd</parameter>
				communicate. Below is an introduction to the inner workings of
				<parameter>syslogd</parameter> on some of the tested platforms:</para>
			<table>
				<title>Communication method between syslogd and its clients</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Platform</entry>
							<entry>Method</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Linux</entry>
							<entry>A <parameter>SOCK_STREAM</parameter> unix socket named
									<parameter>/dev/log</parameter>; some of the distributions
								layers switched over to using <parameter>SOCK_DGRAM</parameter>,
								though applications still work with either method. </entry>
						</row>
						<row>
							<entry>BSD flavors</entry>
							<entry>A <parameter>SOCK_DGRAM</parameter> unix socket named
									<parameter>/var/run/log</parameter>.</entry>
						</row>
						<row>
							<entry>Solaris (2.5 or below)</entry>
							<entry>An SVR4 style <parameter>STREAMS</parameter> device named
									<parameter>/dev/log</parameter>.</entry>
						</row>
						<row>
							<entry>Solaris (2.6 or above)</entry>
							<entry>In addition to the <parameter>STREAMS</parameter> device used in
								earlier versions, 2.6 uses a new multithreaded IPC method called
								door. By default the door used by <parameter>syslogd</parameter> is
									<parameter>/etc/.syslog_door</parameter>. </entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			<para>Each possible communication mechanism has the corresponding source driver in
					<emphasis>syslog-ng</emphasis>. For instance, to open a unix socket with
					<parameter>SOCK_DGRAM</parameter> style communication use the driver
					<parameter>unix-dgram</parameter>, the same with
				<parameter>SOCK_STREAM</parameter> style - as used under Linux - is called
				unix-stream. </para>
			<example>
				<title>Source statement on a Linux based operating system</title>
				<synopsis>
					source src { unix-stream("/dev/log"); internal(); udp(ip(0.0.0.0) port(514)); };
				</synopsis>
			</example>
			<para>Each driver may take parameters; some of them are required, others are optional.
				The required parameters are positional, meaning that they must be specified in a
				defined order. A <parameter>unix-stream()</parameter> driver has a single required
				argument, the name of the socket to listen to, and several optional parameters,
				which follow the socket name. Optional arguments can be specified in any order using
				the <literal>option(value)</literal> syntax. </para>
			<para>
				<table>
					<title>Available source drivers in syslog-ng</title>
					<tgroup cols="2">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>internal()</entry>
								<entry>Messages generated internally in
									<emphasis>syslog-ng</emphasis>.</entry>
							</row>
							<row>
								<entry>unix-stream()</entry>
								<entry>Opens the specified unix socket in
									<parameter>SOCK_STREAM</parameter> mode and listens for
									messages.</entry>
							</row>
							<row>
								<entry>unix-dgram()</entry>
								<entry>Opens the specified unix socket in
									<parameter>SOCK_DGRAM</parameter> mode and listens for
								messages.</entry>
							</row>
							<row>
								<entry>file()</entry>
								<entry>Opens the specified file and reads messages.</entry>
							</row>
							<row>
								<entry>pipe(), fifo</entry>
								<entry>Opens the specified named pipe and reads messages.</entry>
							</row>
							<row>
								<entry>tcp()</entry>
								<entry>Listens on the specified TCP port for messages.</entry>
							</row>
							<row>
								<entry>udp()</entry>
								<entry>Listens on the specified UDP port for messages.</entry>
							</row>
							<row>
								<entry>tcp6()</entry>
								<entry>Listens on the specified TCP port for messages over
								IPv6.</entry>
							</row>
							<row>
								<entry>udp6()</entry>
								<entry>Listens on the specified UDP port for messages over
								IPv6.</entry>
							</row>
							<row>
								<entry>sun-stream(), sun-streams()</entry>
								<entry>Opens the specified <parameter>STREAMS</parameter> device on
									Solaris systems and reads messages.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</para>
			<para>For a complete descriptions on the above drivers, see <xref
					linkend="reference_sourcedrivers"/>. </para>
		</sect1>
		<sect1 id="filters">
			<title>Filters</title>
			<para>Filters perform log routing within <emphasis>syslog-ng</emphasis>. You can write a
				boolean expression using internal functions: a message passes if the expression is
				true. </para>
			<para>Filters also have a unique identifying name that can be referenced in log
				statements. </para>
			<para>Syntax for the filter statement:</para>
			<synopsis>
				filter &lt;identifier&gt; { expression; };
			</synopsis>
			<para>An expression may contain parentheses, the boolean operators "and", "or" and
				"not", and any of the functions listed in <xref linkend="filterfunc"/>. </para>
			<example>
				<title>A filter statement finding the messages containing the word 'deny' coming
					from the host 'foo'</title>
				<synopsis>
					filter f_blurp_deny { host("foo") and match("deny"); };
				</synopsis>
			</example>
			<para>For a complete description on the above functions, see <xref
					linkend="reference_filters"/>. </para>
			<para>In earlier revisions of syslog-ng there was a special filter identifier,
				"DEFAULT", which matched all not-yet-matched messages. This could make your
				configuration much simpler and easier to manage. This feature was removed in
				syslog-ng 1.5.x, and a more powerful idea was introduced. For more details consult
					<xref linkend="logpath"/>. </para>
		</sect1>
		<sect1 id="destinations">
			<title>Destinations</title>
			<para>A destination is where a log is sent if the filtering rules match. Similarly to
				sources, destinations are comprised of one or more drivers, each defining how
				messages are handled. Destinations can be declared in the configuration file via a
				destination statement using the syntax
				below:<synopsis>
					destination &lt;identifier&gt; { destination-driver(params); destination-driver(params); ... };
				</synopsis>
			</para>
			<note>
				<para>The list of drivers may be empty: in this case all messages sent to the
					destination are discarded. This is equivalent to omitting the destination from
					the log statement.</para>
			</note>
			<table>
				<title>Available destination drivers in syslog-ng</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>file()</entry>
							<entry>Writes messages to the specified file.</entry>
						</row>
						<row>
							<entry>fifo(), pipe()</entry>
							<entry>Writes messages to the specified named pipe.</entry>
						</row>
						<row>
							<entry>unix-stream()</entry>
							<entry>Sends messages to the specified unix socket in
									<parameter>SOCK_STREAM</parameter> style (Linux).</entry>
						</row>
						<row>
							<entry>unix-dgram()</entry>
							<entry>Sends messages to the specified unix socket in
									<parameter>SOCK_DGRAM</parameter> style (BSD).</entry>
						</row>
						<row>
							<entry>tcp()</entry>
							<entry>Sends messages to the specified host and TCP port.</entry>
						</row>
						<row>
							<entry>udp()</entry>
							<entry>Sends messages to the specified host and UDP port.</entry>
						</row>
						<row>
							<entry>tcp6()</entry>
							<entry>Sends messages to the specified host and TCP port over
							IPv6.</entry>
						</row>
						<row>
							<entry>udp6()</entry>
							<entry>Sends messages to the specified host and UDP port over
							IPv6.</entry>
						</row>
						<row>
							<entry>usertty()</entry>
							<entry>Sends messages to the specified user's terminal if logged
							in.</entry>
						</row>
						<row>
							<entry>program()</entry>
							<entry>Forks and launches the specified program, and sends messages to
								its standard input.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			<para>For detailed description of the supported drivers, see <xref
					linkend="reference_destinationdrivers"/>. </para>
		</sect1>
		<sect1 id="templates">
			<title>Template objects</title>
			<para>syslog-ng 2.0 allows you to define common templates, and refer to them from every
				object requiring a template. For example:</para>
			<para>
				<synopsis>
          template t_filetmpl { template("$ISODATE $HOST $MSG\n"); template_escape(no)); };
          
          destination d_file { file("/var/log/messages" template(t_filetmpl); };
        </synopsis>
				Templates can reference one or more macros as described in <xref linkend="macros"/>. </para>
			<note>
				<para>Previous versions of syslog-ng required template formats to be defined for
					every destination.</para>
			</note>
		</sect1>
		<sect1 id="logpath">
			<title>Log paths</title>
			<para>The previous chapters described how to define sources, filters and destinations.
				These components have to be connected together using log statements. The syntax of
				log statements is described below:</para>
			<synopsis>
				log { source(s1); source(s2); ... 
				filter(f1); filter(f2); ... 
				destination(d1); destination(d2); ... 
				flags(flag1[, flag2...]); };
			</synopsis>
			<para>Any message coming from any of the listed sources, matching all the filters is
				sent to all listed destinations. Log statements are processed in the order they
				appear in the configuration file. </para>
			<para>By default, all matching log statements are processed, therefore a single log
				message might be sent to the same destination several times, provided the
				destination is listed in several log statements. </para>
			<para>This default behavior can be changed using the <parameter>flags()</parameter>
				parameter. <table id="logflags">
					<title>Log statement flags</title>
					<tgroup cols="2">
						<thead>
							<row>
								<entry>Flag</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>final</entry>
								<entry>This flag means that the processing of log statements ends
									here. Note that this does not necessarily mean that matching
									messages will be stored only once, as there can be matching log
									statements processed prior the current one. </entry>
							</row>
							<row>
								<entry>fallback</entry>
								<entry>This flag makes a log statement 'fallback'. Being a fallback
									statement means that only messages not matching any
									'non-fallback' log statements will be dispatched. </entry>
							</row>
							<row>
								<entry>catchall</entry>
								<entry>This flag means that the source of the message is ignored,
									only the filters are taken into account when matching
								messages.</entry>
							</row>
							<row>
								<entry>flow-control</entry>
								<entry>Specifies that this log path should be flow controlled,
									meaning that syslog-ng will stop reading messages from sources
									feeding destinations through this log statement if the
									destinations are not able to process the messages at the
									required speed. If disabled, syslog-ng will drop messages if the
									destination queues are full. If enabled, syslog-ng will only
									drop messages if the destination queues/window sizes are
									improperly sized. </entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</para>

		</sect1>
		<sect1 id="options">
			<title>Options</title>
			<para>There are several options that can modify the behavior of
				<emphasis>syslog-ng</emphasis>. For an exact list of possible options see <xref
					linkend="reference_options"/>. Each option may have parameters, similarly to
				driver specifications. The general syntax is:</para>
			<synopsis>
				options { option1(params); option2(params); ... };
			</synopsis>
		</sect1>
	</chapter>

	<chapter id="reference">
		<title>Reference</title>
		<para>This chapter documents the drivers and options that can be used in the configuration
			file. </para>
		<sect1 id="reference_sourcedrivers">
			<title>Source drivers</title>
			<para>The following drivers may be used in source statements, as described in <xref
					linkend="sources"/>. The option <link linkend="reference_options">
					<parameter>log_msg_size()</parameter>
				</link> is available in each source: it specifies the maximum length of incoming log
				messages in bytes. If not specified, the value of the global option is used (see
					<xref linkend="reference_options"/>). </para>
			<para>Some parameters affecting message parsing are common for all sources: <table
					id="sourcecommonopts">
					<title>Common options for source drivers</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Default</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>flags()</entry>
								<entry>set of [no-parse,kernel]</entry>
								<entry>empty set</entry>
								<entry>Specifies log parsing flags. <parameter>no-parse</parameter>
									completely disables syslog message parsing and processes the
									complete line as the message part of a syslog message. Other
									information (timestamp, host, etc.) is added automatically. This
									flag is useful for parsing files not complying to the syslog
									format. <parameter>kernel</parameter> makes the source default
									to the <parameter>LOG_KERN | LOG_CRIT</parameter> priority if
									not specified otherwise. </entry>
							</row>
							<row>
								<entry>log_msg_size()</entry>
								<entry>number</entry>
								<entry>The value specified by the global
									<parameter>log_msg_size()</parameter> option, which defaults to
										<parameter>8192</parameter>.</entry>
								<entry>Specifies the maximum length of incoming log messages. Uses
									the value of the <link linkend="reference_options">global
									option</link> if not specified. </entry>
							</row>
							<row>
								<entry>log_iw_size()</entry>
								<entry>number</entry>
								<entry>100</entry>
								<entry>The size of the initial window, this value is used during
									flow control.</entry>
							</row>
							<row>
								<entry>log_fetch_limit()</entry>
								<entry>number</entry>
								<entry>The value specified by the global <link
										linkend="reference_options">
										<parameter>log_fetch_limit()</parameter>
									</link> option, which defaults to <parameter>10</parameter>.</entry>
								<entry>The maximum number of messages fetched from a source during a
									single poll loop. The destination queues might fill up before
									flow-control could stop reading if
									<parameter>log_fetch_limit()</parameter> is too high. </entry>
							</row>
							<row>
								<entry>log_prefix()</entry>
								<entry>string</entry>
								<entry/>
								<entry>A string prepended to every log message. It can be used to
									prepend an arbitrary string to any log source, though it is most
									commonly used for adding <parameter>kernel:</parameter> to the
									kernel messages on Linux. </entry>
							</row>
							<row>
								<entry>pad_size()</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies input padding. Some operating systems (such as
									HP-UX) pad all 0 messages to block boundary. This option can be
									used to specify the block size. (HP-UX uses 2048 bytes).
									Syslog-ng will pad reads from the associated device to the
									number of bytes set in <parameter>pad_size()</parameter>. Mostly
									used on HP-UX where <filename>/dev/log</filename> is a named
									pipe and every write is padded to 2048 bytes. </entry>
							</row>
							<row>
								<entry>follow_freq()</entry>
								<entry>number</entry>
								<entry>-1</entry>
								<entry>Indicates that the source should be checked periodically
									instead of being polled. This is useful for files which always
									indicate readability, even though no new lines were appended. If
									this value is higher than zero, syslog-ng will not attempt to
									use <parameter>poll()</parameter> on the file, but checks
									whether the file changed every time the
									<parameter>follow_freq()</parameter> interval (in seconds) has
									elapsed. </entry>
							</row>
							<row>
								<entry>time_zone()</entry>
								<entry>timezone in the form +/-HH:MM</entry>
								<entry/>
								<entry>The default timezone for messages read from the source.
									Applies only if no timezone is specified within the message
									itself. </entry>
							</row>
							<row>
								<entry>optional()</entry>
								<entry>yes or no</entry>
								<entry/>
								<entry>Instruct syslog-ng to ignore the error if a specific source
									cannot be initialized. No other attempts to initialize the
									source will be made until the configuration is reloaded. This
									option currently applies to the <parameter>pipe()</parameter>,
										<parameter>unix-dgram</parameter>, and
										<parameter>unix-stream</parameter> drivers.</entry>
							</row>
							<row>
								<entry>keep_timestamp()</entry>
								<entry>yes or no</entry>
								<entry>yes</entry>
								<entry>Specifies whether syslog-ng should accept the timestamp
									received from the peer. If disabled, the time of reception will
									be used instead. </entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</para>
			<sect2>
				<title>internal()</title>
				<para>All internally generated messages "come" from this special source. To collect
					warnings, errors and notices from <emphasis>syslog-ng</emphasis> itself, include
					this source in one of your source statements. </para>
				<synopsis>
					Declaration: internal()
				</synopsis>
				<para><emphasis>syslog-ng</emphasis> will issue a warning upon startup if this
					driver is not referenced. </para>
				<example>
					<title>Using the internal() driver</title>
					<synopsis>
						source s_local { internal(); };
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>unix-stream() and unix-dgram()</title>
				<para>These two drivers behave similarly: they open the given
					<parameter>AF_UNIX</parameter> socket and start listening on it for messages.
						<parameter>unix-stream()</parameter> is primarily used on Linux and uses
						<parameter>SOCK_STREAM</parameter> semantics (connection oriented, no
					messages are lost); while <parameter>unix-dgram()</parameter> is used on BSDs
					and uses <parameter>SOCK_DGRAM</parameter> semantics: this may result in lost
					local messages if the system is overloaded. </para>
				<para>To avoid denial of service attacks when using connection-oriented protocols,
					the number of simultaneously accepted connections should be limited. This can be
					achieved using the <parameter>max-connections()</parameter> parameter. The
					default value of this parameter is quite strict, you might have to increase it
					on a busy system. </para>
				<para>Both unix-stream and unix-dgram have a single required positional argument,
					specifying the filename of the socket to create, and several optional
					parameters. </para>
				<note>
					<para><parameter>syslogd</parameter> on Linux originally used
							<parameter>SOCK_STREAM</parameter> sockets but this was changed in some
						distributions to <parameter>SOCK_DGRAM</parameter> at around 1999. The
						change was a fix to a possible DoS problem, however, this might not have
						been a proper solution. On Linux you can choose to use whichever driver you
						like as syslog clients automatically detect the socket type being used. </para>
					<synopsis>
						Declaration: 
						unix-stream(filename [options]);
						unix-dgram(filename [options]); 
					</synopsis>
				</note>
				<para>The following options can be specified for these divers:</para>
				<table>
					<title>Available options for unix-stream() and unix-dgram()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Description</entry>
								<entry>Default</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>owner()</entry>
								<entry>string</entry>
								<entry>Set the uid of the socket.</entry>
								<entry>root</entry>
							</row>
							<row>
								<entry>group()</entry>
								<entry>string</entry>
								<entry>Set the gid of the socket.</entry>
								<entry>root</entry>
							</row>
							<row>
								<entry>perm()</entry>
								<entry>number</entry>
								<entry>Set the permission mask. For octal numbers prefix the number
									with '0', e.g.: use 0755 for rwxr-xr-x.</entry>
								<entry>0666</entry>
							</row>
							<row>
								<entry>keep-alive()</entry>
								<entry>yes or no</entry>
								<entry>Selects whether to keep connections open when
										<emphasis>syslog-ng</emphasis> is restarted; can be used
									only with <parameter>unix-stream()</parameter>. </entry>
								<entry>yes</entry>
							</row>
							<row>
								<entry>max-connections()</entry>
								<entry>number</entry>
								<entry>Limits the number of simultaneously open connections. Can be
									used only with <parameter>unix-stream()</parameter>.</entry>
								<entry>10</entry>
							</row>
							<row>
								<entry>so_broadcast</entry>
								<entry>yes or no</entry>
								<entry>no</entry>
								<entry>This option controls the <parameter>SO_BROADCAST</parameter>
									socket option required to make syslog-ng send messages to a
									broadcast address. See the <command>socket(7)</command> manual
									page for details. </entry>
							</row>
							<row>
								<entry>so_rcvbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket receive buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>so_sndbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket send buffer in bytes.
								</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the unix-stream() and unix-dgram() drivers</title>
					<synopsis>
						# source declaration on Linux
						source s_stream { unix-stream("/dev/log" max-connections(10)); };
						
						# source declaration on BSD
						source s_dgram { unix-dgram("/var/run/log"); };						
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>tcp(), tcp6(), udp() and udp6()</title>
				<para>These drivers enable to receive messages from the network. As the name of the
					drivers implies, both UDP and TCP can be used to transport messages. The
						<parameter>tcp6()</parameter> and <parameter>udp6()</parameter> use the IPv6
					network protocol.</para>
				<para>UDP is a simple datagram oriented protocol, which provides "best effort
					service" to transfer messages between hosts. It may lose messages, and no
					attempt is made at the protocol level to retransmit such lost messages. The
						<emphasis>syslog</emphasis> protocol traditionally uses UDP. </para>
				<para>TCP provides connection-oriented service, which basically means a
					flow-controlled message pipeline. In this pipeline each message is acknowledged,
					and retransmission is done for lost packets. Generally it is safer to use TCP,
					because lost connections can be detected, and no messages get lost, assuming
					that the TCP connection does not break. When a TCP connection is broken the
					'in-transit' messages that were sent by syslog-ng but not yet received on the
					other side are lost. (Basically these messages are still sitting in the socket
					buffer of the sending host and syslog-ng has no information about the fate of
					these messages). </para>
				<para>The <parameter>tcp()</parameter> and <parameter>udp()</parameter> drivers do
					not require any positional parameters. By default they bind to
						<parameter>0.0.0.0:514</parameter>, which means that
					<emphasis>syslog-ng</emphasis> will listen on all available interfaces, port
					514. To limit accepted connections to only one interface, use the
						<parameter>localip()</parameter> parameter as described below. </para>
				<note>
					<para>The tcp port 514 is reserved for use with <command>rshell</command>, so
						select a different port if <emphasis>syslog-ng</emphasis> and
							<command>rshell</command> is used at the same time. </para>
				</note>
				<para>If you specify a multicast bind address to <parameter>udp()</parameter> and
						<parameter>udp6()</parameter>, syslog-ng will automatically join the
					necessary multicast group. TCP does not support multicasting. </para>
				<synopsis>
					Declaration:
					tcp([options]);
					udp([options]);
				</synopsis>
				<para>The following options are valid for <parameter>tcp()</parameter>,
						<parameter>tcp6()</parameter>, <parameter>udp()</parameter>, and
						<parameter>udp6()</parameter>
				</para>
				<table>
					<title>Available options for tcp(), tcp6(), udp(), and udp6()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Description</entry>
								<entry>Default</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>ip() or localip()</entry>
								<entry>string</entry>
								<entry>The IP address to bind to. Note that this is not the address
									where messages are accepted from. </entry>
								<entry>0.0.0.0</entry>
							</row>
							<row>
								<entry>port() or localport()</entry>
								<entry>number</entry>
								<entry>The port number to bind to.</entry>
								<entry>514</entry>
							</row>
							<row>
								<entry>keep-alive()</entry>
								<entry>yes or no</entry>
								<entry>Available for <parameter>tcp()</parameter> only; specifies
									whether connections should be closed upon the receipt of a
									SIGHUP signal. </entry>
								<entry>yes</entry>
							</row>
							<row>
								<entry>tcp-keep-alive()</entry>
								<entry>yes or no</entry>
								<entry>Available for <parameter>tcp()</parameter> only; specifies
									whether TCP keep alive messages using the SO_KEEPALIVE socket
									option should be enabled. </entry>
								<entry>no</entry>
							</row>
							<row>
								<entry>max-connections()</entry>
								<entry>number</entry>
								<entry>Specifies the maximum number of simultaneous connections.</entry>
								<entry>10</entry>
							</row>
							<row>
								<entry>so_broadcast</entry>
								<entry>yes or no</entry>
								<entry>no</entry>
								<entry>This option controls the <parameter>SO_BROADCAST</parameter>
									socket option required to make syslog-ng send messages to a
									broadcast address. See the <command>socket(7)</command> manual
									page for details. </entry>
							</row>
							<row>
								<entry>so_rcvbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket receive buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>so_sndbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket send buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>ip_ttl</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the Time-To-Live value of outgoing packets.
								</entry>
							</row>
							<row>
								<entry>ip_tos</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the Type-of-Service value of outgoing packets.
								</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the udp() and tcp() drivers</title>
					<synopsis>
						source s_tcp { tcp(ip(127.0.0.1) port(1999) max-connections(10)); };
						source s_udp { udp(); };
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>file()</title>
				<para>Usually the kernel presents its messages in a special file
						(<parameter>/dev/kmsg</parameter> on BSDs, <parameter>/proc/kmsg</parameter>
					on Linux), so to read such special files the <parameter>file()</parameter>
					driver is needed. Please note that this driver cannot follow a file like
						<command>tail -f</command> does. To feed a growing logfile into
						<emphasis>syslog-ng</emphasis> (e.g.: an HTTP
					<filename>access.log</filename>), use a script like this: </para>
				<example>
					<title>Script to feed a growing logfile into syslog-ng</title>
					<synopsis>
						#!/bin/sh
						tail -f logfile | logger -p local4.info
					</synopsis>
				</example>
				<para>The file driver has a single required parameter specifying the file to open,
					and has only the common source specific options as specified in <xref
						linkend="sourcecommonopts"/>. </para>
				<synopsis>
					Declaration:
					file(filename);
				</synopsis>
				<example>
					<title>Using the file() driver</title>
					<synopsis>
						source s_file { file("/proc/kmsg" log_prefix("kernel: ")); };
					</synopsis>
				</example>
				<note>
					<para>On Linux, the <parameter>klogd</parameter> daemon can be used in addition
						to <emphasis>syslog-ng</emphasis> to read kernel messages and forward them
						to <emphasis>syslog-ng</emphasis>. <parameter>klogd</parameter> used to
						preprocess kernel messages to resolve symbols etc., but as this is
						deprecated by <parameter>ksymoops</parameter> there is really no point in
						running both <parameter>klogd</parameter> and <emphasis>syslog-ng</emphasis>
						in parallel. Also note that running two processes reading
							<filename>/proc/kmsg</filename> at the same time might result in
						dead-locks. </para>
				</note>
			</sect2>
			<sect2>
				<title>pipe()</title>
				<para>The pipe driver opens a named pipe with the specified name and listens for
					messages. It is used as the native message delivery protocol on HP-UX. </para>
				<para>The pipe driver has a single required parameter, specifying the filename of
					the pipe to open. It has only the common source specific options as specified in
						<xref linkend="sourcecommonopts"/>. </para>
				<para>Pipe is very similar to the <parameter>file()</parameter> driver, but there
					are a few differences, for example <parameter>pipe()</parameter> opens its
					argument in read-write mode, therefore it is not recommended to be used on
					special files like <filename>/proc/kmsg</filename>.</para>
				<warning>
					<para>It is not recommended to use <parameter>pipe()</parameter> on anything
						else than real pipes. </para>
				</warning>
				<synopsis>
					Declaration:
					pipe(filename);
				</synopsis>
				<note>
					<para>You have to create this pipe using <command>mkfifo(1)</command>. </para>
				</note>
				<example>
					<title>Using the pipe() driver</title>
					<synopsis>
						source s_pipe { pipe("/dev/log" pad_size(2048)); };
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>sun-streams() driver</title>
				<para>Solaris uses its <parameter>STREAMS</parameter> framework to send messages to
					the <parameter>syslogd</parameter> process. <emphasis>syslog-ng</emphasis> has
					to be compiled with this driver enabled for <parameter>sun-streams()</parameter>
					to be usable (see <command>./configure --help</command>). </para>
				<para>Newer versions of Solaris (2.5.1 and above), use a new IPC in addition to
						<parameter>STREAMS</parameter>, called door to confirm the delivery of a
					message. <emphasis>syslog-ng</emphasis> supports this new IPC mechanism via the
						<parameter>door()</parameter> option (see below). </para>
				<para>The <parameter>sun-streams()</parameter> driver has a single required argument
					specifying the <parameter>STREAMS</parameter> device to open, and the
						<parameter>door()</parameter> option.</para>
				<example>
					<title>Using the sun-streams() driver</title>
					<synopsis>
						source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door"); };
					</synopsis>
				</example>
				<table>
					<title>Available options for sun-streams</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Description</entry>
								<entry>Default</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>door()</entry>
								<entry>string</entry>
								<entry>Specifies the filename of a door to open, needed on Solaris
									above 2.5.1. </entry>
								<entry>none</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
			</sect2>
		</sect1>
		<sect1 id="reference_destinationdrivers">
			<title>Destination drivers</title>
			<para>Destination drivers output log messages to somewhere outside
				<emphasis>syslog-ng</emphasis>: a file or a network socket. </para>
			<para>Some of the parameters affecting message formatting and sending are common for all
				destinations.</para>
			<table id="destcommonopts">
				<title>Common options for destination drivers</title>
				<tgroup cols="4">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Type</entry>
							<entry>Default</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>flags()</entry>
							<entry/>
							<entry>empty set</entry>
							<entry> </entry>
						</row>
						<row>
							<entry>log_fifo_size()</entry>
							<entry>number</entry>
							<entry>Use global setting. </entry>
							<entry>The number of entries in the output fifo. </entry>
						</row>

						<row>
							<entry>fsync()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Forces an <parameter>fsync()</parameter> call on the destination
								fd after each write. Note: this may seriously degrade
							performance.</entry>
						</row>

						<row>
							<entry>sync_freq()</entry>
							<entry>number</entry>
							<entry>Use global setting. </entry>
							<entry>This setting is an obsolete alias of the
								<parameter>flush_lines()</parameter> option. </entry>
						</row>

						<row>
							<entry>flush_lines()</entry>
							<entry>number</entry>
							<entry>Use global setting. </entry>
							<entry>Specifies how many lines are flushed to a destination at a time.
								Syslog-ng waits for this number of lines to accumulate and sends
								them off in a single batch. Setting this number high increases
								throughput as fully filled frames are sent to the network, but also
								increases message latency. The latency can be limited by the use of
								the <parameter>flush_timeout</parameter> option. </entry>
						</row>

						<row>
							<entry>flush_timeout()</entry>
							<entry>time in milliseconds</entry>
							<entry>Use global setting. </entry>
							<entry>Specifies the time syslog-ng waits for lines to accumulate in its
								output buffer. See the <parameter>flush_lines</parameter> option for
								more information. </entry>
						</row>

						<row>
							<entry>template()</entry>
							<entry>string</entry>
							<entry>A format conforming to the default logfile format. </entry>
							<entry>Specifies a template defining the logformat to be used in the
								destination. Macros are described in <xref linkend="macros"/>.
								Please note that for network destinations it might not be
								appropriate to change the template as it changes the on-wire format
								of the syslog protocol which might not be tolerated by stock syslog
								receivers (like <parameter>syslogd</parameter> or syslog-ng itself).
								For network destinations make sure the receiver can cope with the
								custom format defined. </entry>
						</row>
						<row>
							<entry>template_escape()</entry>
							<entry>yes or no</entry>
							<entry>yes</entry>
							<entry>Turns on escaping <parameter>'</parameter> and
								<parameter>"</parameter> in templated output files. This is useful
								for generating SQL statements and quoting string contents so that
								parts of the log message are not interpreted as commands to the SQL
								server.</entry>
						</row>
						<row>
							<entry>timezone()</entry>
							<entry>timezone offset in seconds</entry>
							<entry>unspecified </entry>
							<entry>Convert timestamps to the timezone specified by this option. If
								this option is not set then the original timezone information in the
								message is used. </entry>
						</row>
						<row>
							<entry>ts_format()</entry>
							<entry>rfc3164, bsd, rfc3339, iso</entry>
							<entry>rfc3164</entry>
							<entry>Override the global timestamp format (set in the global
									<parameter>ts_format()</parameter> parameter) for the specific
								destination. </entry>
						</row>
						<row>
							<entry>frac_digits()</entry>
							<entry>number</entry>
							<entry>0</entry>
							<entry><emphasis>syslog-ng</emphasis> can store fractions of a second in
								the timestamps. <parameter>frac_digits()</parameter> specifies the
								number of digits stored. The digits storing the fractions are padded
								by zeros if the original timestamp of the message specifies only
								seconds. Fractions can always be stored for the time the message was
								received.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
			<note>
				<para>The <parameter>usertty</parameter> destination does not support
				templates.</para>
			</note>
			<sect2>
				<title>file()</title>
				<para>The file driver is one of the most important destination drivers in
						<emphasis>syslog-ng</emphasis>. It allows to output messages to the
					specified file, or to a set of files. </para>
				<para>The destination filename may include macros which get expanded when the
					message is written, thus a simple <parameter>file()</parameter> driver may crete
					several files. For more information on available macros see <xref
						linkend="macros"/>. </para>
				<para>If the expanded filename refers to a directory which does not exist, it will
					be created depending on the <parameter>create_dirs()</parameter> setting (both
					global and a per destination option).</para>
				<warning>
					<para>Since the state of each created file must be tracked by
							<emphasis>syslog-ng</emphasis>, it consumes some memory for each file.
						If no new messages are written to a file within 60 seconds (controlled by
						the <parameter>time_reap</parameter> global option), it is closed, and its
						state is freed. </para>
					<para>Exploiting this, a DoS attack can be mounted against the system. If the
						number of possible destination files and its needed memory is more than the
						amount available on the logserver. </para>
					<para>The most suspicious macro is <parameter>$PROGRAM</parameter>, where the
						number of possible variations is quite high, so in untrusted environments
							<parameter>$PROGRAM</parameter> should not be used. </para>
				</warning>
				<para>Apart from the common destination options described in <xref
						linkend="destcommonopts"/> the <parameter>file()</parameter> destination has
					the following options:</para>
				<table>
					<title>Available options for file()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Default</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<!--							<row>
								<entry>encrypt()</entry>
								<entry>yes or no</entry>
								<entry>Use global setting. </entry>
								<entry>Encrypt the resulting file. NOTE:  not implemented yet. </entry>
							</row>-->
							<!--							<row>
								<entry>compress()</entry>
								<entry>yes or no</entry>
								<entry>Use global setting. </entry>
								<entry>Compress the resulting logfile using zlib. NOTE: not
									implemented yet. </entry>
							</row>-->
							<row>
								<entry>owner()</entry>
								<entry>string</entry>
								<entry>Set the owner of the created file to the one specified. </entry>
								<entry>root</entry>
							</row>
							<row>
								<entry>group()</entry>
								<entry>string</entry>
								<entry>Set the group of the created file to the one specified. </entry>
								<entry>root</entry>
							</row>
							<row>
								<entry>perm()</entry>
								<entry>number</entry>
								<entry>The permission mask of the file if it is created by
										<emphasis>syslog-ng</emphasis>. For octal numbers prefix the
									number with '0', e.g.: use 0755 for rwxr-xr-x. </entry>
								<entry> 0600 </entry>
							</row>
							<row>
								<entry>create_dirs()</entry>
								<entry>yes or no</entry>
								<entry>Enable creating non-existing directories. </entry>
								<entry> no </entry>
							</row>
							<row>
								<entry>dir_perm()</entry>
								<entry>number</entry>
								<entry>The permission mask of directories created by
										<emphasis>syslog-ng</emphasis>. Log directories are only
									created if a file after macro expansion refers to a non-existing
									directory, and directory creation is enabled (see the
										<parameter>create_dirs()</parameter> option below). For
									octal numbers prefix the number with '0', e.g.: use 0755 for
									rwxr-xr-x.</entry>
								<entry> 0600 </entry>
							</row>
							<row>
								<entry>dir_owner()</entry>
								<entry>string</entry>
								<entry>The owner of directories created by
									<emphasis>syslog-ng</emphasis>. </entry>
								<entry> root </entry>
							</row>
							<row>
								<entry>dir_group()</entry>
								<entry>string</entry>
								<entry>The group of directories created by
									<emphasis>syslog-ng</emphasis>. </entry>
								<entry> root </entry>
							</row>
							<row>
								<entry>remove_if_older()</entry>
								<entry>number</entry>
								<entry>If set to a value higher than 0, before writing to a file,
									syslog-ng checks whether this file is older than the specified
									amount of time (specified in seconds). If so, it removes the
									existing file and the line to be written is the first line of a
									new file having the same name. In combination with e.g.: the
										<parameter>$WEEKDAY</parameter> macro, this can be used for
									simple log rotation, in case not all history has to be kept. </entry>
								<entry>Never remove existing files; use append instead ( = 0).
								</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the file() driver</title>
					<synopsis>
						destination d_file { file("/var/log/messages" ); };
					</synopsis>
				</example>
				<example>
					<title>Using the file() driver with macros in the file name and a template for
						the message</title>
					<synopsis>
						destination d_file {
						file("/var/log/$YEAR.$MONTH.$DAY/messages"
						template("$HOUR:$MIN:$SEC $TZ $HOST [$LEVEL] $MSG $MSG\n")
						template_escape(no)
						);
						};
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>pipe()</title>
				<para>This driver sends messages to a named pipe like
					<filename>/dev/xconsole</filename>. </para>
				<para>The pipe driver has a single required parameter, specifying the filename of
					the pipe to open. </para>
				<synopsis>
					Declaration:
					pipe(filename);
				</synopsis>
				<note>
					<para>You have to create this pipe using <command>mkfifo(1)</command>. </para>
				</note>
				<para>Apart from the common destination options described in <xref
						linkend="destcommonopts"/> the <parameter>pipe()</parameter> destination has
					the following options:</para>
				<table>
					<title>Available options for pipe()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Description</entry>
								<entry>Default</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>owner()</entry>
								<entry>string</entry>
								<entry>Set the owner of the pipe to the one specified. </entry>
								<entry> root </entry>
							</row>
							<row>
								<entry>group()</entry>
								<entry>string</entry>
								<entry>Set the group of the pipe to the one specified. </entry>
								<entry> root </entry>
							</row>
							<row>
								<entry>perm()</entry>
								<entry>number</entry>
								<entry>The permission mask of the pipe. For octal numbers prefix the
									number with '0', e.g.: use 0755 for rwxr-xr-x. </entry>
								<entry> 0600 </entry>
							</row>
							<row>
								<entry>template()</entry>
								<entry>string</entry>
								<entry>Specifies a template which defines the logformat to be used.
									Possible macros are the same as for the
									<parameter>file()</parameter> destination. </entry>
								<entry>A format conforming to the default logfile format. </entry>
							</row>
							<row>
								<entry>template_escape()</entry>
								<entry>yes or no</entry>
								<entry>Turns on escaping ' and " in templated output files. This is
									useful for generating SQL statements and quoting string contents
									so that parts of the log message are not interpreted as commands
									to the SQL server.</entry>
								<entry> yes </entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the pipe() driver</title>
					<synopsis>
						destination d_pipe { pipe("/dev/xconsole"); };
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>unix-stream() &amp; unix-dgram()</title>
				<para>This driver sends messages to a unix socket in either
					<parameter>SOCK_STREAM</parameter> or <parameter>SOCK_DGRAM</parameter> mode. </para>
				<para>Both drivers have a single required argument specifying the name of the socket
					to connect to. </para>
				<synopsis>
					Declaration: 
					unix-stream(filename [options]);
					unix-dgram(filename [options]); 
				</synopsis>
				<para>Apart from the common destination options described in <xref
						linkend="destcommonopts"/> the <parameter>unix-stream()</parameter> and
						<parameter>unix-dgram()</parameter> destinations has the following options:</para>
				<table>
					<title>Available options for unix-stream() and unix-dgram()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Default</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>so_broadcast</entry>
								<entry>yes or no</entry>
								<entry>no</entry>
								<entry>This option controls the <parameter>SO_BROADCAST</parameter>
									socket option required to make syslog-ng send messages to a
									broadcast address. See the <command>socket(7)</command> manual
									page for details. </entry>
							</row>
							<row>
								<entry>so_rcvbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket receive buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>so_sndbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket send buffer in bytes.
								</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the unix-stream() driver</title>
					<synopsis>
						destination d_unix_stream { unix-stream("/var/run/logs"); };
					</synopsis>
				</example>
			</sect2>
			<sect2>
				<title>udp(), udp6(), tcp() and tcp6()</title>
				<para>This driver sends messages to another host on the local intranet or internet
					using either UDP or TCP protocol. The <parameter>tcp6()</parameter> and
						<parameter>udp6()</parameter> drivers use the IPv6 network protocol.</para>
				<para>Both drivers have a single required argument specifying the destination host
					address, where messages should be sent, and several optional parameters. Note
					that this differs from source drivers, where local bind address is implied, and
					none of the parameters are required. </para>
				<para><parameter>udp()</parameter> and <parameter>udp6()</parameter> automatically
					send multicast packets if a multicast destination address is specified.
						<parameter>tcp()</parameter> and <parameter>tcp6()</parameter> do not
					support multicasting.</para>
				<synopsis>
					Declaration:
					tcp(host [options]);
					udp(host [options]);
					tcp6(host [options]);
					udp6(host [options]);					
				</synopsis>
				<para>Apart from the common destination options described in <xref
						linkend="destcommonopts"/> these destinations have the following options:</para>
				<table>
					<title>Available options for udp(), udp6(), tcp() and tcp6()</title>
					<tgroup cols="4">
						<thead>
							<row>
								<entry>Name</entry>
								<entry>Type</entry>
								<entry>Default</entry>
								<entry>Description</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>localip()</entry>
								<entry>string</entry>
								<entry>The IP address to bind to before connecting to target. </entry>
								<entry>0.0.0.0</entry>
							</row>
							<row>
								<entry>localport()</entry>
								<entry>number</entry>
								<entry>The port number to bind to.</entry>
								<entry>0</entry>
							</row>
							<row>
								<entry>port() or destport()</entry>
								<entry>number</entry>
								<entry>The port number to connect to.</entry>
								<entry>514</entry>
							</row>
							<row>
								<entry>spoof_source</entry>
								<entry>yes or no</entry>
								<entry>Enables source address spoofing. This means that the host
									running <emphasis>syslog-ng</emphasis> generates UDP packets
									with the source IP address matching the original sender of the
									message. It is useful when you want to perform some kind of
									preprocessing via syslog-ng then forward messages to your
									central log management solution with the source address of the
									original sender. This option only works for UDP destinations
									though the original message can be received by TCP as well. This
									option is only available if <emphasis>syslog-ng</emphasis> was
									compiled using the <parameter>--enable-spoof-source</parameter>
									configure option. </entry>
								<entry>no</entry>
							</row>
							<row>
								<entry>so_broadcast</entry>
								<entry>yes or no</entry>
								<entry>no</entry>
								<entry>This option controls the <parameter>SO_BROADCAST</parameter>
									socket option required to make syslog-ng send messages to a
									broadcast address. See the <command>socket(7)</command> manual
									page for details. </entry>
							</row>
							<row>
								<entry>so_rcvbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket receive buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>so_sndbuf</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the size of the socket send buffer in bytes.
								</entry>
							</row>
							<row>
								<entry>ip_ttl</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the Time-To-Live value of outgoing packets.
								</entry>
							</row>
							<row>
								<entry>ip_tos</entry>
								<entry>number</entry>
								<entry>0</entry>
								<entry>Specifies the Type-of-Service value of outgoing packets.
								</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				<example>
					<title>Using the tcp() driver</title>
					<synopsis>
						destination d_tcp { tcp("10.1.2.3" port(1999); localport(999)); };
					</synopsis>
				</example>
			</sect2>

			<sect2>
				<title>usertty()</title>
				<para>This driver writes messages to the terminal of a logged-in user. </para>
				<para>The <parameter>usertty()</parameter> driver has a single required argument,
					specifying a username who should receive a copy of matching messages. </para>
				<synopsis>
					Declaration: 
					usertty(username);
				</synopsis>
				<para><parameter>usertty()</parameter> has only the common destination options
					described in <xref linkend="destcommonopts"/>.</para>
				<note>
					<para>The <parameter>usertty()</parameter> destination does not support
						templates.</para>
				</note>
				<example>
					<title>Using the usertty() driver</title>
					<synopsis>
						destination d_usertty { usertty("root"); };
					</synopsis>
				</example>
			</sect2>

			<sect2>
				<title>program()</title>
				<para>This driver executes the specified program with the specified arguments and
					sends messages to the standard input (<parameter>stdin</parameter>) of the
					child. </para>
				<para>The <parameter>program()</parameter> driver has a single required parameter,
					specifying a program name to start. The program is executed with the help of the
					current shell, so the command may include both file patterns and I/O
					redirection, they will be processed. </para>
				<synopsis>
					Declaration: 
					program(commandtorun);
				</synopsis>
				<note>
					<para>Syslog-ng 1.6 executed the program once at startup, and kept it running
						until SIGHUP or exit. The reason was to prevent starting up a large number
						of programs for messages, which would have enabled an easy DoS attack. </para>
					<para>Syslog-ng 2.0 on the other hand restarts the program if it exits, mainly
						for reliability reasons. However it is not recommended to launch programs
						for single messages as that might easily cause a DoS for the system. </para>
				</note>

				<para>The program destination supports all common destination options described in
						<xref linkend="destcommonopts"/>.
                                      The default message format that is
                                      sent to the program matches the BSD syslog protocol, e.g. it includes 
                                      the priority value in addition to the format used in logfiles.</para>
				<example>
					<title>Using the program() destination driver</title>
					<synopsis>
						destination d_prg { program("/bin/cat >/dev/null"); };
					</synopsis>
				</example>
			</sect2>
		</sect1>
		<sect1 id="reference_filters">
			<title>Filter functions</title>
			<para>The following functions may be used in the filter statement, as described in <xref
					linkend="filters"/>.</para>
			<table id="filterfunc">
				<title>Available filter functions in syslog-ng</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Synopsis</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>facility</entry>
							<entry>facility(facility[,facility])</entry>
							<entry>Match messages having one of the listed facility code. An
								alternate syntax permits the use an arbitrary facility
							codes.</entry>
						</row>
						<row>
							<entry>facility</entry>
							<entry>facility(&lt;numeric facility code&gt;)</entry>
							<entry>An alternate syntax for <parameter>facility</parameter>
								permitting the use of an arbitrary facility code. Facility codes
								0-23 are predefined and can be referenced by their usual name.
								Facility codes above 24 are not defined but can be used by this
								alternate syntax. </entry>
						</row>
						<row>
							<entry>level() or priority()</entry>
							<entry>level(pri[,pri1..pri2[,pri3]])</entry>
							<entry>Match messages based on priority.</entry>
						</row>
						<row>
							<entry>program()</entry>
							<entry>program(regexp)</entry>
							<entry>Match messages by using a regular expression against the program
								name field of log messages </entry>
						</row>
						<row>
							<entry>host()</entry>
							<entry>host(regexp)</entry>
							<entry>Match messages by using a regular expression against the hostname
								field of log messages. </entry>
						</row>
						<row>
							<entry>match()</entry>
							<entry>match(regexp)</entry>
							<entry>Tries to match a regular expression to the message
							itself.</entry>
						</row>
						<row>
							<entry>filter()</entry>
							<entry>filter(filtername)</entry>
							<entry>Call another filter rule and evaluate its value.</entry>
						</row>
						<row>
							<entry>netmask()</entry>
							<entry>netmask(ip/mask)</entry>
							<entry>Check the sender's IP address whether it is in the specified IP
								subnet.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</sect1>
		<sect1 id="macros">
			<title>Macros</title>
			<para>Certain parts of syslog-ng (e.g.: destination filenames and message content
				templates) can refer to one or more macros, which get expanded as a message is
				processed. The table below summarizes the macros available in syslog-ng. </para>
			<para>Macros can be included by prefixing the macro name with a <parameter>$</parameter>
				sign, just like in Bourne compatible shells. syslog-ng 2.0 uses a new syntax for
				braces around macro names: <parameter>"$MSG"</parameter> and
				<parameter>"${MSG}"</parameter> are equivalent. </para>
			<para>The macros related to the time of the message (e.g.:
				<parameter>ISODATE</parameter>, <parameter>HOUR</parameter>, etc.) have two further
				versions each: one with the <parameter>S_</parameter> and one with the
				<parameter>R_</parameter> prefix (e.g.: <parameter>S_DATE</parameter> and
					<parameter>R_DATE</parameter> ). The <parameter>S_DATE</parameter> macro
				represents the date found in the log message, i.e. when the message was sent by the
				original application. <parameter>R_DATE</parameter> is the date when syslog has
				received the message. <parameter>DATE</parameter> equals either
				<parameter>S_DATE</parameter> or <parameter>R_DATE</parameter>, depending on the
				global option set in the now deprecated <parameter>use_time_recvd()</parameter>
				parameter (see <xref linkend="reference_options"/>). </para>
			<table>
				<title>Available macros in filename expansion</title>
				<tgroup cols="2">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>FACILITY</entry>
							<entry>The name of the facility from where the message originates.
							</entry>
						</row>
						<row>
							<entry>PRIORITY or LEVEL</entry>
							<entry>The priority of the message. </entry>
						</row>
						<row>
							<entry>TAG</entry>
							<entry>The priority and facility encoded as a 2 digit hexadecimal
								number. </entry>
						</row>
						<row>
							<entry>PRI</entry>
							<entry>The priority and facility encoded as a 2 or 3 digit decimal
								number as it is present in syslog messages. </entry>
						</row>
						<row>
							<entry>DATE, R_DATE, S_DATE</entry>
							<entry>Date of the message using the BSD-syslog style timestamp format
								(month/day/hour/minute/second, each expressed in two digits). This
								is the original syslog time stamp without year information, e.g.:
									<parameter>Jun 13 15:58:00</parameter>. </entry>
						</row>
						<row>
							<entry>FULLDATE, R_FULLDATE, S_FULLDATE</entry>
							<entry>A nonstandard format for the date of the message using the same
								format as <parameter>DATE</parameter>, but including the year as
								well, e.g.: <parameter>2006 Jun 13 15:58:00</parameter>.</entry>
						</row>
						<row>
							<entry>ISODATE, R_ISODATE, S_ISODATE</entry>
							<entry>Date of the message in the ISO 8601 compatible standard timestamp
								format (yyyy-mm-ddThh:mm:ss+-ZONE), e.g.:
									<parameter>2006-06-13T15:58:00.123+01:00</parameter>. If
								possible, it is recommended to use <parameter>ISODATE</parameter>
								for timestamping. Note that syslog-ng can produce fractions of a
								second in the timestamp by using the
								<parameter>frac_digits()</parameter> global or per-destination
								option.</entry>
						</row>
						<row>
							<entry>STAMP, R_STAMP, S_STAMP</entry>
							<entry>A timestamp formatted according to the <link
									linkend="reference_options">
									<parameter>ts_format()</parameter>
								</link> global or per-destination option.</entry>
						</row>
						<row>
							<entry>YEAR, R_YEAR, S_YEAR</entry>
							<entry>The year the message was sent. </entry>
						</row>
						<row>
							<entry>MONTH, R_MONTH, S_MONTH</entry>
							<entry>The month the message was sent. </entry>
						</row>
						<row>
							<entry>DAY, R_DAY, S_DAY</entry>
							<entry>The day the message was sent. </entry>
						</row>
						<row>
							<entry>WEEKDAY, R_WEEKDAY, S_WEEKDAY</entry>
							<entry>The 3-letter name of the day of week the message was sent, e.g.
									<parameter>Thu</parameter>. </entry>
						</row>
						<row>
							<entry>WEEK, R_WEEK, S_WEEK</entry>
							<entry>The week number of the year. (The first Monday in the year marks
								the first week.)</entry>
						</row>
						<row>
							<entry>HOUR, R_HOUR, S_HOUR</entry>
							<entry>The hour of day the message was sent. </entry>
						</row>
						<row>
							<entry>MIN, R_MIN, S_MIN</entry>
							<entry>The minute the message was sent. </entry>
						</row>
						<row>
							<entry>SEC, R_SEC, S_SEC</entry>
							<entry>The second the message was sent. </entry>
						</row>
						<row>
							<entry>UNIXTIME, R_UNIXTIME, S_UNIXTIME</entry>
							<entry>Standard unix timestamp, represented as the number of seconds
								since <parameter>1970-01-01T00:00:00</parameter>. </entry>
						</row>
						<row>
							<entry>TZOFFSET, R_TZOFFSET, S_TZOFFSET</entry>
							<entry>The time-zone as hour offset from GMT; e.g.:
								<parameter>-07:00</parameter>. In syslog-ng 1.6.x this used to be
									<parameter>-0700</parameter> but as
								<parameter>ISODATE</parameter> requires the colon it was added to
									<parameter>TZOFFSET</parameter> as well. </entry>
						</row>
						<row>
							<entry>TZ, R_TZ, S_TZ</entry>
							<entry>Equivalent to TZOFFSET, used to mean the time zone name
								abbreviation in syslog-ng 1.6.x. </entry>
						</row>
						<row>
							<entry>HOST</entry>
							<entry>The name of the source host where the message originates from. If
								the message traverses several hosts and the
									<parameter>chain_hostnames()</parameter> option is on (see <xref
									linkend="reference_options"/>), the first host in the chain is
								used.</entry>
						</row>
						<row>
							<entry>FULLHOST</entry>
							<entry>The full FQDN of the host name chain (without trimming chained
								hosts), including the domain name.</entry>
						</row>
						<row>
							<entry>HOST_FROM</entry>
							<entry>Name of the host that sent the message to
								<emphasis>syslog-ng</emphasis>, as resolved by syslog-ng using DNS.
								If the message traverses several hosts, this is the last host in the
								chain. </entry>
						</row>
						<row>
							<entry>FULLHOST_FROM</entry>
							<entry>FQDN of the host that sent the message to
								<emphasis>syslog-ng</emphasis> as resolved by syslog-ng using DNS.
								If the message traverses several hosts, this is the last host in the
								chain. </entry>
						</row>
						<row>
							<entry>SOURCEIP</entry>
							<entry>IP address of the host that sent the message to
									<emphasis>syslog-ng</emphasis>. (I.e. the IP address of the host
								in the <parameter>FULLHOST_FROM</parameter> macro.) Please note that
								when a message traverses several relays, this macro contains the IP
								of the last relay. </entry>
						</row>
						<row>
							<entry>PROGRAM</entry>
							<entry>The name of the program sending the message. </entry>
						</row>
						<row>
							<entry>PID</entry>
							<entry>The PID of the program sending the message. </entry>
						</row>

						<row>
							<entry>MSG or MESSAGE</entry>
							<entry>Message contents including the program name and pid. </entry>
						</row>
						<row>
							<entry>MSGONLY</entry>
							<entry>Message contents without the program name. </entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</sect1>
		<sect1 id="reference_options">
			<title>Options</title>
			<para>The following options can be specified in the options statement, as described in
					<xref linkend="options"/>.</para>
			<table>
				<title>List of global options supported in syslog-ng</title>
				<tgroup cols="3">
					<thead>
						<row>
							<entry>Name</entry>
							<entry>Accepted values</entry>
							<entry>Default</entry>
							<entry>Description</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>time_reopen()</entry>
							<entry>number</entry>
							<entry>The time to wait in seconds before a dead connection is
								reestablished.</entry>
							<entry>60</entry>
						</row>
						<row>
							<entry>time_reap()</entry>
							<entry>number</entry>
							<entry>The time to wait in seconds before an idle destination file is
								closed.</entry>
							<entry>60</entry>
						</row>
						<row>
							<entry>time_sleep()</entry>
							<entry>number</entry>
							<entry>0</entry>
							<entry>The time to wait in milliseconds between each invocation of the
									<parameter>poll()</parameter> iteration.</entry>
						</row>
						<row>
							<entry>sync() or sync_freq() (DEPRECATED)</entry>
							<entry>number</entry>
							<entry>0</entry>
							<entry>Obsolete aliases for <parameter>flush_lines()</parameter></entry>
						</row>
						<row>
							<entry>mark_freq()</entry>
							<entry>number</entry>
							<entry>1200</entry>
							<entry>The number of seconds between two <parameter>MARK</parameter>
								lines. <parameter>MARK</parameter> lines are generated if there was
								no message traffic to inform the receiver that the connection is
								still alive. </entry>
						</row>
						<row>
							<entry>stats_freq()</entry>
							<entry>number</entry>
							<entry>600</entry>
							<entry>The period between two STATS messages in seconds. STATS are log
								messages sent by <emphasis>syslog-ng</emphasis>, containing
								statistics about dropped log messages. This parameter is identical
								to the <parameter>stats()</parameter> option of <emphasis>syslog-ng
									1.6</emphasis>. In <emphasis>syslog-ng 2.0</emphasis>,
									<parameter>stats()</parameter> is an alias of
									<parameter>stats_freq()</parameter>.</entry>
						</row>
						<row>
							<entry>log_fifo_size()</entry>
							<entry>number</entry>
							<entry>100</entry>
							<entry>The number of lines fitting to the output queue</entry>
						</row>
						<row>
							<entry>chain_hostnames()</entry>
							<entry>yes or no</entry>
							<entry>yes</entry>
							<entry>Enable or disable the chained hostname format.</entry>
						</row>
						<row>
							<entry>normalize_hostnames()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Normalize hostnames, which currently translates to converting
								them to lower case. (requires 1.9.9)</entry>
						</row>
						<row>
							<entry>keep_hostname()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Enable or disable hostname rewriting.</entry>
						</row>
						<row>
							<entry>check_hostname()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Enable or disable checking whether the hostname contains valid
								characters.</entry>
						</row>
						<row>
							<entry>bad_hostname()</entry>
							<entry>regular expression</entry>
							<entry>no</entry>
							<entry>A regexp containing hostnames which should not be handled as
								hostnames. </entry>
						</row>

						<row>
							<entry>create_dirs()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Enable or disable directory creation for destination
							files.</entry>
						</row>
						<row>
							<entry>owner()</entry>
							<entry>userid</entry>
							<entry>root</entry>
							<entry>The default owner of output files.</entry>
						</row>
						<row>
							<entry>group()</entry>
							<entry>groupid</entry>
							<entry>root</entry>
							<entry>The default group of output files.</entry>
						</row>
						<row>
							<entry>perm()</entry>
							<entry>permission value</entry>
							<entry>0600</entry>
							<entry>The default permission for output files.</entry>
						</row>
						<row>
							<entry>dir_owner()</entry>
							<entry>userid</entry>
							<entry>root</entry>
							<entry>The default owner of newly created directories.</entry>
						</row>
						<row>
							<entry>dir_group()</entry>
							<entry>groupid</entry>
							<entry>root</entry>
							<entry>The default group for newly created directories.</entry>
						</row>
						<row>
							<entry>dir_perm()</entry>
							<entry>permission value</entry>
							<entry>0700</entry>
							<entry>The default permission for newly created directories.</entry>
						</row>
						<row>
							<entry>use_time_recvd() (DEPRECATED)</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>
								<para>This option controls how the time related macros are expanded
									in filename and content templates. If set to yes, then the
									non-prefixed versions of the time related macros (e.g.:
										<parameter>HOUR</parameter> instead of
									<parameter>R_HOUR</parameter> and <parameter>S_HOUR</parameter>)
									refer to the time when the message was received, otherwise it
									refers to the timestamp which is in the message. </para>
								<note>
									<para>The timestamps in the messages are generated by the
										originating host and might not be accurate. </para>
								</note>
								<note>
									<para>This option is deprecated as many users assumed that it
										controls the timestamp as it is written to
										logfiles/destinations, which is not the case. To change how
										messages are formatted, specify a content-template referring
										to the appropriate prefixed (<parameter>S_</parameter> or
											<parameter>R_</parameter>) time macro. </para>
								</note>
							</entry>
						</row>
						<row>
							<entry>ts_format()</entry>
							<entry>rfc3164, bsd, rfc3339, iso</entry>
							<entry>rfc3164</entry>
							<entry>Specifies the timestamp format used when syslog-ng itself formats
								a timestamp and nothing else specifies a format (e.g.:
									<parameter>STAMP</parameter> macros, internal messages, messages
								without original timestamps). </entry>
						</row>
						<row>
							<entry>use_dns()</entry>
							<entry>yes or no</entry>
							<entry>yes</entry>
							<entry>Enable or disable DNS usage. syslog-ng blocks on DNS queries, so
								enabling DNS may lead to a Denial of Service attack. To prevent DoS,
								protect your syslog-ng network endpoint with firewall rules, and
								make sure that all hosts which may get to syslog-ng are
							resolvable.</entry>
						</row>
						<row>
							<entry>dns_cache()</entry>
							<entry>yes or no</entry>
							<entry>yes</entry>
							<entry>Enable or disable DNS cache usage.</entry>
						</row>
						<row>
							<entry>dns_cache_size()</entry>
							<entry>number</entry>
							<entry>1007</entry>
							<entry>Number of hostnames in the DNS cache.</entry>
						</row>
						<row>
							<entry>dns_cache_expire()</entry>
							<entry>number</entry>
							<entry>3600</entry>
							<entry>Number of seconds while a successful lookup is cached.</entry>
						</row>
						<row>
							<entry>dns_cache_expire_failed()</entry>
							<entry>number</entry>
							<entry>60</entry>
							<entry>Number of seconds while a failed lookup is cached.</entry>
						</row>
						<row>
							<entry>log_msg_size()</entry>
							<entry>number</entry>
							<entry>8192</entry>
							<entry>Maximum length of a message in bytes.</entry>
						</row>
						<row>
							<entry>use_fqdn()</entry>
							<entry>yes or no</entry>
							<entry>no</entry>
							<entry>Add Fully Qualified Domain Name instead of short
							hostname.</entry>
						</row>
						<row>
							<entry>gc_idle_threshold() (DEPRECATED)</entry>
							<entry>number</entry>
							<entry>n/a</entry>
							<entry>Has no meaning in syslog-ng 1.9.x and later. </entry>
						</row>

						<row>
							<entry>gc_busy_threshold() (DEPRECATED)</entry>
							<entry>number</entry>
							<entry>n/a</entry>
							<entry>Has no meaning in syslog-ng 1.9.x and later. </entry>
						</row>

						<row>
							<entry>flush_lines()</entry>
							<entry>number</entry>
							<entry>0</entry>
							<entry>Specifies how many lines are flushed to a destination at a time.
								Syslog-ng waits for this number of lines to accumulate and sends
								them off in a single batch. Setting this number high increases
								throughput as fully filled frames are sent to the network, but also
								increases message latency. The latency can be limited by the use of
								the <parameter>flush_timeout</parameter> option. </entry>
						</row>

						<row>
							<entry>flush_timeout()</entry>
							<entry>time in milliseconds</entry>
							<entry>10000</entry>
							<entry>Specifies the time syslog-ng waits for lines to accumulate in its
								output buffer. See the <parameter>flush_lines()</parameter> option
								for more information. </entry>
						</row>

						<row>
							<entry>recv_time_zone()</entry>
							<entry>time offset (e.g.: <parameter>+03:00</parameter>)</entry>
							<entry>local timezone</entry>
							<entry>Specifies the time zone associated with the incoming messages, if
								not specified otherwise in the message or in the source driver. See
									<xref linkend="timezone_handling"/> for details.</entry>
						</row>
						<row>
							<entry>send_time_zone()</entry>
							<entry>time offset (e.g.: <parameter>+03:00</parameter>)</entry>
							<entry>local timezone</entry>
							<entry>Specifies the time zone associated with the messages sent by
								syslog-ng, if not specified otherwise in the message or in the
								destination driver. See <xref linkend="timezone_handling"/> for
								details.</entry>
						</row>
						<row>
							<entry>frac_digits()</entry>
							<entry>number</entry>
							<entry>0</entry>
							<entry><emphasis>syslog-ng</emphasis> can store fractions of a second in
								the timestamps. <parameter>frac_digits()</parameter> specifies the
								number of digits stored. The digits storing the fractions are padded
								by zeros if the original timestamp of the message specifies only
								seconds. Fractions can always be stored for the received time of the
								messages.</entry>
						</row>
					</tbody>
				</tgroup>
			</table>
		</sect1>
	</chapter>
	<chapter id="tuning">
		<title>Performance tuning in syslog-ng</title>

		<!--<note>
			<para>This information is out of date for syslog-ng 2.0. Some of it might still apply,
				but syslog-ng has changed considerably.</para>
		</note>-->
		<para>There are several settings available you can finetune the behaviour of syslog-ng. The
			defaults should be adequate for a single server or workstation installation, but for a
			central loghost receiving the logs from multiple computers it may not be enough. </para>
		<sect1>
			<title>Setting garbage collector parameters</title>
			<para>Syslog-ng 2.0 is a complete reimplementation of syslog-ng 1.6, and does not use
				the mark and sweep garbage collector at all. The garbage collector parameters
					(<parameter>gc_idle_threshold</parameter>,
				<parameter>gc_busy_threshold</parameter>) are still accepted but are ignored.
			</para>
		</sect1>
		<sect1>
			<title>Setting time_sleep()</title>
			<para>When there are a lot of parallel connections to syslog-ng, the amount of time
				required to prepare for a single poll loop iteration is significant. Since the
				arrival of every single log message triggers a new iteration, the CPU usage of
				syslog-ng might increase significantly even if the number of messages received is
				otherwise low. The solution is to add a fixed latency to message processing to wait
				some messages to arrive and to process them in blocks. This can be accomplished by
				setting the <parameter>time_sleep()</parameter> to a non-zero value. It is not
				recommended to increase it above 100ms, as that might skew timestamps, slow
				syslog-ng, and cause messages to be dropped. An alternative solution is to avoid
					<parameter>tcp()</parameter> and <parameter>unix-stream()</parameter> sources
				and use the DGRAM versions, <parameter>udp()</parameter> and
				<parameter>unix-dgram()</parameter>, respectively. </para>
			<para>The value of <parameter>fetch_limit()</parameter> and
				<parameter>log_fifo_size()</parameter> must also be sized accordingly when
					<parameter>time_sleep()</parameter> is modified. </para>
		</sect1>
		<sect1>
			<title>Setting output queue size</title>
			<para><emphasis>syslog-ng</emphasis> always reads its incoming log channels to prevent
				the running daemons from blocking. This may result in lost messages if the output
				queue is full, it is therefore important to set the output queue size (termed in
				number of messages). The size of the output queue can be set either globally, or on
				a per destination basis.</para>
			<note>
				<para>This does not apply to syslog-ng 2.0 if the flow-control flag is enabled. See
						<xref linkend="logflags"/> for details.</para>
			</note>
			<synopsis>
			options { log_fifo_size(1000); };
			</synopsis>
			<para>or</para>
			<synopsis>
				destination d_messages { file("/var/log/messages" log_fifo_size(1000)); };
			</synopsis>
			<para>You should set your fifo size to the estimated number of messages in a message
				burst. If bursts extend the bandwidth of your destination pipe,
				<emphasis>syslog-ng</emphasis> can feed messages into the destination pipe after the
				burst has collapsed. </para>
			<para>Of course <emphasis>syslog-ng</emphasis> cannot widen the network bandwidth, so if
				the destination host lives on a noisy network and the logtraffic extends the
				bandwidth of this network, <emphasis>syslog-ng</emphasis> cannot do anything.
				However, it will do its best. </para>
		</sect1>
		<sect1>
			<title>Setting the sync parameter</title>
			<para>The <parameter>sync</parameter> parameter does not exactly do what its name
				implies. As you have seen messages to be sent are buffered in an output queue. The
					<parameter>sync</parameter> parameter specifies the number of messages held in
				this buffer before anything is written. </para>
			<para>Note that it does not write all buffered messages into a single chunk; each
				distinct message is written with a single <parameter>write()</parameter> system
				call. </para>
		</sect1>
	</chapter>

</book>