The syslog-ng Open Source Edition 3.9 Administrator Guide

This guide is published under the Creative Commons Attribution-Noncommercial-No Derivative Works (by-nc-nd) 3.0 license. See Appendix D, Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License for details. The latest version is always available at https://www.balabit.com/support/documentation.

Some rights reserved.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (https://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

AIX™, AIX 5L™, AS/400™, BladeCenter™, eServer™, IBM™, the IBM™ logo, IBM System i™, IBM System i5™, IBM System x™, iSeries™, i5/OS™, Netfinity™, NetServer™, OpenPower™, OS/400™, PartnerWorld™, POWER™, ServerGuide™, ServerProven™, and xSeries™ are trademarks or registered trademarks of International Business Machines.

Alliance Log Agent for System i™ is a registered trademark of Patrick Townsend & Associates, Inc.

The Balabit™ name and the Balabit™ logo are registered trademarks of Balabit SA.

Debian™ is a registered trademark of Software in the Public Interest Inc.

Hadoop™ and the Hadoop elephant logo are trademarks of the Apache Software Foundation.

Linux™ is a registered trademark of Linus Torvalds.

MapR™, is a trademark of MapR Technologies, Inc.

Elasticsearch™ and Kibana™ is a trademark of Elasticsearch BV, registered in the U.S. and in other countries.

Apache Kafka and the Apache Kafka Logo are trademarks of the Apache Software Foundation.

MySQL™ is a registered trademark of Oracle and/or its affiliates.

Oracle™, JD Edwards™, PeopleSoft™, and Siebel™ are registered trademarks of Oracle Corporation and/or its affiliates.

Red Hat™, Inc., Red HatEnterprise Linux™ and Red HatLinux™ are trademarks of Red Hat, Inc.

SUSE™ is a trademark of SUSE AG, a Novell business.

Solaris™ is a registered trademark of Oracle and/or its affiliates.

The syslog-ng™ name and the syslog-ng™ logo are registered trademarks of Balabit.

Windows™ 95, 98, ME, 2000, XP, Server 2003, Vista, Server 2008, 7, 8, and Server 2012 are registered trademarks of Microsoft Corporation.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER. Balabit is not responsible for any third-party websites mentioned in this document. Balabit does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balabit will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

May 12, 2017


Table of Contents

Preface
1. Summary of contents
2. Target audience and prerequisites
3. Products covered in this guide
4. Typographical conventions
5. Contact and support information
5.1. Sales contact
5.2. Support contact
5.3. Training
6. About this document
6.1. Summary of changes
6.2. Feedback
6.3. Acknowledgments
1. Introduction to syslog-ng
1.1. What syslog-ng is
1.2. What syslog-ng is not
1.3. Why is syslog-ng needed?
1.4. What is new in syslog-ng Open Source Edition 3.9?
1.5. Who uses syslog-ng?
1.6. Supported platforms
2. The concepts of syslog-ng
2.1. The philosophy of syslog-ng
2.2. Logging with syslog-ng
2.2.1. The route of a log message in syslog-ng
2.3. Modes of operation
2.3.1. Client mode
2.3.2. Relay mode
2.3.3. Server mode
2.4. Global objects
2.5. Timezones and daylight saving
2.5.1. How syslog-ng OSE assigns timezone to the message
2.5.2. A note on timezones and timestamps
2.6. The license of syslog-ng OSE
2.7. High availability support
2.8. The structure of a log message
2.8.1. BSD-syslog or legacy-syslog messages
2.8.2. IETF-syslog messages
2.9. Message representation in syslog-ng OSE
2.10. Structuring macros, metadata, and other value-pairs
2.10.1. Specifying data types in value-pairs
2.11. Things to consider when forwarding messages between syslog-ng OSE hosts
3. Installing syslog-ng
3.1. Compiling syslog-ng from source
3.2. Compiling options of syslog-ng OSE
3.3. Uninstalling syslog-ng OSE
3.4. Configuring Microsoft SQL Server to accept logs from syslog-ng
4. The syslog-ng OSE quick-start guide
4.1. Configuring syslog-ng on client hosts
4.2. Configuring syslog-ng on server hosts
4.3. Configuring syslog-ng relays
4.3.1. Configuring syslog-ng on relay hosts
4.3.2. How relaying log messages works
5. The syslog-ng OSE configuration file
5.1. Notes about the configuration syntax
5.2. Defining configuration objects inline
5.3. Using channels in configuration objects
5.4. Global and environmental variables
5.5. Modules in syslog-ng OSE
5.5.1. Loading modules
5.6. Managing complex syslog-ng configurations
5.6.1. Including configuration files
5.6.2. Reusing configuration blocks
5.6.3. Generating configuration blocks from a script
6. Collecting log messages — sources and source drivers
6.1. How sources work
6.2. Collecting internal messages
6.2.1. internal() source options
6.3. Collecting messages from text files
6.3.1. Notes on reading kernel messages
6.3.2. file() source options
6.4. Collecting messages using the RFC3164 protocol (network() driver)
6.4.1. network() source options
6.5. Receiving JSON messages from nodejs applications
6.5.1. nodejs() source options
6.6. Converting local e-mail messages to log messages
6.7. Collecting messages from named pipes
6.7.1. pipe() source options
6.8. Collecting process accounting logs on Linux
6.8.1. pacct() options
6.9. Receiving messages from external applications
6.9.1. program() source options
6.10. Collecting messages on Sun Solaris
6.10.1. sun-streams() source options
6.11. Collecting messages using the IETF syslog protocol (syslog() driver)
6.11.1. syslog() source options
6.12. Collecting the system-specific log messages of a platform
6.13. Collecting messages from the systemd-journal system log storage
6.13.1. systemd-journal() source options
6.14. Collecting systemd messages using a socket
6.15. Collecting messages from remote hosts using the BSD syslog protocol
6.15.1. tcp(), tcp6(), udp() and udp6() source options — OBSOLETE
6.16. Collecting messages from UNIX domain sockets
6.16.1. UNIX credentials and other metadata
6.16.2. unix-stream() and unix-dgram() source options
7. Sending and storing log messages — destinations and destination drivers
7.1. Publishing messages using AMQP
7.1.1. amqp() destination options
7.2. Sending messages directly to Elasticsearch version 1.x
7.2.1. Prerequisites
7.2.2. How syslog-ng OSE interacts with Elasticsearch
7.2.3. Client modes
7.2.4. Elasticsearch destination options
7.3. Sending messages directly to Elasticsearch version 2.0 or higher
7.3.1. Prerequisites
7.3.2. How syslog-ng OSE interacts with Elasticsearch
7.3.3. Client modes
7.3.4. Elasticsearch X-Pack (Shield) and syslog-ng OSE
7.3.5. Search Guard and syslog-ng OSE
7.3.6. Elasticsearch destination options
7.4. Storing messages in plain-text files
7.4.1. file() destination options
7.5. Sending metrics to Graphite
7.5.1. graphite() destination options
7.6. Storing messages on the Hadoop Distributed File System (HDFS)
7.6.1. Prerequisites
7.6.2. How syslog-ng OSE interacts with HDFS
7.6.3. Storing messages with MapR-FS
7.6.4. HDSF destination options
7.7. Posting messages over HTTP
7.7.1. HTTP destination options
7.8. Posting messages over HTTP without Java
7.8.1. HTTP destination options
7.9. Publishing messages to Apache Kafka
7.9.1. Prerequisites
7.9.2. How syslog-ng OSE interacts with Apache Kafka
7.9.3. Kafka destination options
7.10. Using Loggly
7.10.1. loggly() destination options
7.11. Using Logmatic.io
7.11.1. logmatic() destination options
7.12. Storing messages in a MongoDB database
7.12.1. How syslog-ng OSE connects the MongoDB server
7.12.2. mongodb() destination options
7.13. Sending messages to a remote log server using the RFC3164 protocol (network() driver)
7.13.1. network() destination options
7.14. Sending messages to named pipes
7.14.1. pipe() destination options
7.15. Sending messages to external applications
7.15.1. program() destination options
7.16. pseudofile()
7.16.1. pseudofile() destination options
7.17. Storing name-value pairs in Redis
7.17.1. redis() destination options
7.18. Monitoring your data with Riemann
7.18.1. riemann() destination options
7.19. Generating SMTP messages (e-mail) from logs
7.19.1. smtp() destination options
7.20. Storing messages in an SQL database
7.20.1. Using the sql() driver with an Oracle database
7.20.2. Using the sql() driver with a Microsoft SQL database
7.20.3. The way syslog-ng interacts with the database
7.20.4. sql() destination options
7.21. Publishing messages using STOMP
7.21.1. stomp() destination options
7.22. Sending messages to a remote logserver using the IETF-syslog protocol
7.22.1. syslog() destination options
7.23. Sending messages to a remote log server using the legacy BSD-syslog protocol (tcp(), udp() drivers)
7.23.1. tcp(), tcp6(), udp(), and udp6() destination options
7.24. Sending messages to UNIX domain sockets
7.24.1. unix-stream() and unix-dgram() destination options
7.25. Sending messages to a user terminal — usertty() destination
7.26. Write your own custom destination in Java or Python
8. Routing messages: log paths and filters
8.1. Log paths
8.1.1. Embedded log statements
8.1.2. Junctions and channels
8.1.3. Log path flags
8.2. Managing incoming and outgoing messages with flow-control
8.2.1. Flow-control and multiple destinations
8.2.2. Configuring flow-control
8.3. Using disk-based and memory buffering
8.3.1. Enabling reliable disk-based buffering
8.3.2. Enabling normal disk-based buffering
8.3.3. Enabling memory buffering
8.3.4. About disk queue files
8.4. Filters
8.4.1. Using filters
8.4.2. Combining filters with boolean operators
8.4.3. Comparing macro values in filters
8.4.4. Using wildcards, special characters, and regular expressions in filters
8.4.5. Tagging messages
8.4.6. Filter functions
8.5. Dropping messages
9. Global options of syslog-ng OSE
9.1. Configuring global syslog-ng options
9.2. Global options
10. TLS-encrypted message transfer
10.1. Secure logging using TLS
10.2. Encrypting log messages with TLS
10.2.1. Configuring TLS on the syslog-ng clients
10.2.2. Configuring TLS on the syslog-ng server
10.3. Mutual authentication using TLS
10.3.1. Configuring TLS on the syslog-ng clients
10.3.2. Configuring TLS on the syslog-ng server
10.4. TLS options
11. Manipulating messages
11.1. Customizing message format
11.1.1. Formatting messages, filenames, directories, and tablenames
11.1.2. Templates and macros
11.1.3. Date-related macros
11.1.4. Hard vs. soft macros
11.1.5. Macros of syslog-ng OSE
11.1.6. Using template functions
11.1.7. Template functions of syslog-ng OSE
11.1.8. Modifying the on-the-wire message format
11.2. Modifying messages
11.2.1. Replacing message parts
11.2.2. Setting message fields to specific values
11.2.3. Unsetting message fields
11.2.4. Creating custom SDATA fields
11.2.5. Setting multiple message fields to specific values
11.2.6. Conditional rewrites
11.2.7. Adding and deleting tags
11.2.8. Anonymizing credit card numbers
11.3. Regular expressions
11.3.1. Types and options of regular expressions
11.3.2. Optimizing regular expressions
12. Parsing and segmenting structured messages
12.1. Parsing syslog messages
12.1.1. Options of syslog-parser parsers
12.2. Parsing messages with comma-separated and similar values
12.2.1. Options of CSV parsers
12.3. Parsing key=value pairs
12.3.1. Options of key=value parsers
12.4. The JSON parser
12.4.1. Options of JSON parsers
12.5. Parsing dates and timestamps
12.5.1. Options of date-parser() parsers
12.6. The Apache Access Log Parser
12.6.1. Options of apache-accesslog-parser() parsers
12.7. The Linux Audit Parser
12.7.1. Options of linux-audit-parser() parsers
13. Processing message content with a pattern database
13.1. Classifying log messages
13.1.1. The structure of the pattern database
13.1.2. How pattern matching works
13.1.3. Artificial ignorance
13.2. Using pattern databases
13.2.1. Using parser results in filters and templates
13.2.2. Downloading sample pattern databases
13.3. Correlating log messages using pattern databases
13.3.1. Referencing earlier messages of the context
13.4. Triggering actions for identified messages
13.4.1. Conditional actions
13.4.2. External actions
13.4.3. Actions and message correlation
13.5. Creating pattern databases
13.5.1. Using pattern parsers
13.5.2. What's new in the syslog-ng pattern database format V5
13.5.3. The syslog-ng pattern database format
14. Correlating log messages
14.1. Correlating messages using the grouping-by() parser
14.1.1. Referencing earlier messages of the context
14.1.2. Options of grouping-by parsers
15. Enriching log messages with external data
15.1. Adding metadata from an external file
15.1.1. Options add-contextual-data()
15.2. Looking up GeoIP data from IP addresses
15.2.1. Options of geoip parsers
16. Statistics of syslog-ng
17. Multithreading and scaling in syslog-ng OSE
17.1. Multithreading concepts of syslog-ng OSE
17.2. Configuring multithreading
17.3. Optimizing multithreaded performance
18. Troubleshooting syslog-ng
18.1. Possible causes of losing log messages
18.2. Creating syslog-ng core files
18.3. Collecting debugging information with strace, truss, or tusc
18.4. Running a failure script
18.5. Stopping syslog-ng
18.6. Reporting bugs and finding help
18.7. Recover data from orphaned diskbuffer files
19. Best practices and examples
19.1. General recommendations
19.2. Handling large message load
19.3. Using name resolution in syslog-ng
19.3.1. Resolving hostnames locally
19.4. Collecting logs from chroot
19.5. Configuring log rotation
A. The syslog-ng manual pages
dqtool — Display the contents of a disk-buffer file created with syslog-ng Open Source Edition
loggen — Generate syslog messages at a specified rate
pdbtool — An application to test and convert syslog-ng pattern database rules
syslog-debun — syslog-ng DEBUg buNdle generator
syslog-ng — syslog-ng system logger application
syslog-ng.conf — syslog-ng configuration file
syslog-ng-ctl — Display message statistics and enable verbose, debug and trace modes in syslog-ng Open Source Edition
B. GNU General Public License
B.1. Preamble
B.2. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
B.2.1. Section 0
B.2.2. Section 1
B.2.3. Section 2
B.2.4. Section 3
B.2.5. Section 4
B.2.6. Section 5
B.2.7. Section 6
B.2.8. Section 7
B.2.9. Section 8
B.2.10. Section 9
B.2.11. Section 10
B.2.12. NO WARRANTY Section 11
B.2.13. Section 12
B.3. How to Apply These Terms to Your New Programs
C. GNU Lesser General Public License
C.1. Preamble
C.2. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
C.2.1. Section 0
C.2.2. Section 1
C.2.3. Section 2
C.2.4. Section 3
C.2.5. Section 4
C.2.6. Section 5
C.2.7. Section 6
C.2.8. Section 7
C.2.9. Section 8
C.2.10. Section 9
C.2.11. Section 10
C.2.12. Section 11
C.2.13. Section 12
C.2.14. Section 13
C.2.15. Section 14
C.2.16. NO WARRANTY Section 15
C.2.17. Section 16
C.3. How to Apply These Terms to Your New Libraries
D. Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License
Glossary
Index
List of syslog-ng OSE parameters

List of Examples

2.1. Using type-hinting
2.2. Using the value-pairs() option
2.3. Using the rekey() option
4.1. The default configuration file of syslog-ng OSE
4.2. A simple configuration for clients
4.3. A simple configuration for servers
4.4. A simple configuration for relays
5.1. A simple configuration file
5.2. Using required and optional parameters
5.3. Using inline definitions
5.4. Using channels
5.5. Using global variables
5.6. Reusing configuration blocks
5.7. Defining blocks with multiple elements
5.8. Passing arguments to blocks
5.9. Using arguments in blocks
6.1. A simple source statement
6.2. A source statement using two source drivers
6.3. Setting default priority and facility
6.4. Source statement on a Linux based operating system
6.5. Using the internal() driver
6.6. Initial window size of a connection
6.7. Using the file() driver
6.8. Tailing files
6.9. Processing indented multi-line messages
6.10. Processing Tomcat logs
6.11. Using the network() driver
6.12. Initial window size of a connection
6.13. Processing indented multi-line messages
6.14. Processing Tomcat logs
6.15. Using the nodejs() driver
6.16. Using the mbox() driver
6.17. Using the pipe() driver
6.18. Initial window size of a connection
6.19. Processing indented multi-line messages
6.20. Processing Tomcat logs
6.21. Using the program() driver
6.22. Initial window size of a connection
6.23. Using the sun-streams() driver
6.24. Initial window size of a connection
6.25. Using the syslog() driver
6.26. Initial window size of a connection
6.27. Processing indented multi-line messages
6.28. Processing Tomcat logs
6.29. Sending all fields through syslog protocol using the systemd-journal() driver
6.30. Filtering for a specific field using the systemd-journal() driver
6.31. Sending all fields in value-pairs using the systemd-journal() driver
6.32. Using the systemd-syslog() driver
6.33. Using the unix-stream() and unix-dgram() drivers
6.34. Initial window size of a connection
7.1. A simple destination statement
7.2. Using the amqp() driver
7.3. Examples for using disk-buffer()
7.4. Sending log data to Elasticsearch version 1.x
7.5. Example for the .yml file
7.6. Examples for using disk-buffer()
7.7. Sending log data to Elasticsearch version 2.x and above
7.8. Sending log data to Elasticsearch using the HTTP REST API
7.9. Examples for using disk-buffer()
7.10. Using the file() driver
7.11. Using the file() driver with macros in the file name and a template for the message
7.12. Examples for using disk-buffer()
7.13. Using the graphite() driver
7.14. Storing logfiles on HDFS
7.15. Storing logfiles with MapR-FS
7.16. Examples for using disk-buffer()
7.17. Sending log data to a web service
7.18. Sending log data to a web service
7.19. Examples for using disk-buffer()
7.20. Sending log data to Apache Kafka
7.21. Using the loggly() driver
7.22. Using the logmatic() driver
7.23. Using the mongodb() driver
7.24. Examples for using disk-buffer()
7.25. Using the network() driver
7.26. Examples for using disk-buffer()
7.27. Using the pipe() driver
7.28. Using the program() destination driver
7.29. Examples for using disk-buffer()
7.30. Using the redis() driver
7.31. Examples for using disk-buffer()
7.32. Using the riemann() driver
7.33. Examples for using disk-buffer()
7.34. Using the smtp() driver
7.35. Simple e-mail alerting with the smtp() driver
7.36. Examples for using disk-buffer()
7.37. Using the sql() driver
7.38. Using the sql() driver with an Oracle database
7.39. Using the sql() driver with an MSSQL database
7.40. Examples for using disk-buffer()
7.41. Setting flags for SQL destinations
7.42. Using SQL NULL values
7.43. Value: default
7.44. Using the stomp() driver
7.45. Examples for using disk-buffer()
7.46. Using the syslog() driver
7.47. Examples for using disk-buffer()
7.48. Using the unix-stream() driver
7.49. Examples for using disk-buffer()
7.50. Using the usertty() driver
8.1. A simple log statement
8.2. Using embedded log paths
8.3. Using junctions
8.4. Using log path flags
8.5. Soft flow-control
8.6. Hard flow-control
8.7. Sizing parameters for flow-control
8.8. Example for using reliable disk-based buffering
8.9. Example for using normal disk-based buffering
8.10. Example for using memory buffering
8.11. A simple filter statement
8.12. Comparing macro values in filters
8.13. Filtering with widcards
8.14. Selecting messages using the in-list filter
8.15. Adding tags and filtering messages with tags
8.16. Skipping messages
9.1. Using global options
10.1. A destination statement using TLS
10.2. A source statement using TLS
10.3. Disabling mutual authentication
10.4. A destination statement using mutual authentication
10.5. A source statement using TLS
10.6. Using ssl-options
11.1. Using templates and macros
11.2. Using SDATA macros
11.3. Using custom template functions
11.4. Using the format-cef-extension template function
11.5. Using the format-json template function
11.6. Using the format-welf() template function
11.7. Using the graphite-output template function
11.8. Using the grep template function
11.9. Using the $(hash) template function
11.10. Anonymizing IP addresses
11.11. Using pattern databases and the if template function
11.12. Using the indent-multi-line template function
11.13. Using the padding template function
11.14. Writing template functions in Python
11.15. Using the sanitize template function
11.16. Using the substr template function
11.17. Using Universally Unique Identifiers
11.18. Using substitution rules
11.19. Anonymizing IP addresses
11.20. Setting message fields to a particular value
11.21. Unsetting a message field
11.22. Rewriting custom SDATA fields
11.23. Using groupset rewrite rules
11.24. Using conditional rewriting
11.25. Using Posix regular expressions
11.26. Using PCRE regular expressions
11.27. Optimizing regular expressions in filters
12.1. Using junctions
12.2. Segmenting hostnames separated with a dash
12.3. Parsing Apache log files
12.4. Segmenting a part of a message
12.5. Adding the end of the message to the last column
12.6. Using a key=value parser
12.7. Using a JSON parser
12.8. Convert logstash eventlog format v0 to v1
12.9. Using the marker option in JSON parser
12.10. Using the date-parser()
12.11. Using the apache-accesslog-parser parser
12.12. Using the linux-audit-parser() parser
13.1. Defining pattern databases
13.2. Using classification results
13.3. Using classification results for filtering messages
13.4. Using pattern parsers as macros
13.5. How syslog-ng OSE calculates context-timeout
13.6. Using message correlation
13.7. Referencing values from an earlier message
13.8. Using the grep template function
13.9. Sending triggered messages to the internal() source
13.10. Generating messages for pattern database matches
13.11. Generating messages with inherited values
13.12. Creating a new context from an action
13.13. Actions based on the number of messages
13.14. Sending triggered messages to external applications
13.15. Referencing values from an earlier message
13.16. Using the inherit-properties option
13.17. Sending alert when a client disappears
13.18. Pattern parser syntax
13.19. Using the STRING and ESTRING parsers
13.20. A pattern database containing a single rule
13.21. Generating messages for pattern database matches
13.22. Generating messages with inherited values
13.23. Generating messages for pattern database matches
13.24. Generating messages with inherited values
14.1. How syslog-ng OSE calculates context-timeout
14.2. Correlating Linux Audit logs
14.3. Referencing values from an earlier message
14.4. Using the grep template function
14.5. Sending triggered messages to the internal() source
15.1. Adding metadata from a CSV file
15.2. Using the GeoIP parser
17.1. Enabling multithreading
19.1. File destination for log rotation
19.2. Command for cron for log rotation
A.1. Using required and optional parameters
A.2. Using global options

List of Procedures

2.2.1. The route of a log message in syslog-ng
2.5.1. How syslog-ng OSE assigns timezone to the message
3.1. Compiling syslog-ng from source
3.4. Configuring Microsoft SQL Server to accept logs from syslog-ng
4.1. Configuring syslog-ng on client hosts
4.2. Configuring syslog-ng on server hosts
4.3.1. Configuring syslog-ng on relay hosts
5.6.3. Generating configuration blocks from a script
6.15.1.1. Change an old source driver to the network() driver
7.2.1. Prerequisites
7.3.1. Prerequisites
7.3.4. Elasticsearch X-Pack (Shield) and syslog-ng OSE
7.3.5. Search Guard and syslog-ng OSE
7.6.1. Prerequisites
7.6.2. How syslog-ng OSE interacts with HDFS
7.6.3. Storing messages with MapR-FS
7.9.1. Prerequisites
7.12.1. How syslog-ng OSE connects the MongoDB server
7.23.1.1. Change an old destination driver to the network() driver
10.2.1. Configuring TLS on the syslog-ng clients
10.2.2. Configuring TLS on the syslog-ng server
10.3.1. Configuring TLS on the syslog-ng clients
10.3.2. Configuring TLS on the syslog-ng server
11.2.6.1. How conditional rewriting works
18.2. Creating syslog-ng core files
19.3.1. Resolving hostnames locally
19.4. Collecting logs from chroot

Preface

Welcome to the syslog-ng Open Source Edition 3.9 Administrator Guide!

This document describes how to configure and manage syslog-ng. Background information for the technology and concepts used by the product is also discussed.

1. Summary of contents

Chapter 1, Introduction to syslog-ng describes the main functionality and purpose of syslog-ng OSE.

Chapter 2, The concepts of syslog-ng discusses the technical concepts and philosophies behind syslog-ng OSE.

Chapter 3, Installing syslog-ng describes how to install syslog-ng OSE on various UNIX-based platforms using the precompiled binaries.

Chapter 4, The syslog-ng OSE quick-start guide provides a briefly explains how to perform the most common log collecting tasks with syslog-ng OSE.

Chapter 5, The syslog-ng OSE configuration file discusses the configuration file format and syntax in detail, and explains how to manage large-scale configurations using included files and reusable configuration snippets.

Chapter 6, Collecting log messages — sources and source drivers explains how to collect and receive log messages from various sources.

Chapter 7, Sending and storing log messages — destinations and destination drivers describes the different methods to store and forward log messages.

Chapter 8, Routing messages: log paths and filters explains how to route and sort log messages, and how to use filters to select specific messages.

Chapter 9, Global options of syslog-ng OSE lists the global options of syslog-ng OSE and explains how to use them.

Chapter 10, TLS-encrypted message transfer shows how to secure and authenticate log transport using TLS encryption.

Chapter 11, Manipulating messages describes how to customize message format using templates and macros, how to rewrite and modify messages, and how to use regular expressions.

Chapter 12, Parsing and segmenting structured messages describes how to segment and process structured messages like comma-separated values.

Chapter 13, Processing message content with a pattern database explains how to identify and process log messages using a pattern database.

Chapter 16, Statistics of syslog-ng details the available statistics that syslog-ng OSE collects about the processed log messages.

Chapter 17, Multithreading and scaling in syslog-ng OSE describes how to configure syslog-ng OSE to use multiple processors, and how to optimize its performance.

Chapter 18, Troubleshooting syslog-ng offers tips to solving problems.

Chapter 19, Best practices and examples gives recommendations to configure special features of syslog-ng OSE.

Appendix A, The syslog-ng manual pages contains the manual pages of the syslog-ng OSE application.

Appendix C, GNU Lesser General Public License includes the text of the LGPLv2.1 license applicable to the core of syslog-ng Open Source Edition.

Appendix B, GNU General Public License includes the text of the GPLv2 license applicable to syslog-ng Open Source Edition.

Appendix D, Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License includes the text of the Creative Commons Attribution Non-commercial No Derivatives (by-nc-nd) License applicable to The syslog-ng Open Source Edition 3.9 Administrator Guide.

Glossary defines the important terms used in this guide.

List of syslog-ng OSE parameters provides cross-references to the definitions of options, parameters, and macros available in syslog-ng OSE.

The Index provides cross-references to important terms used in this guide.

2. Target audience and prerequisites

This guide is intended for system administrators and consultants responsible for designing and maintaining logging solutions and log centers. It is also useful for IT decision makers looking for a tool to implement centralized logging in heterogeneous environments.

The following skills and knowledge are necessary for a successful syslog-ng administrator:

  • At least basic system administration knowledge.

  • An understanding of networks, TCP/IP protocols, and general network terminology.

  • Working knowledge of the UNIX or Linux operating system.

  • In-depth knowledge of the logging process of various platforms and applications.

  • An understanding of the legacy syslog (BSD-syslog) protocol) and the new syslog (IETF-syslog) protocol) standard.

3. Products covered in this guide

This guide describes the use of the following products:

  • syslog-ng Open Source Edition (syslog-ng OSE) 3.9.1 and later

4. Typographical conventions

Before you start using this guide, it is important to understand the terms and typographical conventions used in the documentation. For more information on specialized terms and abbreviations used in the documentation, see theGlossary at the end of this document.

The following kinds of text formatting and icons identify special information in the document.

Tip

Tips provide best practices and recommendations.

Note

Notes provide additional information on a topic, and emphasize important facts and considerations.

Warning

Warnings mark situations where loss of data or misconfiguration of the device is possible if the instructions are not obeyed.

Command

Commands you have to execute.

Emphasis

Reference items, additional readings.

/path/to/file

File names.

Parameters

Parameter and attribute names.

Label

GUI output messages or dialog labels.

Menu

A submenu or menu item in the menu bar.

Button

Buttons in dialog windows.

5. Contact and support information

This product is developed and maintained by the open source community and Balabit-Europe. Balabit-Europe is located in Budapest, Hungary. Our address is:

Balabit SA2 Alíz StreetH-1117BudapestHungaryTel: +36 1 398-6700Fax: +36 1 208-0875
         E-mail: 
         Web: https://www.balabit.com/
        

5.1. Sales contact

You can directly contact us with sales related topics at the e-mail address , or leave us your contact information and we call you back.

5.2. Support contact

In case you experience a problem that is not covered in this guide, post it on our forum or mailing list.

To report bugs found in syslog-ng OSE, visit this page.

Precompiled binary packages are available for free from various third-parties. See the list of precompiled syslog-ng OSE binary packages.

5.3. Training

Balabit SA holds courses on using its products for new and experienced users. For dates, details, and application forms, visit the https://my.balabit.com/training webpage.

6. About this document

This guide is a work-in-progress document with new versions appearing periodically.

The latest version of this document can be downloaded from the Balabit website.

6.1. Summary of changes

This section lists the changes of The syslog-ng Open Source Edition Administrator Guide.

6.1.1. Version 3.8 - 3.9

Changes in product: 

Changes in documentation: 

  • Corrections and editorial changes.

6.1.2. Version 3.7 - 3.8

Changes in product: 

Changes in documentation: 

6.1.3. Version 3.6 - 3.7

Changes in product: 

Changes in documentation: 

6.1.4. Version 3.5 - 3.6

Changes in product: 

Changes in documentation: 

6.2. Feedback

Any feedback is greatly appreciated, especially on what else this document should cover. General comments, errors found in the text, and any suggestions about how to improve the documentation is also welcome at documentation@balabit.com.

The source of this guide is available on GitHub. In case of the syslog-ng Open Source Edition guides, you can also:

6.3. Acknowledgments

Balabit would like to express its gratitude to the syslog-ng users and the syslog-ng community for their invaluable help and support.

Chapter 1. Introduction to syslog-ng

This chapter introduces the syslog-ng Open Source Edition application in a non-technical manner, discussing how and why is it useful, and the benefits it offers to an existing IT infrastructure.

1.1. What syslog-ng is

The syslog-ng application is a flexible and highly scalable system logging application that is ideal for creating centralized and trusted logging solutions. Among others, syslog-ng OSE allows you the following.

Secure and reliable log transfer

The syslog-ng OSE application enables you to send the log messages of your hosts to remote servers using the latest protocol standards. You can collect and store your log data centrally on dedicated log servers. Transfer log messages using the TCP protocol ensures that no messages are lost.

Disk-based message buffering. To minimize the risk of losing important log messages, the syslog-ng OSE application can store messages on the local hard disk if the central log server or the network connection becomes unavailable. The syslog-ng application automatically sends the stored messages to the server when the connection is reestablished, in the same order the messages were received. The disk buffer is persistent – no messages are lost even if syslog-ng is restarted.

Secure logging using TLS. Log messages may contain sensitive information that should not be accessed by third parties. Therefore, syslog-ng OSE supports the Transport Layer Security (TLS) protocol to encrypt the communication. TLS also allows you to authenticate your clients and the logserver using X.509 certificates.

Flexible data extraction and processing

Most log messages are inherently unstructured, which makes them difficult to process. To overcome this problem, syslog-ng OSE comes with a set of built-in parsers, which you can combine to build very complex things.

Filter and classify. The syslog-ng OSE application can sort the incoming log messages based on their content and various parameters like the source host, application, and priority. You can create directories, files, and database tables dynamically using macros. Complex filtering using regular expressions and boolean operators offers almost unlimited flexibility to forward only the important log messages to the selected destinations.

Parse and rewrite. The syslog-ng OSE application can segment log messages to named fields or columns, and also modify the values of these fields. You can process JSON messages, key-value pairs, and more.

To get the most information out of your log data, syslog-ng OSE allows you to correlate log messages and aggregate the extracted information into a single message. You can also use external information to enrich your log data.

Big data clusters

The log data that your organization has to process, store, and review increases daily, so many organizations use big data solutions for their logs. To accomodate this huge amount of data, syslog-ng OSE natively supports storing log messages in HDFS files and Elasticsearch clusters.

Message queue support

Large organizations increasingly rely on queuing infrastructure to transfer their data. syslog-ng OSE supports Apache Kafka, the Advanced Message Queuing Protocol (AMQP), and the Simple Text Oriented Messaging Protocol (STOMP).

SQL, NoSQL, and monitoring

Storing your log messages in a database allows you to easily search and query the messages and interoperate with log analyzing applications. The syslog-ng application supports the following databases: MongoDB, MSSQL, MySQL, Oracle, PostgreSQL, and SQLite.

syslog-ng OSE also allows you to extract the information you need from your log data, and directly send it to your Graphite, Redis, or Riemann monitoring system.

Wide protocol and platform support

syslog protocol standards. syslog-ng not only supports legacy BSD syslog (RFC3164) and the enhanced RFC5424 protocols but also JavaScript Object Notation (JSON) and journald message formats.

Heterogeneous environments. The syslog-ng OSE application is the ideal choice to collect logs in massively heterogeneous environments using several different operating systems and hardware platforms, including Linux, Unix, BSD, Sun Solaris, HP-UX, Tru64, and AIX.

IPv4 and IPv6 support. The syslog-ng application can operate in both IPv4 and IPv6 network environments, and can receive and send messages to both types of networks.

1.2. What syslog-ng is not

The syslog-ng application is not log analysis software. It can filter log messages and select only the ones matching certain criteria. It can even convert the messages and restructure them to a predefined format, or parse the messages and segment them into different fields. But syslog-ng cannot interpret and analyze the meaning behind the messages, or recognize patterns in the occurrence of different messages.

1.3. Why is syslog-ng needed?

Log messages contain information about the events happening on the hosts. Monitoring system events is essential for security and system health monitoring reasons.

The original syslog protocol separates messages based on the priority of the message and the facility sending the message. These two parameters alone are often inadequate to consistently classify messages, as many applications might use the same facility — and the facility itself is not even included in the log message. To make things worse, many log messages contain unimportant information. The syslog-ng application helps you to select only the really interesting messages, and forward them to a central server.

Company policies or other regulations often require log messages to be archived. Storing the important messages in a central location greatly simplifies this process.

1.4. What is new in syslog-ng Open Source Edition 3.9?

Version 3.9 of syslog-ng Open Source Edition includes the following main features:

  • The elastic2() destination driver now supports Search Guard, an alternative security solution for Elasticsearch. For details, see Procedure 7.3.5, Search Guard and syslog-ng OSE.

  • When using TLS-transport, you can now use certain fields of the X.509 certificates as macros. For details, see Section .TLS.X509.

  • To explicitly unset a several fields you can use the groupunset() rewrite rule. For details, see Section 11.2.3, Unsetting message fields.

  • add-contextual-data() now supports the prefix() option. Also, in the CSV file, Windows-style linebreaks (CRLF) are handled properly.

For a more detailed list, see Section 6.1.1, Version 3.8 - 3.9 and https://github.com/balabit/syslog-ng/releases/.

1.5. Who uses syslog-ng?

The syslog-ng application is used worldwide by companies and institutions who collect and manage the logs of several hosts, and want to store them in a centralized, organized way. Using syslog-ng is particularly advantageous for:

  • Internet Service Providers

  • Financial institutions and companies requiring policy compliance

  • Server, web, and application hosting companies

  • Datacenters

  • Wide area network (WAN) operators

  • Server farm administrators.

1.6. Supported platforms

The syslog-ng Open Source Edition application is highly portable and is known to run on a wide range of hardware architectures (x86, x86_64, SUN Sparc, PowerPC 32 and 64, Alpha) and operating systems, including Linux, BSD, Solaris, IBM AIX, HP-UX, Mac OS X, Cygwin, Tru64, and others.

Chapter 2. The concepts of syslog-ng

This chapter discusses the technical concepts of syslog-ng.

2.1. The philosophy of syslog-ng

Typically, syslog-ng is used to manage log messages and implement centralized logging, where the aim is to collect the log messages of several devices on a single, central log server. The different devices — called syslog-ng clients — all run syslog-ng, and collect the log messages from the various applications, files, and other sources. The clients send all important log messages to the remote syslog-ng server, which sorts and stores them.

2.2. Logging with syslog-ng

The syslog-ng application reads incoming messages and forwards them to the selected destinations. The syslog-ng application can receive messages from files, remote hosts, and other sources.

Log messages enter syslog-ng in one of the defined sources, and are sent to one or more destinations.

Sources and destinations are independent objects, log paths define what syslog-ng does with a message, connecting the sources to the destinations. A log path consists of one or more sources and one or more destinations: messages arriving from a source are sent to every destination listed in the log path. A log path defined in syslog-ng is called a log statement.

Optionally, log paths can include filters. Filters are rules that select only certain messages, for example, selecting only messages sent by a specific application. If a log path includes filters, syslog-ng sends only the messages satisfying the filter rules to the destinations set in the log path.

Other optional elements that can appear in log statements are parsers and rewriting rules. Parsers segment messages into different fields to help processing the messages, while rewrite rules modify the messages by adding, replacing, or removing parts of the messages.

2.2.1. Procedure – The route of a log message in syslog-ng

Purpose: 

The following procedure illustrates the route of a log message from its source on the syslog-ng client to its final destination on the central syslog-ng server.

Figure 2.1. The route of a log message

The route of a log message

Steps: 

  1. A device or application sends a log message to a source on the syslog-ng client. For example, an Apache web server running on Linux enters a message into the /var/log/apache file.

  2. The syslog-ng client running on the web server reads the message from its /var/log/apache source.

  3. The syslog-ng client processes the first log statement that includes the /var/log/apache source.

  4. The syslog-ng client performs optional operations (message filtering, parsing, and rewriting) on the message, for example, it compares the message to the filters of the log statement (if any). If the message complies with all filter rules, syslog-ng sends the message to the destinations set in the log statement, for example, to the remote syslog-ng server.

    Warning

    Message filtering, parsing, and rewriting is performed in the order that the operations appear in the log statement.

    Note

    The syslog-ng client sends a message to all matching destinations by default. As a result, a message may be sent to a destination more than once, if the destination is used in multiple log statements. To prevent such situations, use the final flag in the destination statements. For details, see Table 8.1, Log statement flags.

  5. The syslog-ng client processes the next log statement that includes the /var/log/apache source, repeating Steps 3-4.

  6. The message sent by the syslog-ng client arrives from a source set in the syslog-ng server.

  7. The syslog-ng server reads the message from its source and processes the first log statement that includes that source.

  8. The syslog-ng server performs optional operations (message filtering, parsing, and rewriting) on the message, for example, it compares the message to the filters of the log statement (if any). If the message complies with all filter rules, syslog-ng sends the message to the destinations set in the log statement.

    Warning

    Message filtering, parsing, and rewriting is performed in the order that the operations appear in the log statement.

  9. The syslog-ng server processes the next log statement, repeating Steps 7-9.

    Note

    The syslog-ng application can stop reading messages from its sources if the destinations cannot process the sent messages. This feature is called flow-control and is detailed in Section 8.2, Managing incoming and outgoing messages with flow-control.

2.3. Modes of operation

The syslog-ng Open Source Edition application has three typical operation scenarios: Client, Server, and Relay.

2.3.1. Client mode

Figure 2.2. Client-mode operation

Client-mode operation

In client mode, syslog-ng collects the local logs generated by the host and forwards them through a network connection to the central syslog-ng server or to a relay. Clients often also log the messages locally into files.

2.3.2. Relay mode

Figure 2.3. Relay-mode operation

Relay-mode operation

In relay mode, syslog-ng receives logs through the network from syslog-ng clients and forwards them to the central syslog-ng server using a network connection. Relays also log the messages from the relay host into a local file, or forward these messages to the central syslog-ng server.

2.3.3. Server mode

Figure 2.4. Server-mode operation

Server-mode operation

In server mode, syslog-ng acts as a central log-collecting server. It receives messages from syslog-ng clients and relays over the network, and stores them locally in files, or passes them to other applications, for example log analyzers.

2.4. Global objects

The syslog-ng application uses the following objects:

  • Source driver: A communication method used to receive log messages. For example, syslog-ng can receive messages from a remote host via TCP/IP, or read the messages of a local application from a file. For details on source drivers, see Chapter 6, Collecting log messages — sources and source drivers.

  • Source: A named collection of configured source drivers.

  • Destination driver: A communication method used to send log messages. For example, syslog-ng can send messages to a remote host via TCP/IP, or write the messages into a file or database. For details on destination drivers, see Chapter 7, Sending and storing log messages — destinations and destination drivers.

  • Destination: A named collection of configured destination drivers.

  • Filter: An expression to select messages. For example, a simple filter can select the messages received from a specific host. For details, see Section 11.1, Customizing message format.

  • Macro: An identifier that refers to a part of the log message. For example, the ${HOST} macro returns the name of the host that sent the message. Macros are often used in templates and filenames. For details, see Section 11.1, Customizing message format.

  • Parser: Parsers are objects that parse the incoming messages, or parts of a message. For example, the csv-parser() can segment messages into separate columns at a predefined separator character (for example a comma). Every column has a unique name that can be used as a macro. For details, see Chapter 12, Parsing and segmenting structured messages and Chapter 13, Processing message content with a pattern database.

  • Rewrite rule: A rule modifies a part of the message, for example, replaces a string, or sets a field to a specified value. For details, see Section 11.2, Modifying messages.

  • Log paths: A combination of sources, destinations, and other objects like filters, parsers, and rewrite rules. The syslog-ng application sends messages arriving from the sources of the log paths to the defined destinations, and performs filtering, parsing, and rewriting of the messages. Log paths are also called log statements. Log statements can include other (embedded) log statements and junctions to create complex log paths. For details, see Chapter 8, Routing messages: log paths and filters.

  • Template: A template is a set of macros that can be used to restructure log messages or automatically generate file names. For example, a template can add the hostname and the date to the beginning of every log message. For details, see Section 11.1, Customizing message format.

  • Option: Options set global parameters of syslog-ng, like the parameters of name resolution and timezone handling. For details, see Chapter 9, Global options of syslog-ng OSE.

For details on the above objects, see The configuration syntax in detail.

2.5. Timezones and daylight saving

The syslog-ng application receives the timezone and daylight saving information from the operating system it is installed on. If the operating system handles daylight saving correctly, so does syslog-ng.

The syslog-ng application supports messages originating from different timezones. The original syslog protocol (RFC3164) does not include timezone information, but syslog-ng provides a solution by extending the syslog protocol to include the timezone in the log messages. The syslog-ng application also enables administrators to supply timezone information for legacy devices which do not support the protocol extension.

2.5.1. Procedure – How syslog-ng OSE assigns timezone to the message

When syslog-ng OSE receives a message, it assigns timezone information to the message using the following algorithm.

  1. The sender application (for example the syslog-ng client) or host specifies the timezone of the messages. If the incoming message includes a timezone it is associated with the message. Otherwise, the local timezone is assumed.

  2. Specify the time-zone() parameter for the source driver that reads the message. This timezone will be associated with the messages only if no timezone is specified within the message itself. Each source defaults to the value of the recv-time-zone() global option. It is not possible to override only the timezone information of the incoming message, but setting the keep-timestamp() option to no allows syslog-ng OSE to replace the full timestamp (timezone included) with the time the message was received.

    Note

    When processing a message that does not contain timezone information, the syslog-ng OSE application will use the timezone and daylight-saving that was effective when the timestamp was generated. For example, the current time is 2011-03-11 (March 11, 2011) in the EU/Budapest timezone. When daylight-saving is active (summertime), the offset is +02:00. When daylight-saving is inactive (wintertime) the timezone offset is +01:00. If the timestamp of an incoming message is 2011-01-01, the timezone associated with the message will be +01:00, but the timestamp will be converted, because 2011-01-01 meant winter time when daylight saving is not active but the current timezone is +02:00.

  3. Specify the timezone in the destination driver using the time-zone() parameter. Each destination driver might have an associated timezone value: syslog-ng converts message timestamps to this timezone before sending the message to its destination (file or network socket). Each destination defaults to the value of the send-time-zone() global option.

    Note

    A message can be sent to multiple destination zones. The syslog-ng application converts the timezone information properly for every individual destination zone.

    Warning

    If syslog-ng OSE sends the message is to the destination using the legacy-syslog protocol (RFC3164) which does not support timezone information in its timestamps, the timezone information cannot be encapsulated into the sent timestamp, so syslog-ng OSE will convert the hour:min values based on the explicitly specified timezone.

  4. If the timezone is not specified, local timezone is used.

  5. When macro expansions are used in the destination filenames, the local timezone is used. (Also, if the timestamp of the received message does not contain the year of the message, syslog-ng OSE uses the local year.)

2.5.2. A note on timezones and timestamps

If the clients run syslog-ng, then use the ISO timestamp, because it includes timezone information. That way you do not need to adjust the recv-time-zone() parameter of syslog-ng.

If you want syslog-ng to output timestamps in Unix (POSIX) time format, use the S_UNIXTIME and R_UNIXTIME macros. You do not need to change any of the timezone related parameters, because the timestamp information of incoming messages is converted to Unix time internally, and Unix time is a timezone-independent time representation. (Actually, Unix time measures the number of seconds elapsed since midnight of Coordinated Universal Time (UTC) January 1, 1970, but does not count leap seconds.)

2.6. The license of syslog-ng OSE

Starting with version 3.2, the syslog-ng Open Source Edition application is licensed under a combined LGPL+GPL license. The core of syslog-ng OSE is licensed under the GNU Lesser General Public License Version 2.1 license, while the rest of the codebase is licensed under the GNU General Public License Version 2 license.

Note

Practically, the code stored under the lib directory of the source code package is under LGPL, the rest is GPL.

For details about the LGPL and GPL licenses, see Appendix C, GNU Lesser General Public License and Appendix B, GNU General Public License, respectively.

2.7. High availability support

Multiple syslog-ng servers can be run in fail-over mode. The syslog-ng application does not include any internal support for this, as clustering support must be implemented on the operating system level. A tool that can be used to create UNIX clusters is Heartbeat (for details, see this page).

2.8. The structure of a log message

The following sections describe the structure of log messages. Currently there are two standard syslog message formats:

2.8.1. BSD-syslog or legacy-syslog messages

This section describes the format of a syslog message, according to the legacy-syslog or BSD-syslog protocol. A syslog message consists of the following parts:

The total message cannot be longer than 1024 bytes.

The following is a sample syslog message: <133>Feb 25 14:09:07 webserver syslogd: restart. The message corresponds to the following format: <priority>timestamp hostname application: message. The different parts of the message are explained in the following sections.

Note

The syslog-ng application supports longer messages as well. For details, see the log-msg-size() option in Section 9.2, Global options. However, it is not recommended to enable messages larger than the packet size when using UDP destinations.

2.8.1.1. The PRI message part

The PRI part of the syslog message (known as Priority value) represents the Facility and Severity of the message. Facility represents the part of the system sending the message, while severity marks its importance. The Priority value is calculated by first multiplying the Facility number by 8 and then adding the numerical value of the Severity. The possible facility and severity values are presented below.

Note

Facility codes may slightly vary between different platforms. The syslog-ng application accepts facility codes as numerical values as well.

Numerical Code Facility
0 kernel messages
1 user-level messages
2 mail system
3 system daemons
4 security/authorization messages
5 messages generated internally by syslogd
6 line printer subsystem
7 network news subsystem
8 UUCP subsystem
9 clock daemon
10 security/authorization messages
11 FTP daemon
12 NTP subsystem
13 log audit
14 log alert
15 clock daemon
16-23 locally used facilities (local0-local7)

Table 2.1. syslog Message Facilities


The following table lists the severity values.

Numerical Code Severity
0 Emergency: system is unusable
1 Alert: action must be taken immediately
2 Critical: critical conditions
3 Error: error conditions
4 Warning: warning conditions
5 Notice: normal but significant condition
6 Informational: informational messages
7 Debug: debug-level messages

Table 2.2. syslog Message Severities


2.8.1.2. The HEADER message part

The HEADER part contains a timestamp and the hostname (without the domain name) or the IP address of the device. The timestamp field is the local time in the Mmm dd hh:mm:ss format, where:

  • Mmm is the English abbreviation of the month: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.

  • dd is the day of the month on two digits. If the day of the month is less than 10, the first digit is replaced with a space. (For example Aug 7.)

  • hh:mm:ss is the local time. The hour (hh) is represented in a 24-hour format. Valid entries are between 00 and 23, inclusive. The minute (mm) and second (ss) entries are between 00 and 59 inclusive.

Note

The syslog-ng application supports other timestamp formats as well, like ISO, or the PIX extended format. For details, see the ts-format() option in Section 9.2, Global options.

2.8.1.3. The MSG message part

The MSG part contains the name of the program or process that generated the message, and the text of the message itself. The MSG part is usually in the following format: program[pid]: message text.

2.8.2. IETF-syslog messages

This section describes the format of a syslog message, according to the IETF-syslog protocol. A syslog message consists of the following parts:

The following is a sample syslog message:[1]

<34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - ID47 - BOM'su root' failed for lonvick on /dev/pts/8

The message corresponds to the following format:

<priority>VERSION ISOTIMESTAMP HOSTNAME APPLICATION PID MESSAGEID STRUCTURED-DATA MSG

In this example, the Facility has the value of 4, severity is 2, so PRI is 34. The VERSION is 1. The message was created on 11 October 2003 at 10:14:15pm UTC, 3 milliseconds into the next second. The message originated from a host that identifies itself as "mymachine.example.com". The APP-NAME is "su" and the PROCID is unknown. The MSGID is "ID47". The MSG is "'su root' failed for lonvick...", encoded in UTF-8. The encoding is defined by theBOM[2]. There is no STRUCTURED-DATA present in the message, this is indicated by "-" in the STRUCTURED-DATA field. The MSG is "'su root' failed for lonvick...".

The HEADER part of the message must be in plain ASCII format, the parameter values of the STRUCTURED-DATA part must be in UTF-8, while the MSG part should be in UTF-8. The different parts of the message are explained in the following sections.

2.8.2.1. The PRI message part

The PRI part of the syslog message (known as Priority value) represents the Facility and Severity of the message. Facility represents the part of the system sending the message, while severity marks its importance. The Priority value is calculated by first multiplying the Facility number by 8 and then adding the numerical value of the Severity. The possible facility and severity values are presented below.

Note

Facility codes may slightly vary between different platforms. The syslog-ng application accepts facility codes as numerical values as well.

Numerical Code Facility
0 kernel messages
1 user-level messages
2 mail system
3 system daemons
4 security/authorization messages
5 messages generated internally by syslogd
6 line printer subsystem
7 network news subsystem
8 UUCP subsystem
9 clock daemon
10 security/authorization messages
11 FTP daemon
12 NTP subsystem
13 log audit
14 log alert
15 clock daemon
16-23 locally used facilities (local0-local7)

Table 2.3. syslog Message Facilities


The following table lists the severity values.

Numerical Code Severity
0 Emergency: system is unusable
1 Alert: action must be taken immediately
2 Critical: critical conditions
3 Error: error conditions
4 Warning: warning conditions
5 Notice: normal but significant condition
6 Informational: informational messages
7 Debug: debug-level messages

Table 2.4. syslog Message Severities


2.8.2.2. The HEADER message part

The HEADER part contains the following elements:

  • VERSION: Version number of the syslog protocol standard. Currently this can only be 1.

  • ISOTIMESTAMP: The time when the message was generated in the ISO 8601 compatible standard timestamp format (yyyy-mm-ddThh:mm:ss+-ZONE), for example: 2006-06-13T15:58:00.123+01:00.

  • HOSTNAME: The machine that originally sent the message.

  • APPLICATION: The device or application that generated the message

  • PID: The process name or process ID of the syslog application that sent the message. It is not necessarily the process ID of the application that generated the message.

  • MESSAGEID: The ID number of the message.

Note

The syslog-ng application supports other timestamp formats as well, like ISO, or the PIX extended format. The timestamp used in the IETF-syslog protocol is derived from RFC3339, which is based on ISO8601. For details, see the ts-format() option in Section 9.2, Global options.

The syslog-ng OSE application will truncate the following fields:

  • If APP-NAME is longer than 48 characters it will be truncated to 48 characters.

  • If PROC-ID is longer than 128 characters it will be truncated to 128 characters.

  • If MSGID is longer than 32 characters it will be truncated to 32 characters.

  • If HOSTNAME is longer than 255 characters it will be truncated to 255 characters.

2.8.2.3. The STRUCTURED-DATA message part

The STRUCTURED-DATA message part may contain meta- information about the syslog message, or application-specific information such as traffic counters or IP addresses. STRUCTURED-DATA consists of data blocks enclosed in brackets ([]). Every block includes the ID of the block, and one or more name=value pairs. The syslog-ng application automatically parses the STRUCTURED-DATA part of syslog messages, which can be referenced in macros (for details, see Section 11.1.5, Macros of syslog-ng OSE). An example STRUCTURED-DATA block looks like:

[exampleSDID@0 iut="3" eventSource="Application" eventID="1011"][examplePriority@0 class="high"]

2.8.2.4. The MSG message part

The MSG part contains the text of the message itself. The encoding of the text must be UTF-8 if theBOM[3]character is present in the message. If the message does not contain the BOM character, the encoding is treated as unknown. Usually messages arriving from legacy sources do not include the BOM character. CRLF characters will not be removed from the message.



[1] Source: https://tools.ietf.org/html/rfc5424

[2] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

[3] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

2.9. Message representation in syslog-ng OSE

When the syslog-ng OSE application receives a message, it automatically parses the message. The syslog-ng OSE application can automatically parse log messages that conform to the RFC3164 (BSD or legacy-syslog) or the RFC5424 (IETF-syslog) message formats. If syslog-ng OSE cannot parse a message, it results in an error.

Tip

In case you need to relay messages that cannot be parsed without any modifications or changes, use the flags(no-parse) option in the source definition, and a template containing only the ${MSG} macro in the destination definition.

To parse non-syslog messages, for example, JSON, CSV, or other messages, you can use the built-in parsers of syslog-ng OSE. For details, see Chapter 12, Parsing and segmenting structured messages.

A parsed syslog message has the following parts.

  • Timestamps. Two timestamps are associated with every message: one is the timestamp contained within the message (that is, when the sender sent the message), the other is the time when syslog-ng OSE has actually received the message.

  • Severity. The severity of the message.

  • Facility. The facility that sent the message.

  • Tags. Custom text labels added to the message that are mainly used for filtering. None of the current message transport protocols adds tags to the log messages. Tags can be added to the log message only within syslog-ng OSE. The syslog-ng OSE application automatically adds the id of the source as a tag to the incoming messages. Other tags can be added to the message by the pattern database, or using the tags() option of the source.

  • IP address of the sender. The IP address of the host that sent the message. Note that the IP address of the sender is a hard macro and cannot be modified within syslog-ng OSE but the associated hostname can be modified, for example, using rewrite rules.

  • Hard macros. Hard macros contain data that is directly derived from the log message, for example, the ${MONTH} macro derives its value from the timestamp. The most important consideration with hard macros is that they are read-only, meaning they cannot be modified using rewrite rules or other means.

  • Soft macros. Soft macros (sometimes also called name-value pairs) are either built-in macros automatically generated from the log message (for example, ${HOST}), or custom user-created macros generated by using the syslog-ng pattern database or a CSV-parser. The SDATA fields of RFC5424-formatted log messages become soft macros as well. In contrast with hard macros, soft macros are writable and can be modified within syslog-ng OSE, for example, using rewrite rules.

    Note

    It is also possible to set the value of built-in soft macros using parsers, for example, to set the ${HOST} macro from the message using a column of a CSV-parser.

    The data extracted from the log messages using named pattern parsers in the pattern database are also soft macros.

    Tip

    For the list of hard and soft macros, see Section 11.1.4, Hard vs. soft macros.

Message size and encoding

Internally, syslog-ng OSE represents every message as UTF-8. The maximal length of the log messages is limited by the log-msg-size() option: if a message is longer than this value, syslog-ng OSE truncates the message at the location it reaches the log-msg-size() value, and discards the rest of the message.

When encoding is set in a source (using the encoding() option) and the message is longer (in bytes) than log-msg-size() in UTF-8 representation, syslog-ng OSE splits the message at an undefined location (because the conversion between different encodings is not trivial).

2.10. Structuring macros, metadata, and other value-pairs

Available in syslog-ng OSE 3.3 and later.

The syslog-ng OSE application allows you to select and construct name-value pairs from any information already available about the log message, or extracted from the message itself. You can directly use this structured information, for example, in the following places:

When using value-pairs, there are three ways to specify which information (that is, macros or other name-value pairs) to include in the selection.

  • Select groups of macros using the scope() parameter, and optionally remove certain macros from the group using the exclude() parameter.

  • List specific macros to include using the key() parameter.

  • Define new name-value pairs to include using the pair() parameter.

These parameters are detailed in Section value-pairs().

2.10.1. Specifying data types in value-pairs

By default, syslog-ng OSE handles every data as strings. However, certain destinations and data formats (for example, SQL, MongoDB, JSON, AMQP) support other types of data as well, for example, numbers or dates. The syslog-ng OSE application allows you to specify the data type in templates (this is also called type-hinting). If the destination driver supports data types, it converts the incoming data to the specified data type. For example, this allows you to store integer numbers as numbers in MongoDB, instead of strings.

Warning

Hazard of data loss! If syslog-ng OSE cannot convert the data into the specified type, an error occurs, and syslog-ng OSE drops the message by default. To change how syslog-ng OSE handles data-conversion errors, see Section on-error().

To use type-hinting, enclose the macro or template containing the data with the type: <datatype>("<macro>"), for example: int("$PID").

Currently the mongodb() destination and the format-json template function supports data types.

Example 2.1. Using type-hinting

The following example stores the MESSAGE, PID, DATE, and PROGRAM fields of a log message in a MongoDB database. The DATE and PID parts are stored as numbers instead of strings.

mongodb(
    value-pairs(pair("date", datetime("$UNIXTIME"))
            pair("pid", int64("$PID"))
            pair("program", "$PROGRAM"))
            pair("message", "$MESSAGE"))
             )
);

The following example formats the same fields into JSON.

$(format-json date=datetime("$UNIXTIME") pid=int64("$PID") program="$PROGRAM" message="$MESSAGE")

The syslog-ng OSE application currently supports the following data-types.

  • boolean: Converts the data to a boolean value. Anything that begins with a t or 1 is converted to true, anything that begins with an f or 0 is converted to false.

  • datetime: Use it only with UNIX timestamps, anything else will likely result in an error. This means that currently you can use only the $UNIXTIME macro for this purpose.

  • double: A floating-point number.

  • literal: The data as a literal string, without adding any quotes or escape characters.

  • int or int32: 32-bit integer.

  • int64: 64-bit integer.

  • string: The data as a string.

value-pairs()

Type: parameter list of the value-pairs() option
Default:
empty string

Description: The value-pairs() option allows you to select specific information about a message easily using predefined macro groups. The selected information is represented as name-value pairs and can be used formatted to JSON format, or directly used in a mongodb() destination.

Example 2.2. Using the value-pairs() option

The following example selects every available information about the log message, except for the date-related macros (R_* and S_*), selects the .SDATA.meta.sequenceId macro, and defines a new value-pair called MSGHDR that contains the program name and PID of the application that sent the log message.

value-pairs(
    scope(nv_pairs core syslog all_macros selected_macros everything)
    exclude("R_*")
    exclude("S_*")
    key(".SDATA.meta.sequenceId")
    pair("MSGHDR" "$PROGRAM[$PID]: ")
)

The following example selects the same information as the previous example, but converts it into JSON format.

$(format-json --scope nv_pairs,core,syslog,all_macros,selected_macros,everything \
  --exclude R_* --exclude S_* --key .SDATA.meta.sequenceId \
  --pair MSGHDR="$PROGRAM[$PID]: ")
Note

Every macro is included in the selection only once, but redundant information may appear if multiple macros include the same information (for example, including several date-related macros in the selection).

The value-pairs() option has the following parameters. The parameters are evaluated in the following order:

exclude()  
Type: Space-separated list of macros to remove from the selection created using the scope() option.
Default: empty string

Description: This option removes the specified macros from the selection. Use it to remove unneeded macros selected using the scope() parameter.

For example, the following example removes the SDATA macros from the selection.

value-pairs(
        scope(rfc5424 selected_macros)
        exclude(".SDATA*")
    )

The name of the macro to remove can include wildcards (*, ?). Regular expressions are not supported.

key()  
Type: Space-separated list of macros to be included in selection
Default: empty string

Description: This option selects the specified macros. The selected macros will be included as MACRONAME = MACROVALUE, that is using key("HOST") will result in HOST = $HOST. You can use wildcards (*, ?) to select multiple macros. For example:

value-pairs(
        scope(rfc3164)
        key("HOST"))
value-pairs(
        scope(rfc3164)
        key("HOST", "PROGRAM"))
pair()  
Type: name value pairs in "<NAME>" "<VALUE>" format
Default: empty string

Description: This option defines a new name-value pair to be included in the message. The value part can include macros, templates, and template functions as well. For example:

value-pairs(
        scope(rfc3164)
        pair("TIME" "$HOUR:$MIN")
        pair("MSGHDR" "$PROGRAM[$PID]: "))
rekey()  
Type: <pattern-to-select-names>, <list of transformations>
Default: empty string

Description: This option allows you to manipulate and modify the name of the value-pairs. You can define transformations, which are are applied to the selected name-value pairs. The first parameter of the rekey() option is a glob pattern that selects the name-value pairs to modify. If you omit the pattern, the transformations are applied to every key of the scope. For details on globs, see Section glob.

  • If rekey() is used within a key() option, the name-value pairs specified in the glob of the key() option are transformed.

  • If rekey() is used outside the key() option, every name-value pair of the scope() is transformed.

The following transformations are available:

add-prefix("<my-prefix>")

Adds the specified prefix to every name. For example, rekey( add-prefix("my-prefix."))

replace-prefix("<prefix-to-replace>", "<new-prefix>")

Replaces a substring at the beginning of the key with another string. Only prefixes can be replaced. For example, replace-prefix(".class", ",patterndb") changes the beginning tag .class to .patterndb

This option was called replace() in syslog-ng OSE version 3.4.

shift("<number>")

Cuts the specified number of characters from the beginning of the name.

Example 2.3. Using the rekey() option

The following sample selects every value-pair that begins with .cee., deletes this prefix by cutting 4 characters from the names, and adds a new prefix (events.).

value-pairs(
    key(".cee.*"
        rekey(
            shift(4)
            add-prefix("events.")
        )
    )
)

The rekey() option can be used with the format-json template-function as well, using the following syntax:

$(format-json --rekey .cee.* --add-prefix events.)
scope()  
Type: space-separated list of macro groups to include in selection
Default: empty string

Description: This option selects predefined groups of macros. The following groups are available:

  • nv-pairs: Every soft macro (name-value pair) associated with the message, except the ones that start with a dot (.) character. Macros starting with a dot character are generated within syslog-ng OSE and are not originally part of the message, therefore are not included in this group.

  • dot-nv-pairs: Every soft macro (name-value pair) associated with the message which starts with a dot (.) character. For example, .classifier.rule_id and .sdata.*. Macros starting with a dot character are generated within syslog-ng OSE and are not originally part of the message.

  • all-nv-pairs: Include every soft macro (name-value pair). Equivalent to using both nv-pairs and dot-nv-pairs.

  • rfc3164: The macros that correspond to the RFC3164 (legacy or BSD-syslog) message format: $FACILITY, $PRIORITY, $HOST, $PROGRAM, $PID, $MESSAGE, and $DATE.

  • rfc5424: The macros that correspond to the RFC5424 (IETF-syslog) message format: $FACILITY, $PRIORITY, $HOST, $PROGRAM, $PID, $MESSAGE, $MSGID, $R_DATE, and the metadata from the structured-data (SDATA) part of RFC5424-formatted messages, that is, every macro that starts with .SDATA..

    The rfc5424 group also has the following alias: syslog-proto. Note that the value of $R_DATE will be listed under the DATE key.

    The rfc5424 group does not contain any metadata about the message, only information that was present in the original message. To include the most commonly used metadata (for example, the $SOURCEIP macro), use the selected-macros group instead.

  • all-macros: Include every hard macro. This group is mainly useful for debugging, as it contains redundant information (for example, the date-related macros include the date-related information several times in various formats).

  • selected-macros: Include the macros of the rfc3164 groups, and the most commonly used metadata about the log message: the $TAGS, $SOURCEIP, and $SEQNUM macros.

  • sdata: The metadata from the structured-data (SDATA) part of RFC5424-formatted messages, that is, every macro that starts with .SDATA.

  • everything: Include every hard and soft macros. This group is mainly useful for debugging, as it contains redundant information (for example, the date-related macros include the date-related information several times in various formats).

For example:

value-pairs(
        scope(rfc3164 selected-macros))

2.11. Things to consider when forwarding messages between syslog-ng OSE hosts

When you send your log messages from a syslog-ng OSE client through the network to a syslog-ng OSE server, you can use different protocols and options. Every combination has its advantages and disadvantages. The most important thing is to use matching protocols and options, so the server handles the incoming log messages properly.

In syslog-ng OSE you can change many aspects of the network communication. First of all, there is the structure of the messages itself. Currently, syslog-ng OSE supports two standard syslog protocols: the BSD (RFC3164) and the syslog (RFC5424) message format.

These RFCs describe the format and the structure of the log message, and add a (lightweight) framing around the messages. You can set this framing/structure by selecting the appropriate driver in syslog-ng OSE. There are two drivers you can use: the network() driver and the syslog() driver. The syslog() driver is for the syslog (RFC5424) protocol and the network() driver is for the BSD (RFC3164) protocol.

The tcp() and udp() drivers are now deprecated, they are essentially equivalent with the network(transport(tcp)) and network(transport(udp)) drivers.

In addition to selecting the driver to use, both drivers allow you to use different transport-layer protocols: TCP and UDP, and optionally also higher-level transport protocols: TLS (over TCP. To complicate things a bit more, you can configure the network() driver (corresponding to the BSD (RFC3164) protocol) to send the messages in the syslog (RFC5424) format (but without the framing used in RFC5424) using the flag(syslog-protocol) option.

Because some combination of drivers and options are invalid, you can use the following drivers and options as sources and as destinations:

  1. syslog(transport(tcp))

  2. syslog(transport(udp))

  3. syslog(transport(tls))

  4. network(transport(tcp))

  5. network(transport(udp))

  6. network(transport(tls))

  7. network(transport(tcp) flag(syslog-protocol))

  8. network(transport(udp) flag(syslog-protocol))

  9. network(transport(tls) flag(syslog-protocol))

If you use the same driver and options in the destination of your syslog-ng OSE client and the source of your syslog-ng OSE server, everything should work as expected. Unfortunately there are some other combinations, that seem to work, but result in losing parts of the messages. The following table show the combinations:

Source \ Destination syslog/tcp syslog/udp syslog/tls network/tcp network/udp network/tls network/tcp/flag network/udp/flag network/tls/flag
syslog/tcp - - ! - - ! - -
syslog/udp - - - ! - - ! -
syslog/tls - - - - ! - - !
network/tcp - - - - - ✔? - -
network/udp - ✔? - - - - ✔? -
network/tls - - - - - - - ✔?
network/tcp/flag ! - - ! - - - -
network/udp/flag - ! - - ! - - -
network/tls/flag - - ! - - ! - -

Table 2.5. Source-destination driver combinations


  • - This method does not work. The logs will not get to the server.

  • ✔ This method works.

  • ! This method has some visible drawbacks. The logs go through, but some of the values are missing/misplaced/and so on.

  • ✔? This method seems to work, but it is not recommended because this can change in a future release.

Chapter 3. Installing syslog-ng

This chapter explains how to install syslog-ng Open Source Edition on various platforms.

3.1. Procedure – Compiling syslog-ng from source

Purpose: 

To compile syslog-ng Open Source Edition (OSE) from the source code, complete the following steps. Alternatively, you can use precompiled binary packages on several platforms. For a list of third-party packages available for various Linux, UNIX, and other platforms, see the syslog-ng OSE third-party binaries page.

Steps: 

  1. Download the latest version of syslog-ng OSE from GitHub. The source code is available as a tar.gz archive file.

  2. Download the latest version of the EventLog library here or from GitHub.

  3. Install the following packages that are required to compile syslog-ng. These packages are available for most UNIX/Linux systems. Alternatively, you can also download the sources and compile them.

    • A version of the gcc C compiler that properly supports Thread Local Storage (TLS), for example, version 4.5.

    • The GNU flex lexical analyser generator, available here.

    • The bison parser generator, available here.

    • The development files of the glib library, available here.

    • The development files of the Autoconf Archive package, available here.

    • The syslog-ng OSE application now uses PCRE-type regular expressions by default. It requires the libpcre library package, available here.

    • If you want to use the Java-based modules of syslog-ng OSE (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile syslog-ng OSE with Java support.

      • Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.

      • Install gradle version 2.2.1 or newer.

      • Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH

        Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start syslog-ng OSE set LD_LIBRARY_PATH in the script as well.

      • If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.

  4. If you want to post log messages as HTTP requests using the http() destination, install the development files of the libcurl library. This library is not needed if you use the --disable-http compile option. Alternatively, you can use a Java-based implementation of the HTTP destination.

  5. If you want to use the spoof-source function of syslog-ng, install the development files of the libnet library, available here.

  6. If you want to send e-mails using the smtp() destination, install the development files of the libesmtp library. This library is not needed if you use the --disable-smtp compile option.

  7. If you want to use the /etc/hosts.deny and /etc/hosts.allow for TCP access, install the development files of the libwrap (also called TCP-wrappers) library, available here.

  8. Uncompress the eventlog archive using the

    $ tar xvfz eventlog-x.x.x.x.tar.gz

    or the

    $ gunzip -c eventlog-x.x.x.x.tar.gz | tar xvf -

    command. A new directory containing the source code of eventlog will be created.

  9. By default, eventlog creates a file used by the syslog-ng configure script in the /usr/local/lib/pkgconfig directory. Issue the following command to add this directory to your PKG_CONFIG_PATH:

    PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
  10. Enter the new directory and issue the following commands. (If the ./configure file does not exist, for example, because you cloned the repository from GitHub instead of using a release tarball, execute the ./autogen.sh command.)

    $ ./configure
    $ make
    $ make install
  11. Uncompress the syslog-ng archive using the

    tar xvfz syslog-ng-x.xx.tar.gz

    or the

    unzip -c syslog-ng-x.xx.tar.gz | tar xvf -

    command. A new directory containing the source code of syslog-ng will be created.

  12. Enter the new directory and issue the following commands:

    $ ./configure
    $ make
    $ make install

    These commands will build syslog-ng using its default options.

    Note
    • On Solaris, use gmake (GNU make) instead of make.

    • To build syslog-ng OSE with less verbose output, use the make V=0 command. This results in shorter, less verbose output, making warnings and other anomalies easier to notice. Note that silent-rules support is only available in recent automake versions.

  13. If needed, use the following options to change how syslog-ng is compiled using the following command syntax:

    $ ./configure --compile-time-option-name
    Note

    You can also use --disable options, to explicitly disable a feature and override autodetection. For example, to disable the TCP-wrapper support, use the --disable-tcp-wrapper option. For the list of available compiling options, see Section 3.2, Compiling options of syslog-ng OSE.

    Warning

    The default linking mode of syslog-ng is dynamic. This means that syslog-ng might not be able to start up if the /usr directory is on NFS. On platforms where syslog-ng is used as a system logger, the --enable-mixed-linking is preferred.

3.2. Compiling options of syslog-ng OSE

When compiling syslog-ng OSE from source, you can use the following compiling options.

  • --enable-all-modules This option will turn on or off all modules and most features when enabled, unless a feature is explicitly disabled, or not detected automatically. Currently, this means that you must explicitly enable the pacct() source, since it is not detected automatically (all other modules are compiled automatically if the required libraries are available).

    This also means that the Sun Streams source is enabled on every platform, not only on Solaris, causing a compile error. Use --enable-all-modules together with --disable-sun-streams.

  • --disable-http Disable support for the http() destination that is based on libcurl.

  • --disable-python Disable support for Python-based modules.

  • --disable-json Disable JSON support. It also disables json-parser, and the format-cim and format-json template functions. Also, it disables JSON support even if the json-c library is installed and detected (see --enable-json).

  • --disable-smtp Disable SMTP support. By default, SMTP support is enabled if the libesmtp library is detected.

  • --enable-amqp Enable the amqp destination (enabled by default). The source of the RabbitMQ client is included in the source code package of syslog-ng OSE. To use an external client instead, use the --with-librabbitmq-client=system compiling option. For details on using this destination, see Section 7.1, Publishing messages using AMQP.

  • --enable-debug Include debug information.

  • --enable-dynamic-linking Compile syslog-ng as a completely dynamic binary. If not specified syslog-ng uses mixed linking (--enable-mixed-linking): it links dynamically to system libraries and statically to everything else.

  • --enable-geoip Enable GEOIP support, required for the geoip template function and the geoip-parser (enabled automatically if the libgeoip library is detected).

  • --enable-ipv6 Enable IPv6 support.

  • --enable-java Enable support for Java-based modules. For other requirements, see the description of the Java-based module (for example, Procedure 7.2.1, Prerequisites) that you want to use.

  • --enable-java-modules Compile the Gradle projects of every Java module available in modules/java-modules.

  • --enable-json Enables JSON support (enabled automatically if the json-c 0.9 or newer library is installed and detected). JSON support is required for json-parser, and the format-cim and format-json template functions.

  • --enable-linux-caps Enable support for capabilities on Linux. For details, see syslog-ng(8).

  • --enable-mongodb Enable the mongodb destination (enabled by default). The source of the MongoDB client is included in the source code package of syslog-ng OSE. To use an external MongoDB client instead, use the --with-libmongo-client=system compiling option. For details on using this destination, see Section 7.12, Storing messages in a MongoDB database.

  • --enable-pacct Enable using the pacct() driver to collect process-accounting logs on Linux systems.

  • --enable-python Enable support for Python-based modules.

  • --enable-redis Enable the redis destination (enabled by default). The source of the libhiredis client (0.11 or newer) must be available. To specify the location of the library, use the --with-libhiredis=<path-to-libhiredis> compiling option. For details on using this destination, see Section 7.17, Storing name-value pairs in Redis.

  • --enable-riemann Enable the riemann destination (enabled by default). The source of the libriemann client must be available. For details on using this destination, see Section 7.18, Monitoring your data with Riemann.

  • --enable-spoof-source Enable spoof_source feature (disabled by default).

  • --enable-sql Enables the sql() destination (enabled automatically if the libdbi library version 0.9 or newer is installed and detected).

  • --enable-ssl Enable SSL support, required for encrypted message transfer, as well as template functions that calculate hashes and UUIDs (enabled automatically if the libopenssl library is detected).

  • --enable-sun-door Enable Sun door support even if not detected (autodetected by default).

  • --enable-sun-streams Enable Sun STREAMS support even if not detected (autodetected by default).

  • --enable-systemd Enable systemd support on Linux platforms (autodetected by default) (enabled automatically if the libsystemd-daemon library is detected).

  • --enable-tcp-wrapper Enable using /etc/hosts.deny and /etc/hosts.allow for TCP access (enabled automatically if the libwrap libraries are detected).

  • --with-embedded-crypto If this option is set, the crypto library is linked directly into libsyslog-ng: the sources of libsyslog-ng-crypto will be appended to the libsyslog-ng sources, and -crypto is not built.

  • --with-ivykis Specifies which ivykis implementation to use (default value: internal). The source of ivykis is included in the source code package of syslog-ng OSE and is used by default. To use an external implementation instead, use the --with-ivykis=system compiling option.

  • --with-libcurl Specifies the path to the libcurl library. For details on using this destination, see Section 7.8, Posting messages over HTTP without Java.

  • --with-libhiredis Specifies the path to the libhiredis library (0.11 or newer). For details on using this destination, see Section 7.17, Storing name-value pairs in Redis.

  • --with-libmongo-client Specifies which MongoDB client to use (default value: auto). The source of the mongodb client is included in the source code package of syslog-ng OSE, but the compiler will use an external MongoDB client if it is installed. To force the compiler to use the internal client instead, use the --with-libmongo-client=internal compiling option. For details on using this destination, see Section 7.12, Storing messages in a MongoDB database.

  • --with-librabbitmq-client Specifies which RabbitMQ client to use (default value: internal). The source of the rabbitmq client is included in the source code package of syslog-ng OSE and is used by default. To use an external client instead, use the --with-librabbitmq-client=system compiling option. For details on using this destination, see Section 7.1, Publishing messages using AMQP.

  • --with-module-dir Specifies a single directory where the syslog-ng OSE Makefile will install the modules.

  • --with-module-path Specifies a colon-separated (:) list of directories, where the syslog-ng OSE binary will search for modules.

  • --with-python Specifies which Python version to use, for example, --with-python=2.7

  • --with-timezone-dir Specifies the directory where syslog-ng looks for the timezone files to resolve the time-zone() and local-time-zone() options. If not specified, the /opt/syslog-ng/share/zoneinfo/ and /usr/share/zoneinfo/ directories are checked, respectively. Note that HP-UX uses a unique file format (tztab) to describe the timezone information, but that format is currently not supported in syslog-ng. As a workaround, copy the zoneinfo files from another, non-HP-UX system to the /opt/syslog-ng/share/zoneinfo/ directory of your HP-UX system.

  • --without-compile-date Removes the compilation date from the binary. For example, as openSUSE checks if recompilation changes the binary to detect if dependent packages need to be rebuilt or not, and including the date changes the binary every time.

3.3. Uninstalling syslog-ng OSE

If you need to uninstall syslog-ng OSE for some reason, you have the following options:

  • If you have installed syslog-ng OSE from a .deb package: Execute the dpkg -r syslog-ng command to remove syslog-ng, or the dpkg -P syslog-ng command to remove syslog-ng OSE and the configuration files as well. Note that removing syslog-ng OSE does not restore the syslog daemon used before syslog-ng.

  • If you have installed syslog-ng OSE from an .rpm package: Execute the rpm -e syslog-ng command to remove syslog-ng OSE. Note that removing syslog-ng OSE does not restore the syslog daemon used before syslog-ng OSE.

3.4. Procedure – Configuring Microsoft SQL Server to accept logs from syslog-ng

Purpose: 

Complete the following steps to configure your Microsoft SQL Server to enable remote logins and accept log messages from syslog-ng.

Steps: 

  1. Start the SQL Server Management Studio application. Select Start > Programs > Microsoft SQL Server 2005 > SQL Server Management Studio.

  2. Create a new database.

    1. Figure 3.1. Creating a new MSSQL database 1.

      Creating a new MSSQL database 1.

      In the Object Explorer, right-click on the Databases entry and select New Database.

    2. Figure 3.2. Creating a new MSSQL database 2.

      Creating a new MSSQL database 2.

      Enter the name of the new database (for example syslogng) into the Database name field and click OK.

  3. Create a new database user and associate it with the new database.

    1. Figure 3.3. Creating a new MSSQL user 1.

      Creating a new MSSQL user 1.

      In the Object Explorer, select Security, right-click on the Logins entry, then select New Login.

    2. Figure 3.4. Creating a new MSSQL user 2.

      Creating a new MSSQL user 2.

      Enter a name (for example syslog-ng) for the user into the Login name field.

    3. Select the SQL Server Authentication option and enter a password for the user.

    4. In the Default database field, select the database created in Step 2 (for example syslogng).

    5. In the Default language field, select the language of log messages that you want to store in the database, then click OK.

      Warning

      Incorrect language settings may result in the database converting the messages to a different character-encoding format. That way the log messages may become unreadable, causing information loss.

    6. In the Object Explorer, select Security > Logins, then right-click on the new login created in the previous step, and select Properties.

    7. Figure 3.5. Associating database with the new user

      Associating database with the new user

      Select User Mapping. In the Users mapped to this login option, check the line corresponding to the new login (for example syslogng). In the Database role membership field, check the db_owner and public options.

  4. Figure 3.6. Associating database with the new user

    Associating database with the new user

    Enable remote logins for SQL users.

    In the Object Explorer right-click on your database server, and select Properties > Security, and set the Server Authentication option to SQL Server and Windows Authentication mode.

Chapter 4. The syslog-ng OSE quick-start guide

This chapter provides a very brief introduction into configuring the syslog-ng OSE application. For details on the format of the configuration file and how to configure sources, destinations, and other features, refer to the subsequent chapters.

4.1. Procedure – Configuring syslog-ng on client hosts

Purpose: 

To configure syslog-ng on a client host, complete the following steps.

Steps: 

  1. Install the syslog-ng application on the host. For details installing syslog-ng on specific operating systems, see Chapter 3, Installing syslog-ng.

  2. Configure the local sources to collect the log messages of the host. Starting with version 3.2, syslog-ng OSE automatically collects the log messages that use the native system logging method of the platform, for example, messages from /dev/log on Linux, or /dev/klog on FreeBSD. For a complete list of messages that are collected automatically, see Section 6.12, Collecting the system-specific log messages of a platform.

    To configure syslog-ng OSE, edit the syslog-ng.conf file with any regular text editor application. The location of the configuration file depends on how you installed syslog-ng OSE. Native packages of a platform (like the ones downloaded from Linux repositories) typically place the configuration file under the /etc/syslog-ng/ directory.

    Add sources to collect the messages from your log files. File sources look like this:

    source s_myfilesource {
            file("/var/log/myapplication.log" follow-freq(1)); };

    Name every source uniquely. For details on configuring file sources, see Section 6.3, Collecting messages from text files.

    Tip

    Many applications send log messages to logfiles by default (for example, the Roundcube webmail client, or the ProFTPD FTP server), but can be configured to send them to syslog instead. If possible, it is recommended to reconfigure the application that way.

    Note

    The default configuration file of syslog-ng OSE collects platform-specific log messages and the internal log messages of syslog-ng OSE.

    source s_local {
            system();
            internal();
    };
  3. Create a network destination that points directly to the syslog-ng server, or to a local relay. The network destination greatly depends on the protocol that your log server or relay accepts messages. Many systems still use the legacy BSD-syslog protocol (RFC3162) over the unreliable UDP transport:

    destination d_network { network("10.1.2.3" transport("udp")); };

    However, if possible, use the much more reliable IETF-syslog protocol over TCP transport:

    destination d_network { syslog("10.1.2.3" transport("tcp")); };
  4. Create a log statement connecting the local sources to the syslog-ng server or relay. For example:

    log {
            source(s_local); destination(d_network); };
  5. If the logs will also be stored locally on the host, create local file destinations.

    Note

    The default configuration of syslog-ng OSE places the collected messages into the /var/log/messages file:

    destination d_local {
        file("/var/log/messages"); };
  6. Create a log statement connecting the local sources to the file destination.

    Note

    The default configuration of syslog-ng OSE has only one log statement:

    log {
        source(s_local); destination(d_local); };
  7. Set filters, macros and other features and options (for example TLS encryption) as necessary.

    Example 4.1. The default configuration file of syslog-ng OSE

    The following is the default configuration file of syslog-ng OSE 3.9. It collects local log messages and the log messages of syslog-ng OSE and saves them in the /var/log/messages file.

    @version: 3.9
    @include "scl.conf"
    source s_local { system(); internal(); };
    destination d_local {
                file("/var/log/messages"); };
    log { source(s_local); destination(d_local); };
    Example 4.2. A simple configuration for clients

    The following is a simple configuration file that collects local log messages and forwards them to a logserver using the IETF-syslog protocol.

    @version: 3.9
    @include "scl.conf"
    source s_local { system(); internal(); };
    destination d_syslog_tcp {
                 syslog("192.168.1.1" transport("tcp") port(2010)); };
    log { source(s_local);destination(d_syslog_tcp); };

4.2. Procedure – Configuring syslog-ng on server hosts

Purpose: 

To configure syslog-ng on a server host, complete the following steps.

Steps: 

  1. Install the syslog-ng application on the host. For details installing syslog-ng on specific operating systems, see Chapter 3, Installing syslog-ng.

  2. Starting with version 3.2, syslog-ng OSE automatically collects the log messages that use the native system logging method of the platform, for example, messages from /dev/log on Linux, or /dev/klog on FreeBSD. For a complete list of messages that are collected automatically, see Section 6.12, Collecting the system-specific log messages of a platform.

  3. To configure syslog-ng OSE, edit the syslog-ng.conf file with any regular text editor application. The location of the configuration file depends on how you installed syslog-ng OSE. Native packages of a platform (like the ones downloaded from Linux repositories) typically place the configuration file under the /etc/syslog-ng/ directory.

    Configure the network sources that collect the log messages sent by the clients and relays. How the network sources should be configured depends also on the capabilities of your client hosts: many older networking devices support only the legacy BSD-syslog protocol (RFC3164) using UDP transport:

    source s_network { syslog(ip(10.1.2.3) transport("udp")); };

    However, if possible, use the much more reliable TCP transport:

    source s_network { syslog(ip(10.1.2.3) transport("tcp")); };

    For other options, see Section 6.11, Collecting messages using the IETF syslog protocol (syslog() driver) and Section 6.15, Collecting messages from remote hosts using the BSD syslog protocol.

    Note

    Starting with syslog-ng OSE version 3.2, the syslog() source driver can handle both BSD-syslog (RFC 3164) and IETF-syslog (RFC 5424-26) messages.

  4. Create local destinations that will store the log messages, for example file- or program destinations. The default configuration of syslog-ng OSE places the collected messages into the /var/log/messages file:

    destination d_local {
        file("/var/log/messages"); };

    If you want to create separate logfiles for every client host, use the ${HOST} macro when specifying the filename, for example:

    destination d_local {
        file("/var/log/messages_${HOST}"); };

    For details on further macros and how to use them, see Chapter 11, Manipulating messages.

  5. Create a log statement connecting the sources to the local destinations.

    log {
            source(s_local); source(s_network); destination(d_local); };
  6. Set filters, options (for example TLS encryption) and other advanced features as necessary.

    Note

    By default, the syslog-ng server will treat the relayed messages as if they were created by the relay host, not the host that originally sent them to the relay. In order to use the original hostname on the syslog-ng server, use the keep-hostname(yes) option both on the syslog-ng relay and the syslog-ng server. This option can be set individually for every source if needed.

    If you are relaying log messages and want to resolve IP addresses to hostnames, configure the first relay to do the name resolution.

    Example 4.3. A simple configuration for servers

    The following is a simple configuration file for syslog-ng Open Source Edition that collects incoming log messages and stores them in a text file.

    @version: 3.9
    @include "scl.conf"
        options {
            time-reap(30);
            mark-freq(10);
            keep-hostname(yes);
            };
        source s_local { system(); internal(); };
        source s_network {
            syslog(transport(tcp));
            };
        destination d_logs {
            file(
                "/var/log/syslog-ng/logs.txt"
                owner("root")
                group("root")
                perm(0777)
                ); };
        log { source(s_local); source(s_network); destination(d_logs); };

4.3. Configuring syslog-ng relays

This section describes how to configure syslog-ng OSE as a relay.

4.3.1. Procedure – Configuring syslog-ng on relay hosts

Purpose: 

To configure syslog-ng on a relay host, complete the following steps:

Steps: 

  1. Install the syslog-ng application on the host. For details installing syslog-ng on specific operating systems, see Chapter 3, Installing syslog-ng.

  2. Configure the network sources that collect the log messages sent by the clients.

  3. Create a network destination that points to the syslog-ng server.

  4. Create a log statement connecting the network sources to the syslog-ng server.

  5. Configure the local sources that collect the log messages of the relay host.

  6. Create a log statement connecting the local sources to the syslog-ng server.

  7. Enable the keep-hostname() and disable the chain-hostnames() options. (For details on how these options work, see Section chain-hostnames().)

    Note

    It is recommended to use these options on your syslog-ng OSE server as well.

  8. Set filters and options (for example TLS encryption) as necessary.

    Note

    By default, the syslog-ng server will treat the relayed messages as if they were created by the relay host, not the host that originally sent them to the relay. In order to use the original hostname on the syslog-ng server, use the keep-hostname(yes) option both on the syslog-ng relay and the syslog-ng server. This option can be set individually for every source if needed.

    If you are relaying log messages and want to resolve IP addresses to hostnames, configure the first relay to do the name resolution.

    Example 4.4. A simple configuration for relays

    The following is a simple configuration file that collects local and incoming log messages and forwards them to a logserver using the IETF-syslog protocol.

    @version: 3.9
    @include "scl.conf"
        options {
            time-reap(30);
            mark-freq(10);
            keep-hostname(yes);
            chain-hostnames(no);
            };
        source s_local { system(); internal(); };
        source s_network {
            syslog(transport(tcp));
            };
        destination d_syslog_tcp {
            syslog("192.168.1.5" transport("tcp") port(2010));
        };
    
        log { source(s_local); source(s_network);
              destination(d_syslog_tcp);
            };

4.3.2. How relaying log messages works

Depending on your exact needs about relaying log messages, there are many scenarios and syslog-ng OSE options that influence how the log message will look like on the logserver. Some of the most common cases are summarized in the following example.

Consider the following example: client-host > syslog-ng-relay > syslog-ng-server, where the IP address of client-host is 192.168.1.2. The client-host device sends a syslog message to syslog-ng-relay. Depending on the settings of syslog-ng-relay, the following can happen.

  • By default, the keep-hostname() option is disabled, so syslog-ng-relay writes the IP address of the sender host (in this case, 192.168.1.2) to the HOST field of the syslog message, discarding any IP address or hostname that was originally in the message.

  • If the keep-hostname() option is enabled on syslog-ng-relay, but name resolution is disabled (the use-dns() option is set to no), syslog-ng-relay uses the HOST field of the message as-is, which is probably 192.168.1.2.

  • To resolve the 192.168.1.2 IP address to a hostname on syslog-ng-relay using a DNS server, use the keep-hostname(no) and use-dns(yes) options. If the DNS server is properly configured and reverse DNS lookup is available for the 192.168.1.2 address, syslog-ng OSE will rewrite the HOST field of the log message to client-host.

    Note

    It is also possible to resolve IP addresses locally, without relying on the DNS server. For details on local name resolution, see Procedure 19.3.1, Resolving hostnames locally.

  • The above points apply to the syslog-ng OSE server (syslog-ng-server) as well, so if syslog-ng-relay is configured properly, use the keep-hostname(yes) option on syslog-ng-server to retain the proper HOST field. Setting keep-hostname(no) on syslog-ng-server would result in syslog-ng OSE rewriting the HOST field to the address of the host that sent the message to syslog-ng-server, which is syslog-ng-relay in this case.

  • If you cannot or do not want to resolve the 192.168.1.2 IP address on syslog-ng-relay, but want to store your log messages on syslog-ng-server using the IP address of the original host (that is, client-host), you can enable the spoof-source() option on syslog-ng-relay. However, spoof-source() works only under the following conditions:

    • The syslog-ng OSE binary has been compiled with the --enable-spoof-source option.

    • The log messages are sent using the highly unreliable UDP transport protocol. (Extremely unrecommended.)

Chapter 5. The syslog-ng OSE configuration file

Location of the syslog-ng configuration file. To configure syslog-ng OSE, edit the syslog-ng.conf file with any regular text editor application. The location of the configuration file depends on how you installed syslog-ng OSE. Native packages of a platform (like the ones downloaded from Linux repositories) typically place the configuration file under the /etc/syslog-ng/ directory.

The configuration syntax in detail. Every syslog-ng configuration file must begin with a line containing the version information of syslog-ng. For syslog-ng version 3.9, this line looks like:

@version: 3.9

Versioning the configuration file was introduced in syslog-ng 3.0. If the configuration file does not contain the version information, syslog-ng assumes that the file is for syslog-ng version 2.x. In this case it interprets the configuration and sends warnings about the parts of the configuration that should be updated. Version 3.0 and later will correctly operate with configuration files of version 2.x, but the default values of certain parameters have changed since 3.0.

Example 5.1. A simple configuration file

The following is a very simple configuration file for syslog-ng: it collects the internal messages of syslog-ng and the messages from /dev/log into the /var/log/messages_syslog-ng.log file.

@version: 3.9

source s_local { unix-dgram("/dev/log"); internal(); };

destination d_file { file("/var/log/messages_syslog-ng.log"); };

log { source(s_local); destination(d_file); };

As a syslog-ng user described on a mailing list:

 

The syslog-ng's config file format was written by programmers for programmers to be understood by programmers. That may not have been the stated intent, but it is how things turned out. The syntax is exactly that of C, all the way down to braces and statement terminators.

 
  --Alan McKinnon
  • The main body of the configuration file consists of object definitions: sources, destinations, logpaths define which log message are received and where they are sent. All identifiers, option names and attributes, and any other strings used in the syslog-ng configuration file are case sensitive. Objects must be defined before they are referenced in another statement. Object definitions (also called statements) have the following syntax:

    object_type object_id {<options>};
    • Type of the object: One of source, destination, log, filter, parser, rewrite rule, or template.

    • Identifier of the object: A unique name identifying the object. When using a reserved word as an identifier, enclose the identifier in quotation marks.

      Tip

      Use identifiers that refer to the type of the object they identify. For example, prefix source objects with s_, destinations with d_, and so on.

      Note

      Repeating a definition of an object (that is, defining the same object with the same id more than once) is not allowed, unless you use the @define allow-config-dups 1 definition in the configuration file.

    • Parameters: The parameters of the object, enclosed in braces {parameters}.

    • Semicolon: Object definitions end with a semicolon (;).

    For example, the following line defines a source and calls it s_internal.

    source s_internal { internal(); };

    The object can be later referenced in other statements using its ID, for example, the previous source is used as a parameter of the following log statement:

    log { source(s_internal); destination(d_file); };
  • The parameters and options within a statement are similar to function calls of the C programming language: the name of the option followed by a list of its parameters enclosed within brackets and terminated with a semicolon.

    option(parameter1, parameter2); option2(parameter1, parameter2);

    For example, the file() driver in the following source statement has three options: the filename (/var/log/apache/access.log), follow-freq(), and flags(). The follow-freq() option also has a parameter, while the flags() option has two parameters.

    source s_tail { file("/var/log/apache/access.log"
        follow-freq(1) flags(no-parse, validate-utf8)); };

    Objects may have required and optional parameters. Required parameters are positional, meaning that they must be specified in a defined order. Optional parameters can be specified in any order using the option(value) format. If a parameter (optional or required) is not specified, its default value is used. The parameters and their default values are listed in the reference section of the particular object.

    Example 5.2. Using required and optional parameters

    The unix-stream() source driver has a single required argument: the name of the socket to listen on. Optional parameters follow the socket name in any order, so the following source definitions have the same effect:

    source s_demo_stream1 {
            unix-stream("<path-to-socket>" max-connections(10) group(log)); };
    source s_demo_stream2 {
            unix-stream("<path-to-socket>" group(log) max-connections(10)); };
  • Some options are global options, or can be set globally, for example, whether syslog-ng OSE should use DNS resolution to resolve IP addresses. Global options are detailed in Chapter 9, Global options of syslog-ng OSE.

    options { use-dns(no); };
  • All identifiers, attributes, and any other strings used in the syslog-ng configuration file are case sensitive.

  • Objects can be used before definition.

  • Objects can be defined inline as well. This is useful if you use the object only once (for example, a filter). For details, see Section 5.2, Defining configuration objects inline.

  • To add comments to the configuration file, start a line with # and write your comments. These lines are ignored by syslog-ng.

    # Comment: This is a stream source
    source s_demo_stream {
            unix-stream("<path-to-socket>" max-connections(10) group(log)); };
Tip

Before activating a new configuration, check that your configuration file is syntactically correct using the syslog-ng --syntax-only command.

To activate the configuration, reload the configuration of syslog-ng using the /etc/init.d/syslog-ng reload command.

5.1. Notes about the configuration syntax

When you are editing the syslog-ng configuration file, note the following points:

  • The configuration file can contain a maximum of 6665 source / destination / log elements.

  • When writing the names of options and parameters (or other reserved words), the hyphen (-) and underscore (_) characters are equivalent, for example max-connections(10) and max_connections(10) are both correct.

  • Numbers can be prefixed with + or - to indicate positive or negative values. Numbers beginning with zero (0) or 0x are treated as octal or hexadecimal numbers, respectively.

    Starting with syslog-ng OSE version 3.5, you can use suffixes for kilo-, mega-, and gigabytes. Use the Kb, Mb, or Gb suffixes for the base-10 version, and Kib, Mib, or Gib for the base-2 version. That is, 2MB means 2000000, while 2MiB means 2097152. For example, to set the log-fifo-size() option to 2000000 bytes, use log-fifo-size(2Mb).

  • You can use commas (,) to separate options or other parameters for readability, syslog-ng completely ignores them. The following declarations are equivalent:

    source s_demo_stream {
            unix-stream("<path-to-socket>" max-connections(10) group(log)); };
    source s_demo_stream {
            unix-stream("<path-to-socket>", max-connections(10), group(log)); };
  • When enclosing object IDs (for example the name of a destination) between double-quotes ("mydestination"), the ID can include whitespace as well, for example:

    source "s demo stream" {
            unix-stream("<path-to-socket>" max-connections(10) group(log)); };
  • For notes on using regular expressions, see Section 11.3, Regular expressions.

5.2. Defining configuration objects inline

Starting with syslog-ng OSE 3.4, you can define configuration objects inline, where they are actually used, without having to define them in a separate placement. This is useful if you need an object only once, for example, a filter or a rewrite rule. Every object can be defined inline: sources, destinations, filters, parsers, rewrite rules, and so on.

To define an object inline, use braces instead of parentheses. That is, instead of <object-type> (<object-id>);, you use <object-type> {<object-definition>};

Example 5.3. Using inline definitions

The following two configuration examples are equivalent. The first one uses traditional statements, while the second uses inline definitions.

source s_local {
    system();
    internal();
};
destination d_local {
    file("/var/log/messages");
};
log {
    source(s_local);
    destination(d_local);
};
log {
    source {
        system();
        internal();
    };
    destination {
        file("/var/log/messages");
    };
};

5.3. Using channels in configuration objects

Starting with syslog-ng OSE 3.4, every configuration object is a log expression. Every configuration object is essentially a configuration block, and can include multiple objects. To reference the block, only the top-level object must be referenced. That way you can use embedded log statements, junctions and in-line object definitions within source, destination, filter, rewrite and parser definitions. For example, a source can include a rewrite rule to modify the messages received by the source, and that combination can be used as a simple source in a log statement. This feature allows you to preprocess the log messages very close to the source itself.

To embed multiple objects into a configuration object, use the following syntax. Note that you must enclose the configuration block between braces instead of parenthesis.

<type-of-top-level-object> <name-of-top-level-object> {
    channel {
        <configuration-objects>
    };
};
Example 5.4. Using channels

For example, to process a log file in a specific way, you can define the required processing rules (parsers and rewrite expressions) and combine them in a single object:

source s_apache {
    channel {
        source { file("/var/log/apache/error.log"); };
        parser(p_apache_parser);
    };
};

log { source(s_apache); ... };

The s_apache source uses a file source (the error log of an Apache webserver) and references a specific parser to process the messages of the error log. The log statement references only the s_apache source, and any other object in the log statement can already use the results of the p_apache_parserparser.

Note

You must start the object definition with a channel even if you will use a junction, for example:

parser demo-parser() {
    channel {
        junction {
            channel { ... };
            channel { ... };
        };
    };
};

If you want to embed configuration objects into sources or destinations, always use channels, otherwise the source or destination will not behave as expected. For example, the following configuration is good:

source s_filtered_hosts {
    pipe("/dev/pipe");
    syslog(ip(192.168.0.1) transport("tcp"));
    syslog(ip(127.0.0.1) transport("tcp"));
    filter(netmask(10.0.0.0/16));
};

5.4. Global and environmental variables

Starting with syslog-ng OSE version 3.2, it is possible to define global variables in the configuration file. Global variables are actually name-value pairs. When syslog-ng processes the configuration file during startup, it automatically replaces `name` with value. To define a global variable, use the following syntax:

@define name "value"

The value can be any string, but special characters must be escaped.To use the variable, insert the name of the variable enclosed between backticks (`, similarly to using variables in Linux or UNIX shells) anywhere in the configuration file.

The value of the global variable can be also specified using the following methods:

  • Without any quotes, as long as the value does not contain any spaces or special characters. In other word, it contains only the following characters: a-zA-Z0-9_..

  • Between apostrophes, in case the value does not contain apostrophes.

  • Between double quotes, in which case special characters must be escaped using backslashes (\).

Tip

The environmental variables of the host are automatically imported and can be used as global variables.

Example 5.5. Using global variables

For example, if an application is creating multiple log files in a directory, you can store the path in a global variable, and use it in your source definitions.

@define mypath "/opt/myapp/logs"
        source s_myapp_1 { file("`mypath`/access.log" follow-freq(1)); };
        source s_myapp_2 { file("`mypath`/error.log" follow-freq(1)); };
        source s_myapp_3 { file("`mypath`/debug.log" follow-freq(1)); };

The syslog-ng OSE application will interpret this as:

@define mypath "/opt/myapp/logs"
        source s_myapp_1 { file("/opt/myapp/logs/access.log" follow-freq(1)); };
        source s_myapp_2 { file("/opt/myapp/logs/error.log" follow-freq(1)); };
        source s_myapp_3 { file("/opt/myapp/logs/debug.log" follow-freq(1)); };

5.5. Modules in syslog-ng OSE

The syslog-ng OSE application is modular, to increase its flexibility and also to simplify the development of additional modules. Most of the functionality of syslog-ng OSE is in separate modules. That way it becomes also possible to finetune the resource requirements of syslog-ng OSE, for example, by loading only the modules that are actually used in the configuration, or simply omitting modules that are not used but require large amount of memory.

Each module contains one or more plugins, which add some functionality to syslog-ng OSE, for example, a destination or a source driver.

  • To display the list of available modules, execute the syslog-ng --version command.

  • To the description of the available modules, execute the syslog-ng --module-registry command.

  • To customize which modules are loaded automatically when syslog-ng OSE is started, use the --default-modules command-line option of syslog-ng OSE.

  • To request loading a module from the syslog-ng OSE configuration file, see Section 5.5.1, Loading modules.

For details on the command-line parameters of syslog-ng OSE mentioned in the previous list, see the syslog-ng OSE man page at syslog-ng(8).

5.5.1. Loading modules

The syslog-ng Open Source Edition application loads every available module during startup.

To load a module that is not loaded automatically, include the following statement in the syslog-ng OSE configuration file:

@module <module-name>

Note the following points about the @module statement:

  • The @module statement is a top-level statement, that is, it cannot be nested into any other statement. Usually it is used immediately after the @version statement.

  • Every @module statement loads a single module: loading multiple modules requires a separate @module statement for every module.

  • In the configuration file, the @module statement of a module must be earlier than the module is used.

Note

To disable loading every module automatically, set the autoload-compiled-modules global variable to 0 in your configuration file:

@define autoload-compiled-modules 0

Note that in this case, you have to explicitly load the modules you want to use.

5.6. Managing complex syslog-ng configurations

The following sections describe some methods that can be useful to simplify the management of large-scale syslog-ng installations.

5.6.1. Including configuration files

The syslog-ng application supports including external files in its configuration file, so parts of its configuration can be managed separately. To include the contents of a file in the syslog-ng configuration, use the following syntax:

@include "<filename>"

This imports the entire file into the configuration of syslog-ng OSE, at the location of the include statement. The <filename> can be one of the following:

  • A filename, optionally with full path. The filename (not the path) can include UNIX-style wildcard characters (*, ?). When using wildcard characters, syslog-ng OSE will include every matching file. For details on using wildcard characters, see Section glob.

  • A directory. When including a directory, syslog-ng OSE will try to include every file from the directory, except files beginning with a ~ (tilde) or a . (dot) character. Including a directory is not recursive. The files are included in alphabetic order, first files beginning with uppercase characters, then files beginning with lowercase characters. For example, if the directory contains the a.conf, B. conf, c.conf, D.conf files, they will be included in the following order: B.conf, D. conf, a.conf, c.conf.

When including configuration files, consider the following points:

  • Defining an object twice is not allowed, unless you use the @define allow-config-dups 1 definition in the configuration file. If an object is defined twice (for example the original syslog-ng configuration file and the file imported into this configuration file both define the same option, source, or other object), then the object that is defined later in the configuration file will be effective. For example, if you set a global option at the beginning of the configuration file, and later include a file that defines the same option with a different value, then the option defined in the imported file will be used.

  • Files can be embedded into each other: the included files can contain include statements as well, up to a maximum depth of 15 levels.

  • You cannot include complete configuration files into each other, only configuration snippets can be included. This means that the included file cannot have a @version statement.

  • Include statements can only be used at top level of the configuration file. For example, the following is correct:

    @version: 3.9
    @include "example.conf"

    But the following is not:

    source s_example {
        @include "example.conf"
    };
Warning

The syslog-ng application will not start if it cannot find a file that is to be included in its configuration. Always double-check the filenames, paths, and access rights when including configuration files, and use the --syntax-only command-line option to check your configuration.

5.6.2. Reusing configuration blocks

To create a reusable configuration snippet and reuse parts of a configuration file, you have to define the block (for example, a source) once, and reference it later. (Such reusable blocks are sometimes called a Source Configuration Library, or SCL.) Any syslog-ng object can be a block. Use the following syntax to define a block:

block type name() {<contents of the block>};

Type must be one of the following: destination, filter, log, parser, rewrite, root, source. The root blocks can be used in the "root" context of the configuration file, that is, outside any other statements.

Blocks may be nested into each other, so for example a block can be built from other blocks. Blocks are somewhat similar to C++ templates.

The type and name combination of each block must be unique, that is, two blocks can have the same name if their type is different.

To use a block in your configuration file, you have to do two things:

  • Include the file defining the block in the syslog-ng.conf file — or a file already included into syslog-ng.conf. Version 3.7 and newer automatically includes the *.conf files from the <directory-where-syslog-ng-is-installed>/scl/*/ directories.

  • Reference the name of the block in your configuration file. This will insert the block into your configuration. For example, to use a block called myblock, include the following line in your configuration:

    myblock()

    Blocks may have parameters, but even if they do not, the reference must include opening and closing parentheses like in the previous example.

The contents of the block will be inserted into the configuration when syslog-ng OSE is started or reloaded.

Example 5.6. Reusing configuration blocks

Suppose you are running an application on your hosts that logs into the /opt/var/myapplication.log file. Create a file (for example, myblocks.conf) that stores a source describing this file and how it should be read:

block source myappsource() {
        file("/opt/var/myapplication.log" follow-freq(1) default-facility(syslog)); };

Include this file in your main syslog-ng configuration file, reference the block, and use it in a logpath:

@version: 3.9
@include "<correct/path>/myblocks.conf"
source s_myappsource { myappsource(); };
...
log { source(s_myappsource); destination(...); };

To define a block that defines more than one object, use root as the type of the block, and reference the block from the main part of the syslog-ng OSE configuration file.

Example 5.7. Defining blocks with multiple elements

The following example defines a source, a destination, and a log path to connect them.

block root mylogs() {
        source s_file { file("/var/log/mylogs.log" follow-freq(1)); };
        destination d_local { file("/var/log/messages"); };
        log { source(s_file); destination(d_local); };
};
Tip

Since the block is inserted into the syslog-ng OSE configuration when syslog-ng OSE is started, the block can be generated dynamically using an external script if needed. This is useful when you are running syslog-ng OSE on different hosts and you want to keep the main configuration identical.

If you want to reuse more than a single configuration object, for example, a logpath and the definitions of its sources and destinations, use the include feature to reuse the entire snippet. For details, see Section 5.6.1, Including configuration files.

5.6.2.1. Passing arguments to configuration blocks

Configuration blocks can receive arguments as well. The parameters the block can receive must be specified when the block is defined, using the following syntax:

block type block_name(argument1(<default-value-of-the-argument>) argument2(<default-value-of-the-argument>) argument3())

If an argument does not have a default value, use empty parentheses after the name of the argument. To refer the value of the argument in the block, use the name of the argument between backticks (for example, `argument1`).

Example 5.8. Passing arguments to blocks

The following sample defines a file source block, which can receive the name of the file as a parameter. If no parameter is set, it reads messages from the /var/log/messages file.

block source s_logfile (filename("messages")) {
  file("/var/log/`filename`" );
};

source s_example {
  s_logfile(filename("logfile.log"));
};

If you reference the block with more arguments then specified in its definition, you can use these additional arguments as a single argument-list within the block. That way, you can use a variable number of optional arguments in your block. This can be useful when passing arguments to a template, or optional arguments to an underlying driver. To reference this argument-list, insert `__VARARGS__` to the place in the block where you want to insert the argument-list. Note that you can use this only once in a block. The following definition extends the logfile block from the previous example, and passes the optional arguments (follow-freq(1) flags(no-parse)) to the file() source.

block source s_logfile (filename("messages")) {
  file("/var/log/`filename`" `__VARARGS__`);
};

source s_example {
  s_logfile(filename("logfile.log") follow-freq(1) flags(no-parse));
};
Example 5.9. Using arguments in blocks

The following example is the code of the pacct() source driver, which is actually a block that can optionally receive two arguments.

block source pacct(file("/var/log/account/pacct") follow-freq(1)) {
@module pacctformat
        file("`file`" follow-freq(`follow-freq`) format("pacct") tags(".pacct") `__VARARGS__`);
};

5.6.3. Procedure – Generating configuration blocks from a script

Purpose: 

The syslog-ng OSE application can automatically execute scripts when it is started, and can include the output of such script in the configuration file. To create and use a script that generates a part of the syslog-ng OSE configuration file (actually, a configuration block), complete the following steps. The steps include examples for collecting Apache access log files (access.log) from subdirectories, but you can create any script that creates a valid syslog-ng OSE configuration snippet.

Steps: 

  1. Navigate to the directory where you have installed syslog-ng OSE (for example, /opt/syslog-ng/share/include/scl/), and create a new directory, for example, apache-access-logs. The name of the directory will be used in the syslog-ng OSE configuration file as well, so use a descriptive name.

  2. Create a file called plugin.conf in this new directory.

  3. Edit the plugin.conf file and add the following line:

    @module confgen context(source) name(<directory-name>) exec("`scl-root`/<directory-name>/<my-script>")

    Replace <directory-name> with the name of the directory (for example, apache-access-logs), and <my-script> with the filename of your script (for example, apache-access-logs.sh). You can reference the script in your syslog-ng OSE configuration file as a configuration block using the value name option.

    The context option determines the type of the configuration snippet that the script generates, and must be one of the following: destination, filter, log, parser, rewrite, root, source. The root blocks can be used in the "root" context of the configuration file, that is, outside any other statements. In the example, context(source) means that the output of the script will be used within a source statement.

  4. Write a script that generates the output you need, and formats it to a configuration snippet that syslog-ng OSE can use. The filename of the script must match with the filename used in plugin.conf, for example, apache-access-logs.sh.

    The following example checks the /var/log/apache2/ directory and its subdirectories, and creates a source driver for every directory that contains an access.log file.

    #!/bin/bash
    for i in `find /var/log/apache2/ -type d`; do
        echo "file(\"$i/access.log\" flags(no-parse) program_override(\"apache2\"));";
    done;

    The script generates an output similar to this one, where service* is the actual name of a subdirectory:

    file("/var/log/apache2/service1/access.log" flags(no-parse) program_override("apache2"));
    file("/var/log/apache2/service2/access.log" flags(no-parse) program_override("apache2"));
    
  5. Include the plugin.conf file in the syslog-ng.conf file — or a file already included into syslog-ng.conf. Version 3.7 and newer automatically includes the *.conf files from the <directory-where-syslog-ng-is-installed>/scl/*/ directories. For details on including configuration files, see Section 5.6.1, Including configuration files.

  6. Add the block you defined in the plugin.conf file to your syslog-ng OSE configuration file. You can reference the block using the value of the name option from the plugin.conf file, followed by parentheses, for example, apache-access-logs(). Make sure to use the block in the appropriate context of the configuration file, for example, within a source statement if the value of the context option in the plugin.conf file is source.

    @include "scl.conf"
    ...
    source s_apache {
        file("/var/log/apache2/access.log" flags(no-parse) program_override("apache2"));
        file("/var/log/apache2/error.log" flags(no-parse) program_override("apache2"));
        file("/var/log/apache2/ssl.log" flags(no-parse) program_override("apache2"));
        apache-access-logs();
    };
    
    log { source(s_apache); destination(d_central); };
    ...
  7. Check if your modified syslog-ng OSE configuration file is syntactically correct using the syslog-ng --syntax-only command.

  8. If your modified configuration is syntactically correct, load the new configuration file using the syslog-ng-ctl reload command.

Chapter 6. Collecting log messages — sources and source drivers

6.1. How sources work

A source is where syslog-ng receives log messages. Sources consist of one or more drivers, each defining where and how messages are received.

To define a source, add a source statement to the syslog-ng configuration file using the following syntax:

source <identifier> { source-driver(params); source-driver(params); ... };
Example 6.1. A simple source statement

The following source statement receives messages on the TCP port 1999 of the interface having the 10.1.2.3 IP address.

source s_demo_tcp { network(ip(10.1.2.3) port(1999)); };
Example 6.2. A source statement using two source drivers

The following source statement receives messages on the 1999 TCP port and the 1999 UDP port of the interface having the 10.1.2.3 IP address.

source s_demo_two_drivers {
           network(ip(10.1.2.3) port(1999));
           network(ip(10.1.2.3) port(1999) transport("udp")); };
Example 6.3. Setting default priority and facility

If the message received by the source does not have a proper syslog header, you can use the default-facility() and default-priority() options to set the facility and priority of the messages. Note that these values are applied only to messages that do not set these parameters in their header.

source headerless_messages { network(default-facility(syslog) default-priority(emerg)); };

Define a source only once. The same source can be used in several log paths. Duplicating sources causes syslog-ng to open the source (TCP/IP port, file, and so on) more than once, which might cause problems. For example, include the /dev/log file source only in one source statement, and use this statement in more than one log path if needed.

Warning

Sources and destinations are initialized only when they are used in a log statement. For example, syslog-ng OSE starts listening on a port or starts polling a file only if the source is used in a log statement. For details on creating log statements, see Chapter 8, Routing messages: log paths and filters.

To collect log messages on a specific platform, it is important to know how the native syslogd communicates on that platform. The following table summarizes the operation methods of syslogd on some of the tested platforms:

Platform Method
Linux A SOCK_DGRAM unix socket named /dev/log. Newer distributions that use systemd collect log messages into a journal file.
BSD flavors A SOCK_DGRAM unix socket named /var/run/log.
Solaris (2.5 or below) An SVR4 style STREAMS device named /dev/log.
Solaris (2.6 or above) In addition to the STREAMS device used in earlier versions, 2.6 uses a new multithreaded IPC method called door. By default the door used by syslogd is /etc/.syslog_door.
HP-UX 11 or later HP-UX uses a named pipe called /dev/log that is padded to 2048 bytes, for example source s_hp-ux {pipe ("/dev/log" pad-size(2048)}.
AIX 5.2 and 5.3 A SOCK_STREAM or SOCK_DGRAM unix socket called /dev/log.

Table 6.1. Communication methods used between the applications and syslogd


Each possible communication mechanism has a corresponding source driver in syslog-ng. For example, to open a unix socket with SOCK_DGRAM style communication use the driver unix-dgram. The same socket using the SOCK_STREAM style — as used under Linux — is called unix-stream.

Example 6.4. Source statement on a Linux based operating system

The following source statement collects the following log messages:

  • internal(): Messages generated by syslog-ng.

  • network(transport("udp")): Messages arriving to the 514/UDP port of any interface of the host.

  • unix-dgram("/dev/log");: Messages arriving to the /dev/log socket.

source s_demo {
    internal();
    network(transport("udp"));
    unix-dgram("/dev/log"); };

The following table lists the source drivers available in syslog-ng.

Name Description
file() Opens the specified file and reads messages.
internal() Messages generated internally in syslog-ng.
network() Receives messages from remote hosts using the BSD-syslog protocol over IPv4 and IPv6. Supports the TCP, UDP, and TLS network protocols.
nodejs() Receives JSON messages from nodejs applications.
pacct() Reads messages from the process accounting logs on Linux.
pipe() Opens the specified named pipe and reads messages.
program() Opens the specified application and reads messages from its standard output.
sun-stream(), sun-streams() Opens the specified STREAMS device on Solaris systems and reads incoming messages.
syslog() Listens for incoming messages using the new IETF-standard syslog protocol.
system() Automatically detects which platform syslog-ng OSE is running on, and collects the native log messages of that platform.
systemd-journal() Collects messages directly from the journal of platforms that use systemd.
systemd-syslog() Collects messages from the journal using a socket on platforms that use systemd.
unix-dgram() Opens the specified unix socket in SOCK_DGRAM mode and listens for incoming messages.
unix-stream() Opens the specified unix socket in SOCK_STREAM mode and listens for incoming messages.

Table 6.2. Source drivers available in syslog-ng


6.2. Collecting internal messages

All messages generated internally by syslog-ng use this special source. To collect warnings, errors and notices from syslog-ng itself, include this source in one of your source statements.

internal()

The syslog-ng application will issue a warning upon startup if none of the defined log paths reference this driver.

Example 6.5. Using the internal() driver
source s_local { internal(); };

The syslog-ng OSE application sends the following message types from the internal() source: 

  • fatal: Priority value: critical (2), Facility value: syslog (5)

  • error: Priority value: error (3), Facility value: syslog (5)

  • warning: Priority value: warning (4), Facility value: syslog (5)

  • notice: Priority value: notice (5), Facility value: syslog (5)

  • info: Priority value: info (6), Facility value: syslog (5)

6.2.1. internal() source options

The internal() driver has the following options:

host-override()

Type: string
Default:  

Description: Replaces the ${HOST} part of the message with the parameter string.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.6. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

normalize-hostnames()

Accepted values: yes | no
Default: no

Description: If enabled (normalize-hostnames(yes)), syslog-ng OSE converts the hostnames to lowercase.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

use-fqdn()

Type: yes or no
Default: no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

6.3. Collecting messages from text files

Collects log messages from plain-text files, for example from the logfiles of an Apache webserver.

The syslog-ng application notices if a file is renamed or replaced with a new file, so it can correctly follow the file even if logrotation is used. When syslog-ng is restarted, it records the position of the last sent log message in the /opt/syslog-ng/var/syslog-ng.persist file, and continues to send messages from this position after the restart.

The file driver has a single required parameter specifying the file to open. For the list of available optional parameters, see Section 6.3.2, file() source options.

Declaration: 

file(filename);
Example 6.7. Using the file() driver
source s_file { file("/var/log/messages"); };
Example 6.8. Tailing files

The following source checks the access.log file every second for new messages.

source s_tail { file("/var/log/apache/access.log"
            follow-freq(1) flags(no-parse)); };
Note

If the message does not have a proper syslog header, syslog-ng treats messages received from files as sent by the kern facility. Use the default-facility() and default-priority() options in the source definition to assign a different facility if needed.

6.3.1. Notes on reading kernel messages

Note the following points when reading kernel messages on various platforms.

  • The kernel usually sends log messages to a special file (/dev/kmsg on BSDs, /proc/kmsg on Linux). The file() driver reads log messages from such files. The syslog-ng application can periodically check the file for new log messages if the follow-freq() option is set.

  • On Linux, the klogd daemon can be used in addition to syslog-ng to read kernel messages and forward them to syslog-ng. klogd used to preprocess kernel messages to resolve symbols and so on, but as this is deprecated by ksymoops there is really no point in running both klogd and syslog-ng in parallel. Also note that running two processes reading /proc/kmsg at the same time might result in dead-locks.

  • When using syslog-ng to read messages from the /proc/kmsg file, syslog-ng automatically disables the follow-freq() parameter to avoid blocking the file.

  • To read the kernel messages on HP-UX platforms, use the following options in the source statement:

    file("/dev/klog" program-override("kernel") flags(kernel) follow-freq(0));

6.3.2. file() source options

The file() driver has the following options:

default-facility()

Type: facility string
Default: kern

Description: This parameter assigns a facility value to the messages received from the file source, if the message does not specify one.

default-priority()

Type: priority string
Default:  

Description: This parameter assigns an emergency level to the messages received from the file source, if the message does not specify one. For example, default-priority(warning)

file()

Type: filename with path
Default:  

Description: The file to read messages from, including the path.

encoding()

Type: string
Default:  

Description: Specifies the characterset (encoding, for example UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command. For details on how encoding affects the size of the message, see Section Message size and encoding.

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[4]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

follow-freq()

Type: number
Default: 1

Description: Indicates that the source should be checked periodically. 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 poll() on the file, but checks whether the file changed every time the follow-freq() interval (in seconds) has elapsed. Floating-point numbers (for example 1.5) can be used as well.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. Make sure that log-iw-size() is larger than the value of log-fetch-limit().

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

log-prefix() (DEPRECATED)

Type: string
Default:  

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

multi-line-garbage()

Type: regular expression
Default: empty string

Description: Use the multi-line-garbage() option when processing multi-line messages that contain unneeded parts between the messages. Specify a string or regular expression that matches the beginning of the unneeded message parts. If the multi-line-garbage() option is set, syslog-ng OSE ignores the lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix(). See also the multi-line-prefix() option.

When receiving multi-line messages from a source when the multi-line-garbage() option is set, but no matching line is received between two lines that match multi-line-prefix(), syslog-ng OSE will continue to process the incoming lines as a single message until a line matching multi-line-garbage() is received.

To use the multi-line-garbage() option, set the multi-line-mode() option to prefix-garbage.

Warning

If the multi-line-garbage() option is set, syslog-ng OSE discards lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix().

multi-line-mode()

Type: indented|regexp
Default: empty string

Description: Use the multi-line-mode() option when processing multi-line messages. The syslog-ng OSE application provides the following methods to process multi-line messages: multi-line-mode(indented), and multi-line-mode(prefix-garbage).

  • The indented mode can process messages where each line that belongs to the previous line is indented by whitespace, and the message continues until the first non-indented line. For example, the Linux kernel (starting with version 3.5) uses this format for /dev/log, as well as several applications, like Apache Tomcat.

    Example 6.9. Processing indented multi-line messages
    source s_tomcat {
        file("/var/log/tomcat/xxx.log" multi-line-mode(indented));
    };
  • The prefix-garbage mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. For details on using multi-line-mode(prefix-garbage), see the multi-line-prefix() and multi-line-garbage() options.

  • The prefix-suffix mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression set in multi-line-suffix(), and treats the lines between multi-line-prefix() and multi-line-suffix() as a single message. Any other lines between the end of the message and the beginning of a new message (that is, a line that matches the multi-line-prefix() expression) are discarded. For details on using multi-line-mode(prefix-suffix), see the multi-line-prefix() and multi-line-suffix() options.

    The prefix-suffix mode is similar to the prefix-garbage mode, but it appends the garbage part to the message instead of discarding it.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

multi-line-prefix()

Type: regular expression starting with the ^ character
Default: empty string

Description: Use the multi-line-prefix() option to process multi-line messages, that is, log messages that contain newline characters (for example, Tomcat logs). Specify a string or regular expression that matches the beginning of the log messages (always start with the ^ character). Use as simple regular expressions as possible, because complex regular expressions can severely reduce the rate of processing multi-line messages. If the multi-line-prefix() option is set, syslog-ng OSE ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. See also the multi-line-garbage() option.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

Example 6.10. Processing Tomcat logs

The log messages of the Apache Tomcat server are a typical example for multi-line log messages. The messages start with the date and time of the query in the YYYY.MM.DD HH:MM:SS format, as you can see in the following example.

2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
SEVERE: Catalina.start:
LifecycleException:  service.getName(): "Catalina";  Protocol handler start failed: java.net.BindException: Address already in use<null>:8080
       at org.apache.catalina.connector.Connector.start(Connector.java:1138)
       at org.apache.catalina.core.StandardService.start(StandardService.java:531)
       at org.apache.catalina.core.StandardServer.start(StandardServer.java:710)
       at org.apache.catalina.startup.Catalina.start(Catalina.java:583)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:288)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:177)
2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
INFO: Server startup in 1206 ms
2010.06.09. 12:45:08 org.apache.coyote.http11.Http11Protocol pause
INFO: Pausing Coyote HTTP/1.1 on http-8080
2010.06.09. 12:45:09 org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina

To process these messages, specify a regular expression matching the timestamp of the messages in the multi-line-prefix() option. Such an expression is the following:

source s_file{file("/var/log/tomcat6/catalina.2010-06-09.log" follow-freq(0) multi-line-mode(regexp) multi-line-prefix("[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.") flags(no-parse));};
};

Note that the flags(no-parse) is needed to avoid syslog-ng OSE trying to interpret the date in the message.

multi-line-suffix()

Type: regular expression
Default: empty string

Description: Use the multi-line-suffix() option when processing multi-line messages. Specify a string or regular expression that matches the end of the multi-line message.

To use the multi-line-suffix() option, set the multi-line-mode() option to prefix-suffix. See also the multi-line-prefix() option.

optional()

Type: yes or no
Default:  

Description: 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 pipe(), unix-dgram, and unix-stream drivers.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.



[4] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.4. Collecting messages using the RFC3164 protocol (network() driver)

The network() source driver can receive syslog messages conforming to RFC3164 from the network using the TCP, TLS, and UDP networking protocols.

  • 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 to retransmit lost messages. The BSD-syslog protocol traditionally uses UDP.

    Use UDP only if you have no other choice.

  • TCP provides connection-oriented service: the client and the server establish a connection, each message is acknowledged, and lost packets are resent. TCP can detect lost connections, and messages are lost, only if the TCP connection breaks. When a TCP connection is broken, messages that the client has sent but were not yet received on the server are lost.

  • The syslog-ng application supports TLS (Transport Layer Security, also known as SSL) over TCP. For details, see Section 10.2, Encrypting log messages with TLS.

Declaration: 

network([options]);

By default, the network() driver binds to 0.0.0.0, meaning that it listens on every available IPV4 interface on the TCP/601 port. To limit accepted connections to only one interface, use the localip() parameter. To listen on IPv6 addresses, use the ip-protocol(6) option.

Example 6.11. Using the network() driver

Using only the default settings: listen on every available IPV4 interface on the TCP/601 port.

source s_network {
    network();
};

UDP source listening on 192.168.1.1 (the default port for UDP is 514):

source s_network {
    network(
        ip("192.168.1.1")
        transport("udp")
        );
};

TCP source listening on the IPv6 localhost, port 2222:

source s_network6 {
        network(
            ip("::1")
            transport("tcp")
            port(2222)
            ip-protocol(6)
        );
};

A TCP source listening on a TLS-encrypted channel.

source s_network {
    network(
        transport("tcp")
        port(2222)
        tls(peer-verify("required-trusted")
            key-file("/opt/syslog-ng/etc/syslog-ng/syslog-ng.key")
            cert-file("/opt/syslog-ng/etc/syslog-ng/syslog-ng.crt")
            );
    );
};

A TCP source listening for messages using the IETF-syslog message format. Note that for transferring IETF-syslog messages, generally you are recommended to use the syslog() driver on both the client and the server, as it uses both the IETF-syslog message format and the protocol. For details, see Section 6.11, Collecting messages using the IETF syslog protocol (syslog() driver).

source s_tcp_syslog {
    network(
        ip("127.0.0.1")
        flags(syslog-protocol)
    );
};

For details on the options of the network() source, see Section 6.4.1, network() source options.

6.4.1. network() source options

The network() driver has the following options.

encoding()

Type: string
Default:  

Description: Specifies the characterset (encoding, for example UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command. For details on how encoding affects the size of the message, see Section Message size and encoding.

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[5]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

host-override()

Type: string
Default:  

Description: Replaces the ${HOST} part of the message with the parameter string.

ip() or localip()

Type: string
Default: 0.0.0.0

Description: The IP address to bind to. By default, syslog-ng OSE listens on every available interface. Note that this is not the address where messages are accepted from.

If you specify a multicast bind address and use the udp transport, syslog-ng OSE automatically joins the necessary multicast group. TCP does not support multicasting.

ip-protocol()

Type: number
Default: 4

Description: Determines the internet protocol version of the given driver (network() or syslog()). The possible values are 4 and 6, corresponding to IPv4 and IPv6. The default value is ip-protocol(4).

Note that listening on a port using IPv6 automatically means that you are also listening on that port using IPv4. That is, if you want to have receive messages on an IP-address/port pair using both IPv4 and IPv6, create a source that uses the ip-protocol(6). You cannot have two sources with the same IP-address/port pair, but with different ip-protocol() settings (it causes an Address already in use error).

For example, the following source receives messages on TCP, using the network() driver, on every available interface of the host on both IPv4 and IPv6.

source s_network_tcp { network( transport("tcp") ip("::") ip-protocol(6) port(601) ); };

ip-tos()

Type: number
Default: 0

Description: Specifies the Type-of-Service value of outgoing packets.

ip-ttl()

Type: number
Default: 0

Description: Specifies the Time-To-Live value of outgoing packets.

keep-alive()

Type: yes or no
Default: yes

Description: Specifies whether connections to sources should be closed when syslog-ng is forced to reload its configuration (upon the receipt of a SIGHUP signal). Note that this applies to the server (source) side of the syslog-ng connections, client-side (destination) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the destination.

keep-hostname()

Type: yes or no
Default: no

Description: Enable or disable hostname rewriting.

  • If enabled (keep-hostname(yes)), syslog-ng OSE assumes that the incoming log message was sent by the host specified in the HOST field of the message.

  • If disabled (keep-hostname(no)), syslog-ng OSE rewrites the HOST field of the message, either to the IP address (if the use-dns() parameter is set to no), or to the hostname (if the use-dns() parameter is set to yes and the IP address can be resolved to a hostname) of the host sending the message to syslog-ng OSE. For details on using name resolution in syslog-ng OSE, see Section 19.3, Using name resolution in syslog-ng.

Note

If the log message does not contain a hostname in its HOST field, syslog-ng OSE automatically adds a hostname to the message.

  • For messages received from the network, this hostname is the address of the host that sent the message (this means the address of the last hop if the message was transferred via a relay).

  • For messages received from the local host, syslog-ng OSE adds the name of the host.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

When relaying messages, enable this option on the syslog-ng OSE server and also on every relay, otherwise syslog-ng OSE will treat incoming messages as if they were sent by the last relay.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

listen-backlog()

Type: integer
Default: 256

Description: Available only for stream based transports (unix-stream, tcp, tls). In TCP, connections are treated incomplete until the three-way handshake is completed between the server and the client. Incomplete connection requests wait on the TCP port for the listener to accept the request. The listen-backlog() option sets the maximum number of incomplete connection requests. For example:

source s_network {
    network(
        ip("192.168.1.1")
        transport("tcp")
        listen-backlog(2048)
        );
};

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.12. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

max-connections()

Type: number
Default: 10

Description: Specifies the maximum number of simultaneous connections.

multi-line-garbage()

Type: regular expression
Default: empty string

Description: Use the multi-line-garbage() option when processing multi-line messages that contain unneeded parts between the messages. Specify a string or regular expression that matches the beginning of the unneeded message parts. If the multi-line-garbage() option is set, syslog-ng OSE ignores the lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix(). See also the multi-line-prefix() option.

When receiving multi-line messages from a source when the multi-line-garbage() option is set, but no matching line is received between two lines that match multi-line-prefix(), syslog-ng OSE will continue to process the incoming lines as a single message until a line matching multi-line-garbage() is received.

To use the multi-line-garbage() option, set the multi-line-mode() option to prefix-garbage.

Warning

If the multi-line-garbage() option is set, syslog-ng OSE discards lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix().

multi-line-mode()

Type: indented|regexp
Default: empty string

Description: Use the multi-line-mode() option when processing multi-line messages. The syslog-ng OSE application provides the following methods to process multi-line messages: multi-line-mode(indented), and multi-line-mode(prefix-garbage).

  • The indented mode can process messages where each line that belongs to the previous line is indented by whitespace, and the message continues until the first non-indented line. For example, the Linux kernel (starting with version 3.5) uses this format for /dev/log, as well as several applications, like Apache Tomcat.

    Example 6.13. Processing indented multi-line messages
    source s_tomcat {
        file("/var/log/tomcat/xxx.log" multi-line-mode(indented));
    };
  • The prefix-garbage mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. For details on using multi-line-mode(prefix-garbage), see the multi-line-prefix() and multi-line-garbage() options.

  • The prefix-suffix mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression set in multi-line-suffix(), and treats the lines between multi-line-prefix() and multi-line-suffix() as a single message. Any other lines between the end of the message and the beginning of a new message (that is, a line that matches the multi-line-prefix() expression) are discarded. For details on using multi-line-mode(prefix-suffix), see the multi-line-prefix() and multi-line-suffix() options.

    The prefix-suffix mode is similar to the prefix-garbage mode, but it appends the garbage part to the message instead of discarding it.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

multi-line-prefix()

Type: regular expression starting with the ^ character
Default: empty string

Description: Use the multi-line-prefix() option to process multi-line messages, that is, log messages that contain newline characters (for example, Tomcat logs). Specify a string or regular expression that matches the beginning of the log messages (always start with the ^ character). Use as simple regular expressions as possible, because complex regular expressions can severely reduce the rate of processing multi-line messages. If the multi-line-prefix() option is set, syslog-ng OSE ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. See also the multi-line-garbage() option.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

Example 6.14. Processing Tomcat logs

The log messages of the Apache Tomcat server are a typical example for multi-line log messages. The messages start with the date and time of the query in the YYYY.MM.DD HH:MM:SS format, as you can see in the following example.

2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
SEVERE: Catalina.start:
LifecycleException:  service.getName(): "Catalina";  Protocol handler start failed: java.net.BindException: Address already in use<null>:8080
       at org.apache.catalina.connector.Connector.start(Connector.java:1138)
       at org.apache.catalina.core.StandardService.start(StandardService.java:531)
       at org.apache.catalina.core.StandardServer.start(StandardServer.java:710)
       at org.apache.catalina.startup.Catalina.start(Catalina.java:583)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:288)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:177)
2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
INFO: Server startup in 1206 ms
2010.06.09. 12:45:08 org.apache.coyote.http11.Http11Protocol pause
INFO: Pausing Coyote HTTP/1.1 on http-8080
2010.06.09. 12:45:09 org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina

To process these messages, specify a regular expression matching the timestamp of the messages in the multi-line-prefix() option. Such an expression is the following:

source s_file{file("/var/log/tomcat6/catalina.2010-06-09.log" follow-freq(0) multi-line-mode(regexp) multi-line-prefix("[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.") flags(no-parse));};
};

Note that the flags(no-parse) is needed to avoid syslog-ng OSE trying to interpret the date in the message.

Warning

If you receive messages using the UDP protocol, do not use multi-line processing. If every line of a multi-line message is received in the same UDP packet, everything is fine, but if a multi-line message is fragmented into multiple UDP packets, the order they are received (thus the way how they are processed) cannot be guaranteed, and causes problems.

multi-line-suffix()

Type: regular expression
Default: empty string

Description: Use the multi-line-suffix() option when processing multi-line messages. Specify a string or regular expression that matches the end of the multi-line message.

To use the multi-line-suffix() option, set the multi-line-mode() option to prefix-suffix. See also the multi-line-prefix() option.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

port() or localport()

Type: number
Default:

In case of TCP transport: 601

In case of UDP transport: 514

Description: The port number to bind to.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

so-broadcast()

Type: yes or no
Default: no

Description: This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. For details, see the socket(7) manual page.

so-keepalive()

Type: yes or no
Default: no

Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.

so-rcvbuf()

Type: number
Default: 0

Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.

Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

so-sndbuf()

Type: number
Default: 0

Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

transport()

Type: udp, tcp, or tls
Default: tcp

Description: Specifies the protocol used to receive messages from the source.

Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

tls()

Type: tls options
Default: n/a

Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see Section 10.4, TLS options.

use-dns()

Type: yes, no, persist_only
Default: yes

Description: Enable or disable DNS usage. The persist_only option attempts to resolve hostnames locally from file (for example from /etc/hosts). The syslog-ng OSE application 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. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

use-fqdn()

Type: yes or no
Default: no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.



[5] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.5. Receiving JSON messages from nodejs applications

Using the nodejs() driver, syslog-ng OSE can receive application logs directly from nodejs applications that use the widespread Winston logging API. The syslog-ng OSE application automatically adds the .nodejs.winston. prefix to the name of the fields the extracted from the message.

To use the nodejs() driver, the scl.conf file must be included in your syslog-ng OSE configuration:

@include "scl.conf"

The nodejs() driver is actually a reusable configuration snippet configured to receive log messages using the network() driver, and process its JSON contents. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the nodejs configuration snippet on GitHub.

Example 6.15. Using the nodejs() driver

The following example uses the default settings of the driver, listening for messages on port 9003 of every IP address of the syslog-ng OSE host.

@include "scl.conf"
source apps { nodejs(); };

The following example listens only on IP address 192.168.1.1, port 9999.

@include "scl.conf"
source apps { nodejs(
            localip(192.168.1.1)
            port(9999)
            )
};
Note

For details on the parameters of the nodejs() driver, see Section 6.5.1, nodejs() source options.

6.5.1. nodejs() source options

The nodejs() driver has the following options.

ip() or localip()

Type: string
Default: 0.0.0.0

Description: The IP address to bind to. By default, syslog-ng OSE listens on every available interface. Note that this is not the address where messages are accepted from.

If you specify a multicast bind address and use the udp transport, syslog-ng OSE automatically joins the necessary multicast group. TCP does not support multicasting.

port() or localport()

Type: number
Default: 9003

Description: The port number to bind to.

6.6. Converting local e-mail messages to log messages

Using the mbox() driver, syslog-ng OSE can read e-mail messages from local mbox files, and convert them to multiline log messages.

This driver has only one required option, the filename of the mbox file. To use the mbox() driver, the scl.conf file must be included in your syslog-ng OSE configuration:

@include "scl.conf"

The mbox() driver is actually a reusable configuration snippet configured to read log messages using the file() driver. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the configuration snippet on GitHub.

Example 6.16. Using the mbox() driver

The following example reads the e-mails of the root user on the syslog-ng OSE host.

@include "scl.conf"
source root-mbox { mbox("/var/spool/mail/root"); };

6.7. Collecting messages from named pipes

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.

The pipe driver has a single required parameter, specifying the filename of the pipe to open. For the list of available optional parameters, see Section 6.7.1, pipe() source options.

Declaration: 

pipe(filename);
Note

As of syslog-ng Open Source Edition 3.0.2, pipes are created automatically. In earlier versions, you had to create the pipe using the mkfifo(1) command.

Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like /proc/kmsg.

Warning
  • It is not recommended to use pipe() on anything else than real pipes.

  • By default, syslog-ng OSE uses the flags(no-hostname) option for pipes, meaning that syslog-ng OSE assumes that the log messages received from the pipe do not contain the hostname field. If your messages do contain the hostname field, use flags(expect-hostname). For details, see Section flags().

Example 6.17. Using the pipe() driver
source s_pipe { pipe("/dev/pipe" pad-size(2048)); };

6.7.1. pipe() source options

The pipe driver has the following options:

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[6]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

follow-freq()

Type: number
Default: 1

Description: Indicates that the source should be checked periodically. 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 poll() on the file, but checks whether the file changed every time the follow-freq() interval (in seconds) has elapsed. Floating-point numbers (for example 1.5) can be used as well.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.18. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

log-prefix() (DEPRECATED)

Type: string
Default:  

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

multi-line-garbage()

Type: regular expression
Default: empty string

Description: Use the multi-line-garbage() option when processing multi-line messages that contain unneeded parts between the messages. Specify a string or regular expression that matches the beginning of the unneeded message parts. If the multi-line-garbage() option is set, syslog-ng OSE ignores the lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix(). See also the multi-line-prefix() option.

When receiving multi-line messages from a source when the multi-line-garbage() option is set, but no matching line is received between two lines that match multi-line-prefix(), syslog-ng OSE will continue to process the incoming lines as a single message until a line matching multi-line-garbage() is received.

To use the multi-line-garbage() option, set the multi-line-mode() option to prefix-garbage.

Warning

If the multi-line-garbage() option is set, syslog-ng OSE discards lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix().

multi-line-mode()

Type: indented|regexp
Default: empty string

Description: Use the multi-line-mode() option when processing multi-line messages. The syslog-ng OSE application provides the following methods to process multi-line messages: multi-line-mode(indented), and multi-line-mode(prefix-garbage).

  • The indented mode can process messages where each line that belongs to the previous line is indented by whitespace, and the message continues until the first non-indented line. For example, the Linux kernel (starting with version 3.5) uses this format for /dev/log, as well as several applications, like Apache Tomcat.

    Example 6.19. Processing indented multi-line messages
    source s_tomcat {
        file("/var/log/tomcat/xxx.log" multi-line-mode(indented));
    };
  • The prefix-garbage mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. For details on using multi-line-mode(prefix-garbage), see the multi-line-prefix() and multi-line-garbage() options.

  • The prefix-suffix mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression set in multi-line-suffix(), and treats the lines between multi-line-prefix() and multi-line-suffix() as a single message. Any other lines between the end of the message and the beginning of a new message (that is, a line that matches the multi-line-prefix() expression) are discarded. For details on using multi-line-mode(prefix-suffix), see the multi-line-prefix() and multi-line-suffix() options.

    The prefix-suffix mode is similar to the prefix-garbage mode, but it appends the garbage part to the message instead of discarding it.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

multi-line-prefix()

Type: regular expression starting with the ^ character
Default: empty string

Description: Use the multi-line-prefix() option to process multi-line messages, that is, log messages that contain newline characters (for example, Tomcat logs). Specify a string or regular expression that matches the beginning of the log messages (always start with the ^ character). Use as simple regular expressions as possible, because complex regular expressions can severely reduce the rate of processing multi-line messages. If the multi-line-prefix() option is set, syslog-ng OSE ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. See also the multi-line-garbage() option.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

Example 6.20. Processing Tomcat logs

The log messages of the Apache Tomcat server are a typical example for multi-line log messages. The messages start with the date and time of the query in the YYYY.MM.DD HH:MM:SS format, as you can see in the following example.

2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
SEVERE: Catalina.start:
LifecycleException:  service.getName(): "Catalina";  Protocol handler start failed: java.net.BindException: Address already in use<null>:8080
       at org.apache.catalina.connector.Connector.start(Connector.java:1138)
       at org.apache.catalina.core.StandardService.start(StandardService.java:531)
       at org.apache.catalina.core.StandardServer.start(StandardServer.java:710)
       at org.apache.catalina.startup.Catalina.start(Catalina.java:583)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:288)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:177)
2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
INFO: Server startup in 1206 ms
2010.06.09. 12:45:08 org.apache.coyote.http11.Http11Protocol pause
INFO: Pausing Coyote HTTP/1.1 on http-8080
2010.06.09. 12:45:09 org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina

To process these messages, specify a regular expression matching the timestamp of the messages in the multi-line-prefix() option. Such an expression is the following:

source s_file{file("/var/log/tomcat6/catalina.2010-06-09.log" follow-freq(0) multi-line-mode(regexp) multi-line-prefix("[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.") flags(no-parse));};
};

Note that the flags(no-parse) is needed to avoid syslog-ng OSE trying to interpret the date in the message.

multi-line-suffix()

Type: regular expression
Default: empty string

Description: Use the multi-line-suffix() option when processing multi-line messages. Specify a string or regular expression that matches the end of the multi-line message.

To use the multi-line-suffix() option, set the multi-line-mode() option to prefix-suffix. See also the multi-line-prefix() option.

optional()

Type: yes or no
Default:  

Description: 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 pipe(), unix-dgram, and unix-stream drivers.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

pipe()

Type: filename with path
Default:  

Description: The filename of the pipe to read messages from.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.



[6] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.8. Collecting process accounting logs on Linux

Starting with version 3.2, syslog-ng OSE can collect process accounting logs on Linux systems.Process accounting is the method of recording and summarizing commands executed on Linux, for example, the commands being run, the user who executed the command, CPU time used by the process, exit code, and so on. When process accounting (also called pacct) is enabled on a system, the kernel writes accounting records to the /var/log/account/pacct file (might vary between different Linux distributions).

To use the pacct() driver, the following conditions must be met:

  • The syslog-ng OSE application must be compiled with the --enable-pacct option. Execute the syslog-ng -V command to check if your binary supports process accounting.

  • The pacctformat plugin must be loaded. By default, syslog-ng OSE automatically loads the available modules.

  • The scl.conf file must be included in your syslog-ng configuration:

    @include "scl.conf"
  • Process accounting must be running on the host. You can enable it with the accton command.

The pacct() driver parses the fields of the accounting logs and transforms them into name-value pairs. The fields are defined in the manual page of the accounting log file (man acct), syslog-ng OSE prepends every field with the .pacct. prefix. For example, the ac_uid field that contains the id of the user who started the process will be available under the $.pacct.ac_uid name. These can be used as macros in templates, in filters to select specific messages, and so on.

To use the pacct() driver, use the following syntax.

@version: 3.9
@include "scl.conf"
source s_pacct { pacct(); };
...
log { source(s_pacct); destination(...); };

The pacct() driver is actually a reusable configuration snippet configured to handle Linux accounting logs. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the pacct configuration snippet on GitHub.

6.8.1. pacct() options

The pacct() driver has the following options:

file()

Type: filename with path
Default: /var/log/account/pacct

Description: The file where the process accounting logs are stored — syslog-ng OSE reads accounting messages from this file.

follow-freq()

Type: number
Default: 1

Description: Indicates that the source should be checked periodically. 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 poll() on the file, but checks whether the file changed every time the follow-freq() interval (in seconds) has elapsed. Floating-point numbers (for example 1.5) can be used as well.

6.9. Receiving messages from external applications

The program driver starts an external application and reads messages from the standard output (stdout) of the application. It is mainly useful to receive log messages from daemons that accept incoming messages and convert them to log messages.

The program driver has a single required parameter, specifying the name of the application to start.

Declaration: 

program(filename);
Example 6.21. Using the program() driver
source s_program { program("/etc/init.d/mydaemon"); };
Note

The program is restarted automatically if it exits.

6.9.1. program() source options

The program driver has the following options:

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[7]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

inherit-environment()

Type: yes|no
Default: yes

Description: By default, when program() starts an external application or script, it inherits the entire environment of the parent process (that is, syslog-ng OSE). Use inherit-environment(no) to prevent this.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.22. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

log-prefix() (DEPRECATED)

Type: string
Default:  

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

optional()

Type: yes or no
Default:  

Description: 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 pipe(), unix-dgram, and unix-stream drivers.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

program()

Type: filename with path
Default:  

Description: The name of the application to start and read messages from.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.



[7] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.10. Collecting messages on Sun Solaris

Solaris uses its STREAMS framework to send messages to the syslogd process. Solaris 2.5.1 and above uses an IPC called door in addition to STREAMS, to confirm the delivery of a message. The syslog-ng application supports the IPC mechanism via the door() option (see below).

Note

The sun-streams() driver must be enabled when the syslog-ng application is compiled (see ./configure --help).

The sun-streams() driver has a single required argument specifying the STREAMS device to open, and the door() option. For the list of available optional parameters, see Section 6.10.1, sun-streams() source options.

Note

Starting with version 3.7, the syslog-ng OSE system() driver automatically extracts the msgid from the message (if available), and stores it in the .solaris.msgid macro. To extract the msgid from the message without using the system()driver, use the extract-solaris-msgid() parser. You can find the exact source of this parser in the syslog-ng OSE GitHub repository.

Declaration: 

sun-streams(<name_of_the_streams_device> door(<filename_of_the_door>));
Example 6.23. Using the sun-streams() driver
source s_stream { sun-streams("/dev/log" door("/etc/.syslog_door")); };

6.10.1. sun-streams() source options

The sun-streams() driver has the following options.

door()

Type: string
Default: none

Description: Specifies the filename of a door to open, needed on Solaris above 2.5.1.

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[8]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

follow-freq()

Type: number
Default: 1

Description: Indicates that the source should be checked periodically. 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 poll() on the file, but checks whether the file changed every time the follow-freq() interval (in seconds) has elapsed. Floating-point numbers (for example 1.5) can be used as well.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.24. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

log-prefix() (DEPRECATED)

Type: string
Default:  

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

optional()

Type: yes or no
Default:  

Description: 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 pipe(), unix-dgram, and unix-stream drivers.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.



[8] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.11. Collecting messages using the IETF syslog protocol (syslog() driver)

The syslog() driver can receive messages from the network using the standard IETF-syslog protocol (as described in RFC5424-26). UDP, TCP, and TLS-encrypted TCP can all be used to transport the messages.

Note

The syslog() driver can also receive BSD-syslog-formatted messages (described in RFC 3164, see Section 2.8.1, BSD-syslog or legacy-syslog messages) if they are sent using the IETF-syslog protocol.

In syslog-ng OSE versions 3.1 and earlier, the syslog() driver could handle only messages in the IETF-syslog (RFC 5424-26) format.

For the list of available optional parameters, see Section 6.11.1, syslog() source options.

Declaration: 

syslog(ip() port() transport() options());
Example 6.25. Using the syslog() driver

TCP source listening on the localhost on port 1999.

source s_syslog { syslog(ip(127.0.0.1) port(1999) transport("tcp")); };

UDP source with defaults.

source s_udp { syslog( transport("udp")); };

Encrypted source where the client is also authenticated. For details on the encryption settings, see Section 10.4, TLS options.

source s_syslog_tls{ syslog(
    ip(10.100.20.40)
    transport("tls")
    tls(
    peer-verify(required-trusted)
    ca-dir('/opt/syslog-ng/etc/syslog-ng/keys/ca.d/')
    key-file('/opt/syslog-ng/etc/syslog-ng/keys/server_privatekey.pem')
    cert-file('/opt/syslog-ng/etc/syslog-ng/keys/server_certificate.pem')
    )
    );};
Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

6.11.1. syslog() source options

The syslog() driver has the following options.

encoding()

Type: string
Default:  

Description: Specifies the characterset (encoding, for example UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command. For details on how encoding affects the size of the message, see Section Message size and encoding.

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[9]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

host-override()

Type: string
Default:  

Description: Replaces the ${HOST} part of the message with the parameter string.

ip() or localip()

Type: string
Default: 0.0.0.0

Description: The IP address to bind to. By default, syslog-ng OSE listens on every available interface. Note that this is not the address where messages are accepted from.

If you specify a multicast bind address and use the udp transport, syslog-ng OSE automatically joins the necessary multicast group. TCP does not support multicasting.

ip-protocol()

Type: number
Default: 4

Description: Determines the internet protocol version of the given driver (network() or syslog()). The possible values are 4 and 6, corresponding to IPv4 and IPv6. The default value is ip-protocol(4).

Note that listening on a port using IPv6 automatically means that you are also listening on that port using IPv4. That is, if you want to have receive messages on an IP-address/port pair using both IPv4 and IPv6, create a source that uses the ip-protocol(6). You cannot have two sources with the same IP-address/port pair, but with different ip-protocol() settings (it causes an Address already in use error).

For example, the following source receives messages on TCP, using the network() driver, on every available interface of the host on both IPv4 and IPv6.

source s_network_tcp { network( transport("tcp") ip("::") ip-protocol(6) port(601) ); };

ip-tos()

Type: number
Default: 0

Description: Specifies the Type-of-Service value of outgoing packets.

ip-ttl()

Type: number
Default: 0

Description: Specifies the Time-To-Live value of outgoing packets.

keep-alive()

Type: yes or no
Default: yes

Description: Specifies whether connections to sources should be closed when syslog-ng is forced to reload its configuration (upon the receipt of a SIGHUP signal). Note that this applies to the server (source) side of the syslog-ng connections, client-side (destination) connections are always reopened after receiving a HUP signal unless the keep-alive option is enabled for the destination.

keep-hostname()

Type: yes or no
Default: no

Description: Enable or disable hostname rewriting.

  • If enabled (keep-hostname(yes)), syslog-ng OSE assumes that the incoming log message was sent by the host specified in the HOST field of the message.

  • If disabled (keep-hostname(no)), syslog-ng OSE rewrites the HOST field of the message, either to the IP address (if the use-dns() parameter is set to no), or to the hostname (if the use-dns() parameter is set to yes and the IP address can be resolved to a hostname) of the host sending the message to syslog-ng OSE. For details on using name resolution in syslog-ng OSE, see Section 19.3, Using name resolution in syslog-ng.

Note

If the log message does not contain a hostname in its HOST field, syslog-ng OSE automatically adds a hostname to the message.

  • For messages received from the network, this hostname is the address of the host that sent the message (this means the address of the last hop if the message was transferred via a relay).

  • For messages received from the local host, syslog-ng OSE adds the name of the host.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

When relaying messages, enable this option on the syslog-ng OSE server and also on every relay, otherwise syslog-ng OSE will treat incoming messages as if they were sent by the last relay.

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

listen-backlog()

Type: integer
Default: 256

Description: Available only for stream based transports (unix-stream, tcp, tls). In TCP, connections are treated incomplete until the three-way handshake is completed between the server and the client. Incomplete connection requests wait on the TCP port for the listener to accept the request. The listen-backlog() option sets the maximum number of incomplete connection requests. For example:

source s_network {
    network(
        ip("192.168.1.1")
        transport("tcp")
        listen-backlog(2048)
        );
};

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.26. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

max-connections()

Type: number
Default: 10

Description: Specifies the maximum number of simultaneous connections.

multi-line-garbage()

Type: regular expression
Default: empty string

Description: Use the multi-line-garbage() option when processing multi-line messages that contain unneeded parts between the messages. Specify a string or regular expression that matches the beginning of the unneeded message parts. If the multi-line-garbage() option is set, syslog-ng OSE ignores the lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix(). See also the multi-line-prefix() option.

When receiving multi-line messages from a source when the multi-line-garbage() option is set, but no matching line is received between two lines that match multi-line-prefix(), syslog-ng OSE will continue to process the incoming lines as a single message until a line matching multi-line-garbage() is received.

To use the multi-line-garbage() option, set the multi-line-mode() option to prefix-garbage.

Warning

If the multi-line-garbage() option is set, syslog-ng OSE discards lines between the line matching the multi-line-garbage() and the next line matching multi-line-prefix().

multi-line-mode()

Type: indented|regexp
Default: empty string

Description: Use the multi-line-mode() option when processing multi-line messages. The syslog-ng OSE application provides the following methods to process multi-line messages: multi-line-mode(indented), and multi-line-mode(prefix-garbage).

  • The indented mode can process messages where each line that belongs to the previous line is indented by whitespace, and the message continues until the first non-indented line. For example, the Linux kernel (starting with version 3.5) uses this format for /dev/log, as well as several applications, like Apache Tomcat.

    Example 6.27. Processing indented multi-line messages
    source s_tomcat {
        file("/var/log/tomcat/xxx.log" multi-line-mode(indented));
    };
  • The prefix-garbage mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. For details on using multi-line-mode(prefix-garbage), see the multi-line-prefix() and multi-line-garbage() options.

  • The prefix-suffix mode uses a string or regular expression (set in multi-line-prefix()) that matches the beginning of the log messages, ignores newline characters from the source until a line matches the regular expression set in multi-line-suffix(), and treats the lines between multi-line-prefix() and multi-line-suffix() as a single message. Any other lines between the end of the message and the beginning of a new message (that is, a line that matches the multi-line-prefix() expression) are discarded. For details on using multi-line-mode(prefix-suffix), see the multi-line-prefix() and multi-line-suffix() options.

    The prefix-suffix mode is similar to the prefix-garbage mode, but it appends the garbage part to the message instead of discarding it.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

multi-line-prefix()

Type: regular expression starting with the ^ character
Default: empty string

Description: Use the multi-line-prefix() option to process multi-line messages, that is, log messages that contain newline characters (for example, Tomcat logs). Specify a string or regular expression that matches the beginning of the log messages (always start with the ^ character). Use as simple regular expressions as possible, because complex regular expressions can severely reduce the rate of processing multi-line messages. If the multi-line-prefix() option is set, syslog-ng OSE ignores newline characters from the source until a line matches the regular expression again, and treats the lines between the matching lines as a single message. See also the multi-line-garbage() option.

Tip
  • To make multi-line messages more readable when written to a file, use a template in the destination and instead of the ${MESSAGE} macro, use the following: $(indent-multi-line ${MESSAGE}). This expression inserts a tab after every newline character (except when a tab is already present), indenting every line of the message after the first. For example:

    destination d_file {
        file ("/var/log/messages"
            template("${ISODATE} ${HOST} $(indent-multi-line ${MESSAGE})\n") );
    };

    For details on using templates, see Section 11.1.2, Templates and macros.

  • To actually convert the lines of multi-line messages to single line (by replacing the newline characters with whitespaces), use the flags(no-multi-line) option in the source.

Example 6.28. Processing Tomcat logs

The log messages of the Apache Tomcat server are a typical example for multi-line log messages. The messages start with the date and time of the query in the YYYY.MM.DD HH:MM:SS format, as you can see in the following example.

2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
SEVERE: Catalina.start:
LifecycleException:  service.getName(): "Catalina";  Protocol handler start failed: java.net.BindException: Address already in use<null>:8080
       at org.apache.catalina.connector.Connector.start(Connector.java:1138)
       at org.apache.catalina.core.StandardService.start(StandardService.java:531)
       at org.apache.catalina.core.StandardServer.start(StandardServer.java:710)
       at org.apache.catalina.startup.Catalina.start(Catalina.java:583)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:288)
       at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
       at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
       at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
       at java.lang.reflect.Method.invoke(Method.java:597)
       at org.apache.commons.daemon.support.DaemonLoader.start(DaemonLoader.java:177)
2010.06.09. 12:07:39 org.apache.catalina.startup.Catalina start
INFO: Server startup in 1206 ms
2010.06.09. 12:45:08 org.apache.coyote.http11.Http11Protocol pause
INFO: Pausing Coyote HTTP/1.1 on http-8080
2010.06.09. 12:45:09 org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina

To process these messages, specify a regular expression matching the timestamp of the messages in the multi-line-prefix() option. Such an expression is the following:

source s_file{file("/var/log/tomcat6/catalina.2010-06-09.log" follow-freq(0) multi-line-mode(regexp) multi-line-prefix("[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.") flags(no-parse));};
};

Note that the flags(no-parse) is needed to avoid syslog-ng OSE trying to interpret the date in the message.

Warning

If you receive messages using the UDP protocol, do not use multi-line processing. If every line of a multi-line message is received in the same UDP packet, everything is fine, but if a multi-line message is fragmented into multiple UDP packets, the order they are received (thus the way how they are processed) cannot be guaranteed, and causes problems.

multi-line-suffix()

Type: regular expression
Default: empty string

Description: Use the multi-line-suffix() option when processing multi-line messages. Specify a string or regular expression that matches the end of the multi-line message.

To use the multi-line-suffix() option, set the multi-line-mode() option to prefix-suffix. See also the multi-line-prefix() option.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

port() or localport()

Type: number
Default:

In case of TCP transport: 601

In case of UDP transport: 514

Description: The port number to bind to.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

so-broadcast()

Type: yes or no
Default: no

Description: This option controls the SO_BROADCAST socket option required to make syslog-ng send messages to a broadcast address. For details, see the socket(7) manual page.

so-keepalive()

Type: yes or no
Default: no

Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.

so-rcvbuf()

Type: number
Default: 0

Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.

Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

so-sndbuf()

Type: number
Default: 0

Description: Specifies the size of the socket send buffer in bytes. For details, see the socket(7) manual page.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

transport()

Type: udp, tcp, or tls
Default: tcp

Description: Specifies the protocol used to receive messages from the source.

Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

tls()

Type: tls options
Default: n/a

Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see Section 10.4, TLS options.

use-dns()

Type: yes, no, persist_only
Default: yes

Description: Enable or disable DNS usage. The persist_only option attempts to resolve hostnames locally from file (for example from /etc/hosts). The syslog-ng OSE application 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. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

use-fqdn()

Type: yes or no
Default: no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.



[9] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

6.12. Collecting the system-specific log messages of a platform

Starting with version 3.2, syslog-ng OSE can automatically collect the system-specific log messages of the host on a number of platforms using the system() driver. If the system() driver is included in the syslog-ng OSE configuration file, syslog-ng OSE automatically adds the following sources to the syslog-ng OSE configuration.

Note

syslog-ng OSE versions 3.2-3.3 used an external script to generate the system() source, but this was problematic in certain situations, for example, when the host used a strict AppArmor profile. Therefore, the system() source is now generated internally in syslog-ng OSE.

The system() driver is also used in the default configuration file of syslog-ng OSE. For details on the default configuration file, see Example 4.1, The default configuration file of syslog-ng OSE. Starting with syslog-ng OSE version 3.6, you can use the system-expand command-line utility (which is a shell script, located in the modules/system-source/ directory) to display the configuration that the system() source will use.

Warning

If syslog-ng OSE does not recognize the platform it is installed on, it does not add any sources.

Starting with version 3.6, syslog-ng OSE parses messages complying with the Splunk Common Information Model (CIM) and marked with @cim as JSON messages (for example, the ulogd from the netfilter project can emit such messages). That way, you can forward such messages without losing any information to CIM-aware applications (for example, Splunk).

Platform Message source
AIX and Tru64
unix-dgram("/dev/log");
FreeBSD
unix-dgram("/var/run/log");
unix-dgram("/var/run/logpriv" perm(0600));
file("/dev/klog" follow-freq(0) program-override("kernel") flags(no-parse));

For FreeBSD versions earlier than 9.1, follow-freq(1) is used.

GNU/kFreeBSD
unix-dgram("/var/run/log");
file("/dev/klog" follow-freq(0) program-override("kernel"));
HP-UX
pipe("/dev/log" pad-size(2048));
Linux
unix-dgram("/dev/log");
file("/proc/kmsg" program-override("kernel") flags(kernel));

Note that on Linux, the so-rcvbuf() option of the system() source is automatically set to 8192.

If the host is running under systemd, syslog-ng OSE reads directly from the systemd journal file using the systemd-journal() source.

If the kernel of the host is version 3.5 or newer, and /dev/kmsg is seekable, syslog-ng OSE will use that instead of /proc/kmsg, using the multi-line-mode(indented), keep-timestamp(no), and the format(linux-kmsg) options.

If syslog-ng OSE is running in a jail or a Linux Container (LXC), it will not read from the /dev/kmsg or /proc/kmsg files.

Solaris 8
sun-streams("/dev/log");
Note

Starting with version 3.7, the syslog-ng OSE system() driver automatically extracts the msgid from the message (if available), and stores it in the .solaris.msgid macro. To extract the msgid from the message without using the system()driver, use the extract-solaris-msgid() parser. You can find the exact source of this parser in the syslog-ng OSE GitHub repository.

Solaris 9
sun-streams("/dev/log" door("/etc/.syslog_door"));
Note

Starting with version 3.7, the syslog-ng OSE system() driver automatically extracts the msgid from the message (if available), and stores it in the .solaris.msgid macro. To extract the msgid from the message without using the system()driver, use the extract-solaris-msgid() parser. You can find the exact source of this parser in the syslog-ng OSE GitHub repository.

Solaris 10
sun-streams("/dev/log" door("/var/run/syslog_door"));
Note

Starting with version 3.7, the syslog-ng OSE system() driver automatically extracts the msgid from the message (if available), and stores it in the .solaris.msgid macro. To extract the msgid from the message without using the system()driver, use the extract-solaris-msgid() parser. You can find the exact source of this parser in the syslog-ng OSE GitHub repository.

Table 6.3. Sources automatically added by syslog-ng Open Source Edition


6.13. Collecting messages from the systemd-journal system log storage

The systemd-journal() source is used on various Linux distributions, such as RHEL (from RHEL7) and CentOS. The systemd-journal() source driver can read the structured name-value format of the journald system service, making it easier to reach the custom fields in the message. By default, syslog-ng OSE adds the .journald. prefix to the name of every parsed value.

The systemd-journal() source driver is designed to read only local messages through the systemd-journal API. It is not possible to set the location of the journal files, or the directories.

Note

The log-msg-size() option is not applicable for this source. Use the max-field-size() option instead.

Note

This source will not handle the following cases:

  • corrupted journal file

  • incorrect journal configuration

  • any other journald-related bugs

Note

If you are using RHEL-7, the default source in the configuration is systemd-journal() instead of unix-dgram("/dev/log") and file("/proc/kmsg"). If you are using unix-dgram("/dev/log") or unix-stream("/dev/log") in your configuration as a source, syslog-ng OSE will revert to using systemd-journal() instead.

Warning

Only one systemd-journal() source can be configured in the configuration file. If there are more than one systemd-journal() sources configured, syslog-ng OSE will not start.

Declaration: 

systemd-journal(options);
Example 6.29. Sending all fields through syslog protocol using the systemd-journal() driver

To send all fields through the syslog protocol, enter the prefix in the following format: ".SDATA.<name>".

@version: 3.9

source s_journald {
	systemd-journal(prefix(".SDATA.journald."));
};

destination d_network {
	syslog("server.host");
};

log {
	source(s_journald);
	destination(d_network);
};
Example 6.30. Filtering for a specific field using the systemd-journal() driver
@version: 3.9

source s_journald {
	systemd-journal(prefix(".SDATA.journald."));
};

filter f_uid {"${.SDATA.journald._UID}" eq "1000"};

destination d_network {
	syslog("server.host");
};

log {
	source(s_journald);
	filter(f_uid);
	destination(d_network);
};
Example 6.31. Sending all fields in value-pairs using the systemd-journal() driver
@version: 3.9

source s_local {
	systemd-journal(prefix("journald."));
};

destination d_network {
	network("server.host" template("$(format_json --scope rfc5424 --key journald.*)\n"));
};

log {
	source(s_local);
	destination(d_network);
};

The journal contains credential information about the process that sent the log message. The syslog-ng OSE application makes this information available in the following macros:

Journald field syslog-ng predefined macro
MESSAGE $MESSAGE
_HOSTNAME $HOST
_PID $PID
_COMM or SYSLOG_IDENTIFIER $PROGRAM If both _COMM and SYSLOG_IDENTIFIER exists, syslog-ng OSE uses SYSLOG_IDENTIFIER
SYSLOG_FACILITY $FACILITY_NUM
PRIORITY $LEVEL_NUM

6.13.1. systemd-journal() source options

The systemd-journal() driver has the following options:

default-facility()

Type: facility string
Default: local0

Description: The default facility value if the SYSLOG_FACILITY entry does not exist.

default-level()

Type: string
Default: notice

Description: The default level value if the PRIORITY entry does not exist.

host-override()

Type: string
Default:  

Description: Replaces the ${HOST} part of the message with the parameter string.

keep-hostname()

Type: yes or no
Default: no

Description: Enable or disable hostname rewriting.

  • If enabled (keep-hostname(yes)), syslog-ng OSE will retain the hostname information read from the systemd journal messages.

  • If disabled (keep-hostname(no)), syslog-ng OSE will use the hostname that has been set up for the operating system instance that syslog-ng is running on. To query or set this value, use the hostnamectl command.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

max-field-size()

Type: number (characters)
Default: 65536

Description: The maximum length of a field's value.

prefix()

Type: string
Default: .journald.

Description: If this option is set, every non-built-in mapped names get a prefix (for example: ".SDATA.journald."). By default, syslog-ng OSE adds the .journald. prefix to every value.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

use-fqdn()

Type: yes or no
Default: no

Description: Add Fully Qualified Domain Name instead of short hostname. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Note

This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

6.14. Collecting systemd messages using a socket

On platforms running systemd, the systemd-syslog() driver reads the log messages of systemd using the /run/systemd/journal/syslog socket. Note the following points about this driver:

  • If possible, use the more reliable systemd-journal() driver instead.

  • The socket activation of systemd is buggy, causing some log messages to get lost during system startup.

  • If syslog-ng OSE is running in a jail or a Linux Container (LXC), it will not read from the /dev/kmsg or /proc/kmsg files.

Declaration: 

systemd-syslog();
Example 6.32. Using the systemd-syslog() driver
@version: 3.9

source s_systemdd {
	systemd-syslog();
};

destination d_network {
	syslog("server.host");
};

log {
	source(s_systemdd);
	destination(d_network);
};

6.15. Collecting messages from remote hosts using the BSD syslog protocol

Note

The tcp(), tcp6(), udp(), and udp6() drivers are obsolete. Use the network() source and the network() destination instead. For details, see Section 6.4, Collecting messages using the RFC3164 protocol (network() driver) and Section 7.13, Sending messages to a remote log server using the RFC3164 protocol (network() driver), respectively.

The tcp(), tcp6(), udp(), udp6() drivers can receive syslog messages conforming to RFC3164 from the network using the TCP and UDP networking protocols. The tcp6() and udp6() drivers use the IPv6 network protocol, while tcp() and udp() use IPv4.

To convert your existing tcp(), tcp6(), udp(), udp6() source drivers to use the network() driver, see Procedure 6.15.1.1, Change an old source driver to the network() driver.

6.15.1. tcp(), tcp6(), udp() and udp6() source options — OBSOLETE

Note

The tcp(), tcp6(), udp(), and udp6() drivers are obsolete. Use the network() source and the network() destination instead. For details, see Section 6.4, Collecting messages using the RFC3164 protocol (network() driver) and Section 7.13, Sending messages to a remote log server using the RFC3164 protocol (network() driver), respectively.

To convert your existing tcp(), tcp6(), udp(), udp6() source drivers to use the network() driver, see Procedure 6.15.1.1, Change an old source driver to the network() driver.

6.15.1.1. Procedure – Change an old source driver to the network() driver

To replace your existing tcp(), tcp6(), udp(), udp6() sources with a network() source, complete the following steps.

  1. Replace the driver with network. For example, replace udp( with network(

  2. Set the transport protocol.

    • If you used TLS-encryption, add the transport("tls") option, then continue with the next step.

    • If you used the tcp or tcp6 driver, add the transport("tcp") option.

    • If you used the udp or udp driver, add the transport("udp") option.

  3. If you use IPv6 (that is, the udp6 or tcp6 driver), add the ip-protocol(6) option.

  4. If you did not specify the port used in the old driver, check Section 6.4.1, network() source options and verify that your clients send the messages to the default port of the transport protocol you use. Otherwise, set the appropriate port number in your source using the port() option.

  5. All other options are identical. Test your configuration with the syslog-ng --syntax-only command.

    The following configuration shows a simple tcp source.

    source s_old_tcp {
        tcp(
            ip(127.0.0.1) port(1999)
            tls(
                peer-verify("required-trusted")
                key-file("/opt/syslog-ng/etc/syslog-ng/syslog-ng.key")
                cert-file('/opt/syslog-ng/etc/syslog-ng/syslog-ng.crt')
            )
        );
    };

    When replaced with the network() driver, it looks like this.

    source s_new_network_tcp {
        network(
            transport("tls")
            ip(127.0.0.1) port(1999)
            tls(
                peer-verify("required-trusted")
                key-file("/opt/syslog-ng/etc/syslog-ng/syslog-ng.key")
                cert-file('/opt/syslog-ng/etc/syslog-ng/syslog-ng.crt')
            )
        );
    };

6.16. Collecting messages from UNIX domain sockets

The unix-stream() and unix-dgram() drivers open an AF_UNIX socket and start listening on it for messages. The unix-stream() driver is primarily used on Linux and uses SOCK_STREAM semantics (connection oriented, no messages are lost), while unix-dgram() is used on BSDs and uses SOCK_DGRAM semantics: this may result in lost local messages if the system is overloaded.

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 max-connections() parameter. The default value of this parameter is quite strict, you might have to increase it on a busy system.

Both unix-stream and unix-dgram have a single required argument that specifies the filename of the socket to create. For the list of available optional parameters, see Section 6.16.2, unix-stream() and unix-dgram() source options

Declaration: 

unix-stream(filename [options]);
unix-dgram(filename [options]);
Note

syslogd on Linux originally used SOCK_STREAM sockets, but some distributions switched to SOCK_DGRAM around 1999 to fix a possible DoS problem. On Linux you can choose to use whichever driver you like as syslog clients automatically detect the socket type being used.

Example 6.33. Using the unix-stream() and unix-dgram() drivers
source s_stream { unix-stream("/dev/log" max-connections(10)); };
source s_dgram { unix-dgram("/var/run/log"); };

6.16.1. UNIX credentials and other metadata

Starting with syslog-ng OSE 3.6, the unix-stream() and unix-dgram() sources automatically extract the available UNIX credentials and other metainformation from the received log messages. The syslog-ng OSE application can extract the following information on Linux and FreeBSD platforms (examples show the value of the macro for the su - myuser command). Similar information is available for the systemd-journal source.

Macro Description
${.unix.cmdline} The name (without the path) and command-line options of the executable belonging to the PID that sent the message. For example, su - myuser
${.unix.exe} The path of the executable belonging to the PID that sent the message. For example, /usr/bin/su
${.unix.gid} The group ID (GID) corresponding to the UID of the application that sent the log message. Note that this is the ID number of the group, not its human-readable name. For example, 0
${.unix.pid}

The process ID (PID) of the application that sent the log message. For example, 774.

Note that on every UNIX platforms, if the system() source uses sockets, it will overwrite the PID macro with the value of ${.unix.pid}, if it is available.

${.unix.uid} The user ID (UID) of the application that sent the log message. Note that this is the ID number of the user, not its human-readable name. For example, 0

Table 6.4. UNIX credentials available via UNIX domain sockets


6.16.2. unix-stream() and unix-dgram() source options

These two drivers behave similarly: they open an AF_UNIX socket and start listening on it for messages. The following options can be specified for these drivers:

create-dirs()

Type: yes or no
Default: no

Description: Enable creating non-existing directories when creating the socket files.

encoding()

Type: string
Default:  

Description: Specifies the characterset (encoding, for example UTF-8) of messages using the legacy BSD-syslog protocol. To list the available character sets on a host, execute the iconv -l command. For details on how encoding affects the size of the message, see Section Message size and encoding.

flags()

Type: assume-utf8, empty-lines, expect-hostname, kernel, no-hostname, no-multi-line, no-parse, sanitize-utf8, store-legacy-msghdr, syslog-protocol, validate-utf8
Default: empty set

Description: Specifies the log parsing options of the source.

  • assume-utf8: The assume-utf8 flag assumes that the incoming messages are UTF-8 encoded, but does not verify the encoding. If you explicitly want to validate the UTF-8 encoding of the incoming message, use the validate-utf8 flag.

  • empty-lines: Use the empty-lines flag to keep the empty lines of the messages. By default, syslog-ng OSE removes empty lines automatically.

  • expect-hostname: If the expect-hostname flag is enabled, syslog-ng OSE will assume that the log message contains a hostname and parse the message accordingly. This is the default behavior for TCP sources. Note that pipe sources use the no-hostname flag by default.

  • kernel: The kernel flag makes the source default to the LOG_KERN | LOG_NOTICE priority if not specified otherwise.

  • no-hostname: Enable the no-hostname flag if the log message does not include the hostname of the sender host. That way syslog-ng OSE assumes that the first part of the message header is ${PROGRAM} instead of ${HOST}. For example:

    source s_dell { network(port(2000) flags(no-hostname)); };
  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line. Note that this happens only if the underlying transport method actually supports multi-line messages. Currently the , syslog(), network(), unix-dgram() drivers support multi-line messages.

  • no-parse: By default, syslog-ng OSE parses incoming messages as syslog messages. The no-parse flag completely disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application will generate a new syslog header (timestamp, host, and so on) automatically and put the entire incoming message into the MSG part of the syslog message. This flag is useful for parsing messages not complying to the syslog format.

    If you are using the flags(no-parse) option, then syslog message parsing is completely disabled, and the entire incoming message is treated as the ${MESSAGE} part of a syslog message. In this case, syslog-ng OSE generates a new syslog header (timestamp, host, and so on) automatically.

  • dont-store-legacy-msghdr: By default, syslog-ng stores the original incoming header of the log message. This is useful of the original format of a non-syslog-compliant message must be retained (syslog-ng automatically corrects minor header errors, for example, adds a whitespace before msg in the following message: Jan 22 10:06:11 host program:msg). If you do not want to store the original header of the message, enable the dont-store-legacy-msghdr flag.

  • sanitize-utf8: When using the sanitize-utf8 flag, syslog-ng OSE converts non-UTF-8 input to an escaped form, which is valid UTF-8.

  • syslog-protocol: The syslog-protocol flag specifies that incoming messages are expected to be formatted according to the new IETF syslog protocol standard (RFC5424), but without the frame header. Note that this flag is not needed for the syslog driver, which handles only messages that have a frame header.

  • validate-utf8: The validate-utf8 flag enables encoding-verification for messages formatted according to the new IETF syslog standard (for details, see Section 2.8.2, IETF-syslog messages). If theBOM[10]character is missing, but the message is otherwise UTF-8 compliant, syslog-ng automatically adds the BOM character to the message.

group()

Type: string
Default: root

Description: Set the gid of the socket.

host-override()

Type: string
Default:  

Description: Replaces the ${HOST} part of the message with the parameter string.

keep-alive()

Type: yes or no
Default: yes

Description: Selects whether to keep connections open when syslog-ng is restarted, cannot be used with unix-dgram().

keep-timestamp()

Type: yes or no
Default: yes

Description: Specifies whether syslog-ng should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

Warning

To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

listen-backlog()

Type: integer
Default: 256

Description: Available only for stream based transports (unix-stream, tcp, tls). In TCP, connections are treated incomplete until the three-way handshake is completed between the server and the client. Incomplete connection requests wait on the TCP port for the listener to accept the request. The listen-backlog() option sets the maximum number of incomplete connection requests. For example:

source s_network {
    network(
        ip("192.168.1.1")
        transport("tcp")
        listen-backlog(2048)
        );
};

log-fetch-limit()

Type: number
Default: 10

Description: 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 log-fetch-limit() is too high.

log-iw-size()

Type: number
Default: 100

Description: The size of the initial window, this value is used during flow control. If the max-connections() option is set, the log-iw-size() will be divided by the number of connections, otherwise log-iw-size() is divided by 10 (the default value of the max-connections() option). The resulting number is the initial window size of each connection. For optimal performance when receiving messages from syslog-ng OSE clients, make sure that the window size is larger than the flush-lines() option set in the destination of your clients.

Example 6.34. Initial window size of a connection

If log-iw-size(1000) and max-connections(10), then each connection will have an initial window size of 100.

log-msg-size()

Type: number
Default: Use the global log-msg-size() option, which defaults to 8192.

Description: Specifies the maximum length of incoming log messages. Uses the value of the global option if not specified. For details on how encoding affects the size of the message, see Section Message size and encoding.

log-prefix() (DEPRECATED)

Type: string
Default:  

Description: A string added to the beginning of every log message. It can be used to add an arbitrary string to any log source, though it is most commonly used for adding kernel: to the kernel messages on Linux. NOTE: This option is deprecated. Use program-override() instead.

max-connections()

Type: number (simultaneous connections)
Default: 256

Description: Limits the number of simultaneously open connections. Cannot be used with unix-dgram().

optional()

Type: yes or no
Default:  

Description: 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 pipe(), unix-dgram, and unix-stream drivers.

owner()

Type: string
Default: root

Description: Set the uid of the socket.

pad-size()

Type: number
Default: 0

Description: Specifies input padding. Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes). The syslog-ng OSE application will pad reads from the associated device to the number of bytes set in pad-size(). Mostly used on HP-UX where /dev/log is a named pipe and every write is padded to 2048 bytes. If pad-size() was given and the incoming message does not fit into pad-size(), syslog-ng will not read anymore from this pipe and displays the following error message:

Padding was set, and couldn't read enough bytes

perm()

Type: number (octal notation)
Default: 0666

Description: Set the permission mask. For octal numbers prefix the number with '0', for example: use 0755 for rwxr-xr-x.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

so-keepalive()

Type: yes or no
Default: no

Description: Enables keep-alive messages, keeping the socket open. This only effects TCP and UNIX-stream sockets. For details, see the socket(7) manual page.

so-rcvbuf()

Type: number
Default: 0

Description: Specifies the size of the socket receive buffer in bytes. For details, see the socket(7) manual page.

Warning

When receiving messages using the UDP protocol, increase the size of the UDP receive buffer on the receiver host (that is, the syslog-ng OSE server or relay receiving the messages). Note that on certain platforms, for example, on Red Hat Enterprise Linux 5, even low message load (~200 messages per second) can result in message loss, unless the so-rcvbuf() option of the source is increased. In such cases, you will need to increase the net.core.rmem_max parameter of the host (for example, to 1024000), but do not modify net.core.rmem_default parameter.

As a general rule, increase the so-rcvbuf() so that the buffer size in kilobytes is higher than the rate of incoming messages per second. For example, to receive 2000 messages per second, set the so-rcvbuf() at least to 2 097 152 bytes.

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example tags("dmz", "router"). This option is available only in syslog-ng 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.



[10] The byte order mark (BOM) is a Unicode character used to signal the byte-order of the message text.

Chapter 7. Sending and storing log messages — destinations and destination drivers

A destination is where a log message is sent if the filtering rules match. Similarly to sources, destinations consist of one or more drivers, each defining where and how messages are sent.

Tip

If no drivers are defined for a destination, all messages sent to the destination are discarded. This is equivalent to omitting the destination from the log statement.

To define a destination, add a destination statement to the syslog-ng configuration file using the following syntax:

destination <identifier> {
            destination-driver(params); destination-driver(params); ... };
Example 7.1. A simple destination statement

The following destination statement sends messages to the TCP port 1999 of the 10.1.2.3 host.

destination d_demo_tcp { network("10.1.2.3" port(1999)); };

If name resolution is configured, you can use the hostname of the target server as well.

destination d_tcp { network("target_host" port(1999)); };
Warning
  • Do not define the same drivers with the same parameters more than once, because it will cause problems. For example, do not open the same file in multiple destinations.

  • Do not use the same destination in different log paths, because it can cause problems with most destination types. Instead, use filters and log paths to avoid such situations.

  • Sources and destinations are initialized only when they are used in a log statement. For example, syslog-ng OSE starts listening on a port or starts polling a file only if the source is used in a log statement. For details on creating log statements, see Chapter 8, Routing messages: log paths and filters.

The following table lists the destination drivers available in syslog-ng OSE. If these destinations do not satisfy your needs, you can extend syslog-ng OSE and write your own destination, for example, in C, Java, or Python. For details, see Section 7.26, Write your own custom destination in Java or Python.

Name Description
amqp() Publishes messages using the AMQP (Advanced Message Queuing Protocol).
elasticsearch and elasticsearch2 Sends messages to an Elasticsearch server. The elasticsearch2 driver supports Elasticsearch version 2 and newer.
file() Writes messages to the specified file.
graphite() Sends metrics to a Graphite server to store numeric time-series data.
hdfs() Sends messages into a file on a Hadoop Distributed File System (HDFS) node.
http() Sends messages over the HTTP protocol. There are two different implementations of this driver: a Java-based http driver, and an http driver without Java.
kafka() Publishes log messages to the Apache Kafka message bus, where subscribers can access them.
loggly() Sends log messages to the Loggly Logging-as-a-Service provider.
logmatic() Sends log messages to the Logmatic.io Logging-as-a-Service provider.
mongodb() Sends messages to a MongoDB database.
network() Sends messages to a remote host using the BSD-syslog protocol over IPv4 and IPv6. Supports the TCP, UDP, and TLS network protocols.
pipe() Writes messages to the specified named pipe.
program() Forks and launches the specified program, and sends messages to its standard input.
redis() Sends messages as name-value pairs to a Redis key-value store.
riemann() Sends metrics or events to a Riemann monitoring system.
smtp() Sends e-mail messages to the specified recipients.
sql() Sends messages into an SQL database. In addition to the standard syslog-ng packages, the sql() destination requires database-specific packages to be installed. Refer to the section appropriate for your platform in Chapter 3, Installing syslog-ng.
stomp() Sends messages to a STOMP server.
syslog() Sends messages to the specified remote host using the IETF-syslog protocol. The IETF standard supports message transport using the UDP, TCP, and TLS networking protocols.
unix-dgram() Sends messages to the specified unix socket in SOCK_DGRAM style (BSD).
unix-stream() Sends messages to the specified unix socket in SOCK_STREAM style (Linux).
usertty() Sends messages to the terminal of the specified user, if the user is logged in.

Table 7.1. Destination drivers available in syslog-ng


7.1. Publishing messages using AMQP

The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol). syslog-ng OSE supports AMQP versions 0.9.1 and 1.0. The syslog-ng OSE amqp() driver supports persistence, and every available exchange types.

The name-value pairs selected with the value-pairs() option will be sent as AMQP headers, while the body of the AMQP message is empty by default (but you can add custom content using the body() option). Publishing the name-value pairs as headers makes it possible to use the Headers exchange-type and subscribe only to interesting log streams. This solution is more flexible than using the routing-key() option.

For the list of available parameters, see Section 7.1.1, amqp() destination options.

Declaration: 

amqp( host("<amqp-server-address>") );
Example 7.2. Using the amqp() driver

The following example shows the default values of the available options.

destination d_amqp {
    amqp(
        vhost("/")
        host("127.0.0.1")
        port(5672)
        exchange("syslog")
        exchange-type("fanout")
        routing-key("")
        body("")
        persistent(yes)
        value-pairs(
            scope("selected-macros" "nv-pairs" "sdata")
        )
    );
};

7.1.1. amqp() destination options

The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol).

The amqp() destination has the following options:

body()

Type: string
Default: empty string

Description: The body of the AMQP message. You can also use macros and templates.

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.3. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

exchange()

Type: string
Default: syslog

Description: The name of the AMQP exchange where syslog-ng OSE sends the message. Exchanges take a message and route it into zero or more queues.

exchange-declare()

Type: yes|no
Default: no

Description: By default, syslog-ng OSE does not create non-existing exchanges. Use the exchange-declare(yes) option to automatically create exchanges.

exchange-type()

Type: direct|fanout|topic|headers
Default: fanout

Description: The type of the AMQP exchange.

host()

Type: hostname or IP address
Default: 127.0.0.1

Description: The hostname or IP address of the AMQP server.

password()

Type: string
Default: n/a

Description: The password used to authenticate on the AMQP server.

persistent()

Type: yes|no
Default: yes

Description: If this option is enabled, the AMQP server or broker will store the messages on its hard disk. That way, the messages will be retained if the AMQP server is restarted, if the message queue is set to be durable on the AMQP server.

port()

Type: number
Default: 5672

Description: The port number of the AMQP server.

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

routing-key()

Type: string
Default: empty string

Description: Specifies a routing key for the exchange. The routing key selects certain messages published to an exchange to be routed to the bound queue. In other words, the routing key acts like a filter. The routing key can include macros and templates.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

username()

Type: string
Default: empty string

Description: The username used to authenticate on the AMQP server.

value-pairs()

Type: parameter list of the value-pairs() option
Default:
scope("selected-macros" "nv-pairs")

Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Section 2.10, Structuring macros, metadata, and other value-pairs.

Note

Empty keys are not logged.

vhost()

Type: string
Default: /

Description: The name of the AMQP virtual host to send the messages to.

7.2. Sending messages directly to Elasticsearch version 1.x

Starting with version 3.7 of syslog-ng OSE can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana.

Note the following limitations when using the syslog-ng OSE elasticsearch destination:

  • This destination is only supported on the Linux platform.

  • Since syslog-ng OSE uses the official Java Elasticsearch libraries, the elasticsearch destination has significant memory usage.

  • Sending messages over the HTTP REST API is supported only using the elastic2() destination. Note that in HTTP mode, the elasticsearch2 destination can send log messages to Elasticsearch version 1.x and newer. For details, see Section 7.3, Sending messages directly to Elasticsearch version 2.0 or higher.

  • The log messages of the underlying client libraries are available in the internal() source of syslog-ng OSE.

Declaration: 

@module mod-java
@include "scl.conf"

elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
);
Example 7.4. Sending log data to Elasticsearch version 1.x

The following example defines an elasticsearch destination that sends messages in transport mode to an Elasticsearch server version 1.x running on the localhost, using only the required parameters.

@module mod-java
@include "scl.conf"

destination d_elastic {
  elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
  );
};

The following example sends 10000 messages in a batch, in transport mode, and includes a custom unique ID for each message.

@module mod-java
@include "scl.conf"

options {
  threaded(yes);
  use-uniqid(yes);
};

source s_syslog {
  syslog();
};

destination d_elastic {
  elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
    client-mode("transport")
    custom-id("${UNIQID}")
    flush-limit("10000")
  );
};

log {
  source(s_syslog);
  destination(d_elastic);
  flags(flow-control);
};

The elasticsearch() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of syslog-ng OSE. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the elasticsearch configuration snippet on GitHub. For details on extending syslog-ng OSE in Java, see the Getting started with syslog-ng development guide.

7.2.1. Procedure – Prerequisites

To send messages from syslog-ng OSE to Elasticsearch, complete the following steps.

Steps: 

  1. If you want to use the Java-based modules of syslog-ng OSE (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile syslog-ng OSE with Java support.

    • Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.

    • Install gradle version 2.2.1 or newer.

    • Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH

      Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start syslog-ng OSE set LD_LIBRARY_PATH in the script as well.

    • If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.

  2. Download the Elasticsearch libraries version 1.5 or newer from the 1.x line from https://www.elastic.co/downloads/elasticsearch. To use Elasticsearch 2.x or newer, use the elasticsearch2() destination (see Section 7.3, Sending messages directly to Elasticsearch version 2.0 or higher).

  3. Extract the Elasticsearch libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/elasticsearch/lib/) where syslog-ng OSE can access them. You must specify this directory in the syslog-ng OSE configuration file. The files are located in the lib directory and its subdirectories of the Elasticsearch release package.

7.2.2. How syslog-ng OSE interacts with Elasticsearch

The syslog-ng OSE application sends the log messages to the official Elasticsearch client library, which forwards the data to the Elasticsearch nodes. The way how syslog-ng OSE interacts with Elasticsearch is described in the following steps.

  • After syslog-ng OSE is started and the first message arrives to the elasticsearch destination, the elasticsearch destination tries to connect to the Elasticsearch server or cluster. If the connection fails, syslog-ng OSE will repeatedly attempt to connect again after the period set in time-reopen() expires.

  • If the connection is established, syslog-ng OSE sends JSON-formatted messages to Elasticsearch.

    • If flush-limit is set to 1: syslog-ng OSE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng OSE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

      This method ensures reliable message transfer, but is slow (about 1000 messages/second).

    • If flush-limit is higher than 1: syslog-ng OSE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng OSE cannot resend the messages.

      This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before syslog-ng OSE recognizes the error. In node mode, about 1000 messages can be lost.

    • If concurrent-requests is higher than 1, syslog-ng OSE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see Section concurrent-requests().

7.2.3. Client modes

The syslog-ng OSE application can interact with Elasticsearch in transport mode or node mode.

  • Transport mode. The syslog-ng OSE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng OSE configuration file.

  • Node mode. The syslog-ng OSE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    Note

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home paramter in the .yml file. For example: path.home: /usr/share/elasticsearch.

7.2.4. Elasticsearch destination options

The elasticsearch destination can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana. The elasticsearch destination has the following options.

Required options: 

The following options are required: index(), type(). In node mode, the cluster() and the resource() options are required as well. Note that to use elasticsearch, you must add the following lines to the beginning of your syslog-ng OSE configuration:

@module mod-java
@include "scl.conf"

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

For the elasticsearch destination, include the path to the directory where you copied the required libraries (see Procedure 7.2.1, Prerequisites), for example, client_lib_dir("/opt/elasticsearch/libs").

client-mode()

Type: transport | node | shield
Default: node

Description: Specifies the client mode used to connect to the Elasticsearch server, for example, client-mode("node").

  • HTTP mode. The syslog-ng OSE application sends messages over HTTP using the REST API of Elasticsearch, and uses the cluster_url() and cluster() options from the syslog-ng OSE configuration file. In HTTP mode, syslog-ng OSE elasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-5.x. Note that HTTP mode is available in syslog-ng OSE version 3.8 and newer.

  • Transport mode. The syslog-ng OSE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng OSE configuration file.

  • Node mode. The syslog-ng OSE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    Note

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home parameter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • Shield mode. Use Elasticsearch X-Pack security (Shield) to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Shield mode, see Procedure 7.3.4, Elasticsearch X-Pack (Shield) and syslog-ng OSE.

  • Search Guard mode. Use the Search Guard Elasticsearch plugin to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Search Guard mode, see Procedure 7.3.5, Search Guard and syslog-ng OSE.

Note

In Node mode, it is required to define the home of the elasticsearch installation with the path.home paramter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • To use this mode, add the Shield .jar file (shield-x.x.x.jar) to the same directory where your Elasticsearch .jar files are located. You can download the Shield distribution and extract the .jar file manually, or you can get it from the Elasticsearch Maven repository.

    It inherits the Transport mode options, but the Shield-related options must be configured in the .yml file (see the resource() option of syslog-ng PE). For more details about the possible options, see: https://www.elastic.co/guide/en/shield/current/reference.html#ref-ssl-tls-settings.

    Example 7.5. Example for the .yml file
    shield.user: es_admin:********
    shield.transport.ssl: true
    shield.ssl.keystore.path: /usr/share/elasticsearch/node.jks
    shield.ssl.keystore.password: mypassword
    

cluster()

Type: string
Default: N/A

Description: Specifies the name or the Elasticsearch cluster, for example, cluster("my-elasticsearch-cluster"). Optionally, you can specify the name of the cluster in the Elasticsearch resource file. For details, see Section resource().

cluster-url()

Type: string
Default: N/A

Description: Specifies the URL or the Elasticsearch cluster, for example, cluster-url("http://192.168.10.10:9200")"). Note that this option works only in HTTP mode: client_mode(http)

concurrent-requests()

Type: number
Default: 0

Description: The number of concurrent (simultaneous) requests that syslog-ng OSE sends to the Elasticsearch server. Set this option to 1 or higher to increase performance. When using the concurrent-requests() option, make sure that the flush-limit() option is higher than one, otherwise it will not have any noticeable effect. For details, see Section flush-limit().

Warning

Hazard of data loss! Using the concurrent-requests() option increases the number of messages lost in case the Elasticsearch server becomes unaccessible.

custom-id()

Type: template or template function
Default: N/A

Description: Use this option to specify a custom ID for the records inserted into Elasticsearch. If this option is not set, the Elasticsearch server automatically generates and ID for the message. For example: custom_id(${UNIQID}) (Note that to use the ${UNIQID} macro, the use-uniqid() global option must be enabled. For details, see Section use-uniqid().)

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.6. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

flush-limit()

Type: number
Default: 5000

Description: The number of messages that syslog-ng OSE sends to the Elasticsearch server in a single batch.

  • If flush-limit is set to 1: syslog-ng OSE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng OSE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

    This method ensures reliable message transfer, but is slow (about 1000 messages/second).

  • If flush-limit is higher than 1: syslog-ng OSE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng OSE cannot resend the messages.

    This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before syslog-ng OSE recognizes the error. In node mode, about 1000 messages can be lost.

  • If concurrent-requests is higher than 1, syslog-ng OSE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see Section concurrent-requests().

frac-digits()

Type: number
Default: 0

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The 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. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

index()

Type: string
Default: N/A

Description: Name of the Elasticsearch index to store the log messages. You can use macros and templates as well. For example, index("syslog-ng_${YEAR}.${MONTH}.${DAY}").

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

on-error()

Accepted values: drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string
Default: Use the global setting (which defaults to drop-message)

Description: Controls what happens when type-casting fails and syslog-ng OSE cannot convert some data to the specified type. By default, syslog-ng OSE drops the entire message and logs the error. Currently the value-pairs() option uses the settings of on-error().

  • drop-message: Drop the entire message and log an error message to the internal() source. This is the default behavior of syslog-ng OSE.

  • drop-property: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the internal() source.

  • fallback-to-string: Convert the property to string and log an error message to the internal() source.

  • silently-drop-message: Drop the entire message silently, without logging the error.

  • silently-drop-property: Omit the affected property (macro, template, or message-field) silently, without logging the error.

  • silently-fallback-to-string: Convert the property to string silently, without logging the error.

port()

Type: number
Default: 9300

Description: The port number of the Elasticsearch server. This option is used only in transport mode: client-mode("transport")

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

resource()

Type: string
Default: N/A

Description: The list of Elasticsearch resources to load, separated by semicolons. For example, resource("/home/user/elasticsearch/elasticsearch.yml;/home/user/elasticsearch/elasticsearch2.yml").

server()

Type: list of hostnames
Default: 127.0.0.1

Description: Specifies the hostname or IP address of the Elasticsearch server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. When specifying multiple addresses, use space to separate the addresses, for example, server("127.0.0.1 remote-server-hostname1 remote-server-hostname2")

This option is used only in transport mode: client-mode("transport")

template()

Type: template or template function
Default: $(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE})

Description: The message as sent to the Elasticsearch server. Typically, you will want to use the command-line notation of the format-json template function.

To add a @timestamp field to the message, for example, to use with Kibana, include the @timestamp=${ISODATE} expression in the template. For example: template($(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}))

For details on formatting messages in JSON format, see Section format-json.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

time-zone()

Type: name of the timezone, or the timezone offset
Default: unspecified

Description: 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. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Section 11.1.3, Date-related macros.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

ts-format()

Type: rfc3164, bsd, rfc3339, iso
Default: rfc3164

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see Section ts-format().

type()

Type: string
Default: N/A

Description: The type of the index. For example, type("test").

7.3. Sending messages directly to Elasticsearch version 2.0 or higher

Starting with version 3.7 of syslog-ng OSE can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana.

Note the following limitations when using the syslog-ng OSE elasticsearch2 destination:

  • This destination is only supported on the Linux platform.

  • Since syslog-ng OSE uses the official Java Elasticsearch libraries, the elasticsearch2 destination has significant memory usage.

  • The log messages of the underlying client libraries are available in the internal() source of syslog-ng OSE.

Declaration: 

@module mod-java
@include "scl.conf"

elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
);
Example 7.7. Sending log data to Elasticsearch version 2.x and above

The following example defines an elasticsearch2 destination that sends messages in transport mode to an Elasticsearch server running on the localhost, using only the required parameters.

@module mod-java
@include "scl.conf"

destination d_elastic {
  elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
  );
};

The following example sends 10000 messages in a batch, in transport mode, and includes a custom unique ID for each message.

@module mod-java
@include "scl.conf"

options {
  threaded(yes);
  use-uniqid(yes);
};

source s_syslog {
  syslog();
};

destination d_elastic {
  elasticsearch2(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
    client-mode("transport")
    custom-id("${UNIQID}")
    flush-limit("10000")
  );
};

log {
  source(s_syslog);
  destination(d_elastic);
  flags(flow-control);
};
Example 7.8. Sending log data to Elasticsearch using the HTTP REST API

The following example send messages to Elasticsearch over HTTP using its REST API:

@include "scl.conf"

source s_network {
    network(port(5555));
};

destination d_elastic {
    elasticsearch2(
        client-mode("http")
        cluster("es-syslog-ng")
        index("x201")
        cluster-url("http://192.168.33.10:9200")
        type("slng_test_type")
        flush-limit("0")
    );
};

log {
   source(s_network);
   destination(d_elastic);
   flags(flow-control);
};

The elasticsearch2() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of syslog-ng OSE. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the elasticsearch configuration snippet on GitHub. For details on extending syslog-ng OSE in Java, see the Getting started with syslog-ng development guide.

7.3.1. Procedure – Prerequisites

To send messages from syslog-ng OSE to Elasticsearch, complete the following steps.

Steps: 

  1. Download and install the Java Runtime Environment (JRE), 2.x (or newer). The syslog-ng OSE elasticsearch2 destination is tested and supported when using the Oracle implementation of Java. Other implementations are untested and unsupported, they may or may not work as expected.

  2. Download the Elasticsearch libraries (version 2.x or newer from the 2.x line) from https://www.elastic.co/downloads/elasticsearch.

  3. Extract the Elasticsearch libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/elasticsearch/lib/) where syslog-ng OSE can access them. You must specify this directory in the syslog-ng OSE configuration file. The files are located in the lib directory and its subdirectories of the Elasticsearch release package.

7.3.2. How syslog-ng OSE interacts with Elasticsearch

The syslog-ng OSE application sends the log messages to the official Elasticsearch client library, which forwards the data to the Elasticsearch nodes. The way how syslog-ng OSE interacts with Elasticsearch is described in the following steps.

  • After syslog-ng OSE is started and the first message arrives to the elasticsearch2 destination, the elasticsearch2 destination tries to connect to the Elasticsearch server or cluster. If the connection fails, syslog-ng OSE will repeatedly attempt to connect again after the period set in time-reopen() expires.

  • If the connection is established, syslog-ng OSE sends JSON-formatted messages to Elasticsearch.

    • If flush-limit is set to 1: syslog-ng OSE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng OSE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

      This method ensures reliable message transfer, but is slow (about 1000 messages/second).

    • If flush-limit is higher than 1: syslog-ng OSE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng OSE cannot resend the messages.

      This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before syslog-ng OSE recognizes the error. In node mode, about 1000 messages can be lost.

    • If concurrent-requests is higher than 1, syslog-ng OSE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see Section concurrent-requests().

7.3.3. Client modes

The syslog-ng OSE application can interact with Elasticsearch in the following modes of operation: http, node, shield, and transport.

  • HTTP mode. The syslog-ng OSE application sends messages over HTTP using the REST API of Elasticsearch, and uses the cluster_url() and cluster() options from the syslog-ng OSE configuration file. In HTTP mode, syslog-ng OSE elasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-5.x. Note that HTTP mode is available in syslog-ng OSE version 3.8 and newer.

  • Transport mode. The syslog-ng OSE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng OSE configuration file.

  • Node mode. The syslog-ng OSE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    Note

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home parameter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • Shield mode. Use Elasticsearch X-Pack security (Shield) to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Shield mode, see Procedure 7.3.4, Elasticsearch X-Pack (Shield) and syslog-ng OSE.

  • Search Guard mode. Use the Search Guard Elasticsearch plugin to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Search Guard mode, see Procedure 7.3.5, Search Guard and syslog-ng OSE.

7.3.4. Procedure – Elasticsearch X-Pack (Shield) and syslog-ng OSE

Purpose: 

Version 3.8 and later supports Elasticsearch X-Pack security (Shield) to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. In this mode, syslog-ng OSE uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng OSE configuration file, but with Shield (X-Pack security) support. To configure syslog-ng OSE to send messages to an Elasticsearch cluster that uses Shield, complete the following steps.

Steps: 

  1. Add the Shield .jar file (shield-x.x.x.jar) to the same directory where your Elasticsearch .jar files are located. You can download the Shield distribution and extract the .jar file manually, or you can get it from the Elasticsearch Maven repository.

  2. Shield mode inherits the Transport mode options, but the Shield-related options must be configured in the .yml file (see the Section resource()). For example:

    shield.user: es_admin:********
    shield.transport.ssl: true
    shield.ssl.keystore.path: /usr/share/elasticsearch/node.jks
    shield.ssl.keystore.password: mypassword

    For more details about the possible options, see: https://www.elastic.co/guide/en/shield/current/reference.html#ref-ssl-tls-settings.

  3. Configure an Elasticsearch destination in syslog-ng OSE that uses the shield client mode.

7.3.5. Procedure – Search Guard and syslog-ng OSE

Purpose: 

Version 3.9 and later supports the Search Guard Elasticsearch plugin (version 2.4.1.16 and newer) to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. To configure syslog-ng OSE to send messages to an Elasticsearch cluster that uses Search Guard, complete the following steps.

Steps: 

  1. Install the Search Guard plugin on your syslog-ng OSE host. Use the plugin version that matches the version of your Elasticsearch installation.

    sudo /usr/share/elasticsearch/bin/plugin install -b com.floragunn/search-guard-ssl/<version-number-of-the-plugin>
  2. Create a certificate for your syslog-ng OSE host, and add the certificate to the SYSLOG_NG-NODE_NAME-keystore.jks file. You can configure the location of this file in the Elasticsearch resources file under the path.conf parameter. For details, see the Search Guard documentation.

  3. Configure an Elasticsearch destination in syslog-ng OSE that uses the searchguard client mode. For example:

    destination d_elasticsearch {
      elasticsearch2(
        client-lib-dir("/usr/share/elasticsearch/plugins/search-guard-ssl/*.jar:/usr/share/elasticsearch/lib")
        index("syslog-${YEAR}.${MONTH}.${DAY}")
        type("syslog")
        time-zone("UTC")
        client_mode("searchguard")
        resource("/etc/syslog-ng/elasticsearch.yml")
      );
    };
  4. Configure the Elasticsearch resource file (for example, /etc/syslog-ng/elasticsearch.yml) as needed for your environment. Note the searchguard: section.

    cluster:
      name: elasticsearch
    discovery:
      zen:
        ping:
          unicast:
            hosts:
              - <ip-address-of-the-elasticsearch-server>
    node:
      name: syslog_ng_secure
      data; false
      master: false
    path:
      home: /etc/syslog-ng
      conf: /etc/syslog-ng
    searchguard:
      ssl:
        transport:
          keystore_filepath: syslog_ng-keystore.jks
          keystore_password: changeit
          truststore_filepath: truststore.jks
          truststore_password: changeit
          enforce_hostname_verification: true

7.3.6. Elasticsearch destination options

The elasticsearch2 destination can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana. The elasticsearch2 destination has the following options.

Required options: 

The following options are required: index(), type(). In node mode, either the cluster() or the resource() option is required as well. Note that to use elasticsearch2, you must add the following lines to the beginning of your syslog-ng OSE configuration:

@module mod-java
@include "scl.conf"

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

Description: Include the path to the directory where you copied the required libraries (see Procedure 7.3.1, Prerequisites), for example, client_lib_dir(/user/share/elasticsearch-2.2.0/lib).

client-mode()

Type: http| transport | node | shield | searchguard
Default: node

Description: Specifies the client mode used to connect to the Elasticsearch server, for example, client-mode("node").

  • HTTP mode. The syslog-ng OSE application sends messages over HTTP using the REST API of Elasticsearch, and uses the cluster_url() and cluster() options from the syslog-ng OSE configuration file. In HTTP mode, syslog-ng OSE elasticsearch2 driver can send log messages to every Elasticsearch version, including 1.x-5.x. Note that HTTP mode is available in syslog-ng OSE version 3.8 and newer.

  • Transport mode. The syslog-ng OSE application uses the transport client API of Elasticsearch, and uses the server(), port(), and cluster() options from the syslog-ng OSE configuration file.

  • Node mode. The syslog-ng OSE application acts as an Elasticsearch node (client no-data), using the node client API of Elasticsearch. Further options for the node can be describe in an Elasticsearch configuration file specified in the resource() option.

    Note

    In Node mode, it is required to define the home of the elasticsearch installation with the path.home parameter in the .yml file. For example: path.home: /usr/share/elasticsearch.

  • Shield mode. Use Elasticsearch X-Pack security (Shield) to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Shield mode, see Procedure 7.3.4, Elasticsearch X-Pack (Shield) and syslog-ng OSE.

  • Search Guard mode. Use the Search Guard Elasticsearch plugin to encrypt and authenticate your connections to from syslog-ng OSE to Elasticsearch 2 and newer. For details on configuring Search Guard mode, see Procedure 7.3.5, Search Guard and syslog-ng OSE.

cluster()

Type: string
Default: N/A

Description: Specifies the name or the Elasticsearch cluster, for example, cluster("my-elasticsearch-cluster"). Optionally, you can specify the name of the cluster in the Elasticsearch resource file. For details, see Section resource().

cluster-url()

Type: string
Default: N/A

Description: Specifies the URL or the Elasticsearch cluster, for example, cluster-url("http://192.168.10.10:9200")"). Note that this option works only in HTTP mode: client_mode(http)

concurrent-requests()

Type: number
Default: 0

Description: The number of concurrent (simultaneous) requests that syslog-ng OSE sends to the Elasticsearch server. Set this option to 1 or higher to increase performance. When using the concurrent-requests() option, make sure that the flush-limit() option is higher than one, otherwise it will not have any noticeable effect. For details, see Section flush-limit().

Warning

Hazard of data loss! Using the concurrent-requests() option increases the number of messages lost in case the Elasticsearch server becomes unaccessible.

custom-id()

Type: template or template function
Default: N/A

Description: Use this option to specify a custom ID for the records inserted into Elasticsearch. If this option is not set, the Elasticsearch server automatically generates and ID for the message. For example: custom_id(${UNIQID}) (Note that to use the ${UNIQID} macro, the use-uniqid() global option must be enabled. For details, see Section use-uniqid().)

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.9. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

flush-limit()

Type: number
Default: 5000

Description: The number of messages that syslog-ng OSE sends to the Elasticsearch server in a single batch.

  • If flush-limit is set to 1: syslog-ng OSE sends the message reliably: it sends a message to Elasticsearch, then waits for a reply from Elasticsearch. In case of failure, syslog-ng OSE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

    This method ensures reliable message transfer, but is slow (about 1000 messages/second).

  • If flush-limit is higher than 1: syslog-ng OSE sends messages in a batch, and receives the response asynchronously. In case of a problem, syslog-ng OSE cannot resend the messages.

    This method is relatively fast (depending on the size of flush-limit, about 8000 messages/second), but the transfer is not reliable. In transport mode, over 5000-30000 messages can be lost before syslog-ng OSE recognizes the error. In node mode, about 1000 messages can be lost.

  • If concurrent-requests is higher than 1, syslog-ng OSE can send multiple batches simultaneously, increasing performance (and also the number of messages that can be lost in case of an error). For details, see Section concurrent-requests().

frac-digits()

Type: number
Default: 0

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The 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. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

index()

Type: string
Default: N/A

Description: Name of the Elasticsearch index to store the log messages. You can use macros and templates as well. For example, index("syslog-ng_${YEAR}.${MONTH}.${DAY}").

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

on-error()

Accepted values: drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string
Default: Use the global setting (which defaults to drop-message)

Description: Controls what happens when type-casting fails and syslog-ng OSE cannot convert some data to the specified type. By default, syslog-ng OSE drops the entire message and logs the error. Currently the value-pairs() option uses the settings of on-error().

  • drop-message: Drop the entire message and log an error message to the internal() source. This is the default behavior of syslog-ng OSE.

  • drop-property: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the internal() source.

  • fallback-to-string: Convert the property to string and log an error message to the internal() source.

  • silently-drop-message: Drop the entire message silently, without logging the error.

  • silently-drop-property: Omit the affected property (macro, template, or message-field) silently, without logging the error.

  • silently-fallback-to-string: Convert the property to string silently, without logging the error.

port()

Type: number
Default: 9300

Description: The port number of the Elasticsearch server. This option is used only in transport mode: client-mode("transport")

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

resource()

Type: string
Default: N/A

Description: The list of Elasticsearch resources to load, separated by semicolons. For example, resource("/home/user/elasticsearch/elasticsearch.yml;/home/user/elasticsearch/elasticsearch2.yml").

server()

Type: list of hostnames
Default: 127.0.0.1

Description: Specifies the hostname or IP address of the Elasticsearch server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. When specifying multiple addresses, use space to separate the addresses, for example, server("127.0.0.1 remote-server-hostname1 remote-server-hostname2")

This option is used only in transport mode: client_mode("transport")

skip-cluster-health-check()

Type: yes|no
Default: no

Description: By default, when connecting to an Elasticsearch cluster, syslog-ng OSE checks the state of the cluster. If the primary shards of the cluster are not active, syslog-ng OSE will not send messages, but wait for them to become active. To disable this health check and send the messages to Elasticsearch anyway, use the skip-cluster-health-check(yes) option in your configuration.

template()

Type: template or template function
Default: $(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE})

Description: The message as sent to the Elasticsearch server. Typically, you will want to use the command-line notation of the format-json template function.

To add a @timestamp field to the message, for example, to use with Kibana, include the @timestamp=${ISODATE} expression in the template. For example: template($(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}))

For details on formatting messages in JSON format, see Section format-json.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

time-zone()

Type: name of the timezone, or the timezone offset
Default: unspecified

Description: 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. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Section 11.1.3, Date-related macros.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

ts-format()

Type: rfc3164, bsd, rfc3339, iso
Default: rfc3164

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see Section ts-format().

type()

Type: string
Default: N/A

Description: The type of the index. For example, type("test").

7.4. Storing messages in plain-text files

The file driver is one of the most important destination drivers in syslog-ng. It allows to output messages to the specified text file, or to a set of files.

The destination filename may include macros which get expanded when the message is written, thus a simple file() driver may create several files: for example, syslog-ng OSE can store the messages of client hosts in a separate file for each host. For more information on available macros see Section 11.1.5, Macros of syslog-ng OSE.

If the expanded filename refers to a directory which does not exist, it will be created depending on the create-dirs() setting (both global and a per destination option).

The file() has a single required parameter that specifies the filename that stores the log messages. For the list of available optional parameters, see Section 7.4.1, file() destination options.

Declaration: 

file(filename options());
Example 7.10. Using the file() driver
destination d_file { file("/var/log/messages"); };
Example 7.11. Using the file() driver with macros in the file name and a template for the message
destination d_file {
        file("/var/log/${YEAR}.${MONTH}.${DAY}/messages"
             template("${HOUR}:${MIN}:${SEC} ${TZ} ${HOST} [${LEVEL}] ${MSG}\n")
             template-escape(no));
};
Note

When using this destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.

Also, after rotating the log files, reload syslog-ng OSE using the syslog-ng-ctl reload command, or use another method to send a SIGHUP to syslog-ng OSE.

Warning

Since the state of each created file must be tracked by syslog-ng, it consumes some memory for each file. If no new messages are written to a file within 60 seconds (controlled by the time-reap() global option), it is closed, and its state is freed.

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 syslog-ng server.

The most suspicious macro is ${PROGRAM}, where the number of possible variations is rather high. Do not use the ${PROGRAM} macro in insecure environments.

7.4.1. file() destination options

The file() driver outputs messages to the specified text file, or to a set of files. The file() destination has the following options:

Warning

When creating several thousands separate log files, syslog-ng might not be able to open the required number of files. This might happen for example when using the ${HOST} macro in the filename while receiving messages from a large number of hosts. To overcome this problem, adjust the --fd-limit command-line parameter of syslog-ng or the global ulimit parameter of your host. For setting the --fd-limit command-line parameter of syslog-ng see the syslog-ng(8) manual page. For setting the ulimit parameter of the host, see the documentation of your operating system.

create-dirs()

Type: yes or no
Default: no

Description: Enable creating non-existing directories.

dir-group()

Type: string
Default: Use the global settings

Description: The group of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-group().

dir-owner()

Type: string
Default: Use the global settings

Description: The owner of the directories created by syslog-ng. To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-owner().

dir-perm()

Type: number
Default: Use the global settings

Description: The permission mask of directories created by syslog-ng. Log directories are only created if a file after macro expansion refers to a non-existing directory, and directory creation is enabled (see also the create-dirs() option). For octal numbers prefix the number with 0, for example use 0755 for rwxr-xr-x.

To preserve the original properties of an existing directory, use the option without specifying an attribute: dir-perm(). Note that when creating a new directory without specifying attributes for dir-perm(), the default permission of the directories is masked with the umask of the parent process (typically 0022).

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.12. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

flags()

Type: no-multi-line, syslog-protocol
Default: empty set

Description: Flags influence the behavior of the destination driver.

  • no-multi-line: The no-multi-line flag disables line-breaking in the messages: the entire message is converted to a single line.

  • syslog-protocol: The syslog-protocol flag instructs the driver to format the messages according to the new IETF syslog protocol standard (RFC5424), but without the frame header. If this flag is enabled, macros used for the message have effect only for the text of the message, the message header is formatted to the new standard. Note that this flag is not needed for the syslog driver, and that the syslog driver automatically adds the frame header to the messages.

flush-lines()

Type: number
Default: Use global setting.

Description: Specifies how many lines are flushed to a destination at a time. The syslog-ng OSE application waits for this number of lines to accumulate and sends them off in a single batch. Increasing this number increases throughput as more messages are sent in a single batch, but also increases message latency.

The syslog-ng OSE application flushes the messages if it has sent flush-lines() number of messages, or the queue became empty. If you stop or reload syslog-ng OSE or in case of network sources, the connection with the client is closed, syslog-ng OSE automatically sends the unsent messages to the destination.

For optimal performance when sending messages to an syslog-ng OSE server, make sure that the flush-lines() is smaller than the window size set using the log-iw-size() option in the source of your server.

flush-timeout() (DEPRECATED)

Type: time in milliseconds
Default: Use global setting.

Description: This is a deprecated option. Specifies the time syslog-ng waits for lines to accumulate in its output buffer. For details, see the flush-lines() option.

frac-digits()

Type: number
Default: 0

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The 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. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

fsync()

Type: yes or no
Default: no

Description: Forces an fsync() call on the destination fd after each write. Note: enabling this option may seriously degrade performance.

group()

Type: string
Default: Use the global settings

Description: Set the group of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: group().

local-time-zone()

Type: name of the timezone, or the timezone offset
Default: The local timezone.

Description: Sets the timezone used when expanding filename and tablename templates.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

mark-mode()

Accepted values: internal | dst-idle | host-idle | periodical | none | global
Default:

internal for pipe, program drivers

none for file, unix-dgram, unix-stream drivers

global for syslog, tcp, udp destinations

host-idle for global option

Description: The mark-mode() option can be set for the following destination drivers: file(), program(), unix-dgram(), unix-stream(), network(), pipe(), syslog() and in global option.

  • internal: When internal mark mode is selected, internal source should be placed in the log path as this mode does not generate mark by itself at the destination. This mode only yields the mark messages from internal source. This is the mode as syslog-ng OSE 3.3 worked. MARK will be generated by internal source if there was NO traffic on local sources:

    file(), pipe(), unix-stream(), unix-dgram(), program()

  • dst-idle: Sends MARK signal if there was NO traffic on destination drivers. MARK signal from internal source will be dropped.

    MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().

  • host-idle: Sends MARK signal if there was NO local message on destination drivers. For example MARK is generated even if messages were received from tcp. MARK signal from internal source will be dropped.

    MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().

  • periodical: Sends MARK signal perodically, regardless of traffic on destination driver. MARK signal from internal source will be dropped.

    MARK signal can be sent by the following destination drivers: network(), syslog(), program(), file(), pipe(), unix-stream(), unix-dgram().

  • none: Destination driver drops all MARK messages. If an explicit mark-mode() is not given to the drivers where none is the default value, then none will be used.

  • global: Destination driver uses the global mark-mode() setting. Note that setting the global mark-mode() to global causes a syntax error in syslog-ng OSE.

Note

In case of dst-idle, host-idle and periodical, the MARK message will not be written in the destination, if it is not open yet.

Available in syslog-ng OSE 3.4 and later.

overwrite-if-older()

Type: number
Default: 0

Description: If set to a value higher than 0, syslog-ng OSE checks when the file was last modified before starting to write into the file. If the file is older than the specified amount of time (in seconds), then syslog-ng removes the existing file and opens a new file with the same name. In combination with for example the ${WEEKDAY} macro, this can be used for simple log rotation, in case not all history has to be kept. (Note that in this weekly log rotation example if its Monday 00:01, then the file from last Monday is not seven days old, because it was probably last modified shortly before 23:59 last Monday, so it is actually not even six days old. So in this case, set the overwrite-if-older() parameter to a-bit-less-than-six-days, for example, to 518000 seconds.

owner()

Type: string
Default: Use the global settings

Description: Set the owner of the created file to the one specified. To preserve the original properties of an existing file, use the option without specifying an attribute: owner().

pad-size()

Type: number
Default: 0

Description: If set, syslog-ng OSE will pad output messages to the specified size (in bytes). Some operating systems (such as HP-UX) pad all messages to block boundary. This option can be used to specify the block size. (HP-UX uses 2048 bytes).

Warning

Hazard of data loss! If the size of the incoming message is larger than the previously set pad-size() value, syslog-ng will truncate the message to the specified size. Therefore, all message content above that size will be lost.

perm()

Type: number
Default: Use the global settings

Description: The permission mask of the file if it is created by syslog-ng. For octal numbers prefix the number with 0, for example use 0755 for rwxr-xr-x.

To preserve the original properties of an existing file, use the option without specifying an attribute: perm().

suppress()

Type: seconds
Default: 0 (disabled)

Description: If several identical log messages would be sent to the destination without any other messages between the identical messages (for example, an application repeated an error message ten times), syslog-ng can suppress the repeated messages and send the message only once, followed by the Last message repeated n times. message. The parameter of this option specifies the number of seconds syslog-ng waits for identical messages.

template()

Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Section 11.1.5, Macros of syslog-ng OSE. 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 syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

template-escape()

Type: yes or no
Default: no

Description: Turns on escaping for the ', ", and backspace characters 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.

time-zone()

Type: name of the timezone, or the timezone offset
Default: unspecified

Description: 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. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Section 11.1.3, Date-related macros.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

ts-format()

Type: rfc3164, bsd, rfc3339, iso
Default: rfc3164

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see Section ts-format().

7.5. Sending metrics to Graphite

The graphite() destination can send metrics to a Graphite server to store numeric time-series data. There are many ways to feed the Graphite template function with name value pairs. The syslog-ng OSE CSV and PatternDB parsers (for details, see Section 13.5.1, Using pattern parsers) can parse log messages and generate name value pairs based on message content. The CSV parser (for details, see Section 12.2, Parsing messages with comma-separated and similar values) can be used for logs which have a constant field based structure, like the Apache web server access logs. The patterndb parser can parse information and can extract important fields from free form log messages, as long as patterns describing the log messages are available. Another way is to send JSON-based log messages (for details, see Section 12.4, The JSON parser) to syslog-ng OSE, like running a simple shell script collecting metrics and running it from cron regularly.

Declaration: 

graphite(payload());
Example 7.13. Using the graphite() driver

To use the graphite() destination, the only mandatory parameter is payload, which specifies the value pairs to send to graphite. In the following example any value pairs starting with "monitor." are forwarded to graphite.

destination d_graphite { graphite(payload("--key monitor.*")); };
Note

The graphite() destination is only a wrapper around the network() destination and the graphite-output template function. If you want to fine-tune the TCP parameters, use the network() destination instead, as described in Section graphite-output.

7.5.1. graphite() destination options

The graphite() destination has the following options:

host()

Type: hostname or IP address
Default: localhost

Description: The hostname or IP address of the Graphite server.

port()

Type: number
Default: 2003

Description: The port number of the Graphite server.

payload()

Type: parameter list of the payload() option
Default:
empty string

Description: The payload() option allows you to select which value pairs to forward to graphite.

The syntax of payload is different from the syntax of value-pairs(): use the command-line syntax used in the format-json template function. For details on using the payload() option, see Section graphite-output.

Note

If left empty, there is no data to be forwarded to Graphite.

7.6. Storing messages on the Hadoop Distributed File System (HDFS)

Starting with version 3.7, syslog-ng OSE can send plain-text log files to the Hadoop Distributed File System (HDFS), allowing you to store your log data on a distributed, scalable file system. This is especially useful if you have huge amount of log messages that would be difficult to store otherwise, or if you want to process your messages using Hadoop tools (for example, Apache Pig).

Note the following limitations when using the syslog-ng OSE hdfs destination:

  • This destination is only supported on the Linux platform.

  • Since syslog-ng OSE uses the official Java HDFS client, the hdfs destination has significant memory usage (about 400MB).

  • The syslog-ng OSE application always creates a new file if the previous has been closed. Appending data to existing files is not supported.

  • Macros are not supported in the file path and the filename. You can use only simple file paths for your log files, for example, /usr/hadoop/logfile.txt.

  • You cannot set when log messages are flushed. Hadoop performs this action automatically, depending on its configured block size, and the amount of data received. There is no way for the syslog-ng OSE application to influence when the messages are actually written to disk. This means that syslog-ng OSE cannot guarantee that a message sent to HDFS is actually written to disk. When using flow-control, syslog-ng OSE acknowledges a message as written to disk when it passes the message to the HDFS client. This method is as reliable as your HDFS environment.

  • The log messages of the underlying client libraries are available in the internal() source of syslog-ng OSE.

Declaration: 

@module mod-java
@include "scl.conf"

hdfs(
    client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/:<path-to-preinstalled-hadoop-libraries>")
    hdfs-uri("hdfs://NameNode:8020")
    hdfs-file("<path-to-logfile>")
);
Example 7.14. Storing logfiles on HDFS

The following example defines an hdfs destination using only the required parameters.

@module mod-java
@include "scl.conf"

destination d_hdfs {
    hdfs(
        client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/hadoop/libs")
        hdfs-uri("hdfs://10.140.32.80:8020")
        hdfs-file("/user/log/logfile.txt")
    );
};

The hdfs() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of syslog-ng OSE. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the hdfs configuration snippet on GitHub. For details on extending syslog-ng OSE in Java, see the Getting started with syslog-ng development guide.

7.6.1. Procedure – Prerequisites

To send messages from syslog-ng OSE to HDFS, complete the following steps.

Steps: 

  1. If you want to use the Java-based modules of syslog-ng OSE (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile syslog-ng OSE with Java support.

    • Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.

    • Install gradle version 2.2.1 or newer.

    • Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH

      Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start syslog-ng OSE set LD_LIBRARY_PATH in the script as well.

    • If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.

  2. Download the Hadoop Distributed File System (HDFS) libraries (version 2.x) from http://hadoop.apache.org/releases.html.

  3. Extract the HDFS libraries into a temporary directory, then collect the various .jar files into a single directory (for example, /opt/hadoop/lib/) where syslog-ng OSE can access them. You must specify this directory in the syslog-ng OSE configuration file. The files are located in the various lib directories under the share/ directory of the Hadoop release package. (For example, in Hadoop 2.7, required files are common/hadoop-common-2.7.0.jar, common/libs/*.jar, hdfs/hadoop-hdfs-2.7.0.jar, hdfs/lib/*, but this may change between Hadoop releases, so it is easier to copy every .jar file into a single directory.

7.6.2. Procedure – How syslog-ng OSE interacts with HDFS

The syslog-ng OSE application sends the log messages to the official HDFS client library, which forwards the data to the HDFS nodes. The way how syslog-ng OSE interacts with HDFS is described in the following steps.

  1. After syslog-ng OSE is started and the first message arrives to the hdfs destination, the hdfs destination tries to connect to the HDFS NameNode. If the connection fails, syslog-ng OSE will repeatedly attempt to connect again after the period set in time-reopen() expires.

  2. syslog-ng OSE checks if the path to the logfile exists. If a directory does not exist syslog-ng OSE automatically creates it. syslog-ng OSE creates the destination file (using the filename set in the syslog-ng OSE configuration file, with a UUID suffix to make it unique, for example, /usr/hadoop/logfile.txt.3dc1c59e-ab3b-4b71-9e81-93db477ed9d9) and writes the message into the file. After the file is created, syslog-ng OSE will write all incoming messages into the hdfs destination.

    Note

    You cannot set when log messages are flushed. Hadoop performs this action automatically, depending on its configured block size, and the amount of data received. There is no way for the syslog-ng OSE application to influence when the messages are actually written to disk. This means that syslog-ng OSE cannot guarantee that a message sent to HDFS is actually written to disk. When using flow-control, syslog-ng OSE acknowledges a message as written to disk when it passes the message to the HDFS client. This method is as reliable as your HDFS environment.

  3. If the HDFS client returns an error, syslog-ng OSE attempts to close the file, then opens a new file and repeats sending the message (trying to connect to HDFS and send the message), as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

  4. The syslog-ng OSE application closes the destination file in the following cases:

    • syslog-ng OSE is reloaded

    • syslog-ng OSE is restarted

    • The HDFS client returns an error.

  5. If the file is closed and you have set an archive directory, syslog-ng OSE moves the file to this directory. If syslog-ng OSE cannot move the file for some reason (for example, syslog-ng OSE cannot connect to the HDFS NameNode), the file remains at its original location, syslog-ng OSE will not try to move it again.

7.6.3. Procedure – Storing messages with MapR-FS

The syslog-ng OSE application is also compatible with MapR File System (MapR-FS). MapR-FS provides better performance, reliability, efficiency, maintainability, and ease of use compared to the default Hadoop Distributed Files System (HDFS). To use MapR-FS with syslog-ng OSE, complete the following steps:

  1. Install MapR libraries. Instead of the official Apache HDFS libraries, MapR uses different libraries. The supported version is MapR 4.x.

    1. Download the libraries from the Maven Repository and Artifacts for MapR or get it from an already existing MapR installation.

    2. Install MapR. If you do not know how to install MapR, follow the instructions on the MapR website.

  2. In a default MapR installation, the required libraries are installed in the following path: /opt/mapr/lib.

    Enter the path where MapR was installed in the class-path option of the hdfs destination, for example:

    class-path("/opt/mapr/lib/")

    If the libraries were downloaded from the Maven Repository, the following additional libraries will be requiered. Note that the version numbers in the filenames can be different in the various Hadoop releases:commons-collections-3.2.1.jar, commons-logging-1.1.3.jar, hadoop-auth-2.5.1.jar, log4j-1.2.15.jar, slf4j-api-1.7.5.jar, commons-configuration-1.6.jar, guava-13.0.1.jar, hadoop-common-2.5.1.jar, maprfs-4.0.2-mapr.jar, slf4j-log4j12-1.7.5.jar, commons-lang-2.5.jar, hadoop-0.20.2-dev-core.jar, json-20080701.jar, protobuf-java-2.5.0.jar, zookeeper-3.4.5-mapr-1406.jar.

  3. Configure the hdfs destination in syslog-ng OSE.

    Example 7.15. Storing logfiles with MapR-FS

    The following example defines an hdfs destination for MapR-FS using only the required parameters.

    @module mod-java
    @include "scl.conf"
    
    destination d_mapr {
        hdfs(
            client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/mapr/lib/")
            hdfs-uri("maprfs://10.140.32.80")
            hdfs-file("/user/log/logfile.txt")
        );
    };
    

7.6.4. HDSF destination options

The hdfs destination stores the log messages in files on the Hadoop Distributed File System (HDFS). The hdfs destination has the following options.

The following options are required: hdfs-file(), hdfs-uri(). Note that to use hdfs, you must add the following lines to the beginning of your syslog-ng OSE configuration:

@module mod-java
@include "scl.conf"

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

For the hdfs destination, include the path to the directory where you copied the required libraries (see Procedure 7.6.1, Prerequisites), for example, client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/*.jar:/opt/hadoop/libs/*.jar").

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.16. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

frac-digits()

Type: number
Default: 0

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The 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. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

hdfs-archive-dir()

Type: string
Default: N/A

Description: The path where syslog-ng OSE will move the closed log files. If syslog-ng OSE cannot move the file for some reason (for example, syslog-ng OSE cannot connect to the HDFS NameNode), the file remains at its original location. For example, hdfs-archive-dir("/usr/hdfs/archive/").

hdfs-file()

Type: string
Default: N/A

Description: The path and name of the log file. For example, hdfs-file("/usr/hdfs/mylogfile.txt"). syslog-ng OSE checks if the path to the logfile exists. If a directory does not exist syslog-ng OSE automatically creates it.

Macros are not supported in the file path and the filename. You can use only simple file paths for your log files, for example, /usr/hadoop/logfile.txt.

hdfs-max-filename-length()

Type: number
Default: 255

Description: The maximum length of the filename. This filename (including the UUID that syslog-ng OSE appends to it) cannot be longer than what the file system permits. If the filename is longer than the value of hdfs-max-filename-length, syslog-ng OSE will automatically truncate the filename. For example, hdfs-max-filename-length("255").

hdfs-resources()

Type: string
Default: N/A

Description: The list of Hadoop resources to load, separated by semicolons. For example, hdfs-resources("/home/user/hadoop/core-site.xml;/home/user/hadoop/hdfs-site.xml").

hdfs-uri()

Type: string
Default: N/A

Description: The URI of the HDFS NameNode is in hdfs://IPaddress:port or hdfs://hostname:port format. When using MapR-FS, the URI of the MapR-FS NameNode is in maprfs://IPaddress or maprfs://hostname format, for example: maprfs://10.140.32.80. The IP address of the node can be IPv4 or IPv6. For example, hdfs-uri("hdfs://10.140.32.80:8020"). The IPv6 address must be enclosed in square brackets ([]) as specified by RFC 2732, for example, hdfs-uri("hdfs://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:8020").

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

on-error()

Accepted values: drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string
Default: Use the global setting (which defaults to drop-message)

Description: Controls what happens when type-casting fails and syslog-ng OSE cannot convert some data to the specified type. By default, syslog-ng OSE drops the entire message and logs the error. Currently the value-pairs() option uses the settings of on-error().

  • drop-message: Drop the entire message and log an error message to the internal() source. This is the default behavior of syslog-ng OSE.

  • drop-property: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the internal() source.

  • fallback-to-string: Convert the property to string and log an error message to the internal() source.

  • silently-drop-message: Drop the entire message silently, without logging the error.

  • silently-drop-property: Omit the affected property (macro, template, or message-field) silently, without logging the error.

  • silently-fallback-to-string: Convert the property to string silently, without logging the error.

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

template()

Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Section 11.1.5, Macros of syslog-ng OSE. 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 syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

time-zone()

Type: name of the timezone, or the timezone offset
Default: unspecified

Description: 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. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Section 11.1.3, Date-related macros.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

ts-format()

Type: rfc3164, bsd, rfc3339, iso
Default: rfc3164

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see Section ts-format().

7.7. Posting messages over HTTP

Version 3.7 of syslog-ng OSE can directly post log messages to web services using the HTTP protocol. Error and status messages received from the HTTP server are forwarded to the internal logs of syslog-ng OSE. The current implementation has the following limitations:

Declaration: 

@module mod-java

java(
    class-path("/syslog-ng/install_dir/lib/syslog-ng/java-modules/*.jar")
    class-name("org.syslog_ng.http.HTTPDestination")

    option("url", "http://<server-address>:<port-number>")

);
Example 7.17. Sending log data to a web service

The following example defines an http destination.

@module mod-java

destination d_http {
    java(
        class-path("/syslog-ng/install_dir/lib/syslog-ng/java-modules/*.jar")
        class-name("org.syslog_ng.http.HTTPDestination")

        option("url", "http://192.168.1.1:80")
    );
};

log
    { source(s_file); destination(d_http); flags(flow-control); };

7.7.1. HTTP destination options

The http destination of syslog-ng OSE can directly post log messages to web services using the HTTP protocol. The http destination has the following options. Some of these options are directly used by the Java code underlying the http destination, therefore these options must be specified in the following format:

option("<option-name>", "<option-value>")

For example, option("url", "http://<server-address>:<port-number>"). The exact format to use is indicated in the description of the option.

Required options: 

The following options are required: url(). Note that to use http, you must add the following line to the beginning of your syslog-ng OSE configuration:

@module mod-java

class-name()

Type: string
Default: N/A

Description: The name of the class (including the name of the package) that includes the destination driver to use.

For the http destination, use this option as class-name("org.syslog_ng.http.HTTPDestination").

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

For the http destination, include the path to the java modules of syslog-ng OSE, for example, class-path("/syslog-ng/install_dir/lib/syslog-ng/java-modules/*.jar").

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

method()

Type: DELETE | HEAD | GET | OPTIONS | POST | PUT | TRACE
Default: PUT  

Description: Specifies the HTTP method to use when sending the message to the server. Available in syslog-ng OSE version 3.7.2 and newer.

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

template()

Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Section 11.1.5, Macros of syslog-ng OSE. 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 syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

url()

Type: URL
Default:  

Description: Specifies the hostname or IP address and optionally the port number of the web service that can receive log data via HTTP. Use a colon (:) after the address to specify the port number of the server. You can also use macros, templates, and template functions in the URL, for example: http://host.example.com:8080/${MACRO1}/${MACRO2}/script")

7.8. Posting messages over HTTP without Java

Version 3.8 of syslog-ng OSE can directly post log messages to web services using the HTTP protocol, without having to use Java. The current implementation has the following limitations:

  • Only HTTP connections are supported, HTTPS is not.

  • Only the PUT and the POST methods are supported.

Declaration: 

destination d_http {
    http(
        url("http://127.0.0.1:8000")
        method("PUT")
        user_agent("syslog-ng User Agent")
        user("user")
        password("password")
        headers("HEADER1: header1", "HEADER2: header2")
        body("${ISODATE} ${MSG}")
    );
};
Example 7.18. Sending log data to a web service

The following example defines an http destination.

destination d_http {
    http(url("http://127.0.0.1:8000")
        method("PUT")
        user_agent("syslog-ng User Agent")
        user("user")
        password("password")
        headers("HEADER1: header1", "HEADER2: header2")
        body("${ISODATE} ${MSG}")
    );
};

log
    { source(s_file); destination(d_http); flags(flow-control); };

7.8.1. HTTP destination options

The http destination of syslog-ng OSE can directly post log messages to web services using the HTTP protocol. The http destination has the following options.

Required options: 

The following options are required: url().

body()

Type: string or template
Default:  

Description: The body of the HTTP request, for example, body("${ISODATE} ${MSG}"). You can use strings, macros, and template functions in the body.

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
  Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
  Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
  Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
  Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
  Description: The number of messages stored in the output buffer of the destination.

Options reliable() and disk-buf-size() are required options.

Example 7.19. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-size(10000)
                disk-buf-size(2000000)
                reliable(yes)
                dir("/tmp/disk-buffer")
            )
        );
};

In the following case normal disk-buffer() is used.

destination d_demo {
    network(
            "127.0.0.1"
            port(3333)
            disk-buffer(
                mem-buf-length(10000)
                disk-buf-size(2000000)
                reliable(no)
                dir("/tmp/disk-buffer")
            )
        );
};

headers()

Type: string list
Default:  

Description: Custom HTTP headers to include in the request, for example, headers("HEADER1: header1", "HEADER2: header2")

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

method()

Type: POST | PUT
Default: POST  

Description: Specifies the HTTP method to use when sending the message to the server.

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

template()

Type: string
Default: A format conforming to the default logfile format.

Description: Specifies a template defining the logformat to be used in the destination. Macros are described in Section 11.1.5, Macros of syslog-ng OSE. 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 syslogd or syslog-ng itself). For network destinations make sure the receiver can cope with the custom format defined.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

password()

Type: string
Default:  

Description: The password that syslog-ng OSE uses to authenticate on the server where it sends the messages.

url()

Type: URL
Default:  

Description: Specifies the hostname or IP address and optionally the port number of the web service that can receive log data via HTTP. Use a colon (:) after the address to specify the port number of the server. For example: http://127.0.0.1:8000

user-agent()

Type: string
Default:  

Description: The value of the USER-AGENT header in the messages sent to the server.

username()

Type: string
Default:  

Description: The username that syslog-ng OSE uses to authenticate on the server where it sends the messages.

7.9. Publishing messages to Apache Kafka

Starting with version 3.7, syslog-ng OSE can directly publish log messages to the Apache Kafka message bus, where subscribers can access them.

  • This destination is only supported on the Linux platform.

  • Since syslog-ng OSE uses the official Java Kafka producer, the kafka destination has significant memory usage.

  • The log messages of the underlying client libraries are available in the internal() source of syslog-ng OSE.

Declaration: 

@module mod-java
@include "scl.conf"

kafka(
    client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/:<path-to-preinstalled-kafka-libraries>")
    kafka-bootstrap-servers("1.2.3.4:9092,192.168.0.2:9092")
    topic("${HOST}")

);
Example 7.20. Sending log data to Apache Kafka

The following example defines a kafka destination, using only the required parameters.

@module mod-java
@include "scl.conf"

destination d_kafka {
  kafka(
    client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/KafkaDestination.jar:/usr/share/kafka/lib/")
    kafka-bootstrap-servers("1.2.3.4:9092,192.168.0.2:9092")
    topic("${HOST}")
  );
};

The kafka() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of syslog-ng OSE. For details on using or writing such configuration snippets, see Section 5.6.2, Reusing configuration blocks. You can find the source of the kafka configuration snippet on GitHub. For details on extending syslog-ng OSE in Java, see the Getting started with syslog-ng development guide.

7.9.1. Procedure – Prerequisites

To publish messages from syslog-ng OSE to Apache Kafka, complete the following steps.

Steps: 

  1. If you want to use the Java-based modules of syslog-ng OSE (for example, the Elasticsearch, HDFS, or Kafka destinations), you must compile syslog-ng OSE with Java support.

    • Download and install the Java Runtime Environment (JRE), 1.7 (or newer). You can use OpenJDK or Oracle JDK, other implementations are not tested.

    • Install gradle version 2.2.1 or newer.

    • Set LD_LIBRARY_PATH to include the libjvm.so file, for example:LD_LIBRARY_PATH=/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/amd64/server:$LD_LIBRARY_PATH

      Note that many platforms have a simplified links for Java libraries. Use the simplified path if available. If you use a startup script to start syslog-ng OSE set LD_LIBRARY_PATH in the script as well.

    • If you are behind an HTTP proxy, create a gradle.properties under the modules/java-modules/ directory. Set the proxy parameters in the file. For details, see The Gradle User Guide.

  2. Download the latest stable binary release of the Apache Kafka libraries (version 0.9 or newer) from http://kafka.apache.org/downloads.html.

  3. Extract the Apache Kafka libraries into a single directory. If needed, collect the various .jar files into a single directory (for example, /opt/kafka/lib/) where syslog-ng OSE can access them. You must specify this directory in the syslog-ng OSE configuration file.

  4. Check if the following files in the Kafka libraries have the same version number: slf4j-api-<version-number>.jar, slf4j-log4j12-<version-number>.jar. If the version number of these files is different, complete the following steps:

    1. Delete one of the files (for example, slf4j-log4j12-<version-number>.jar).

    2. Download a version that matches the version number of the other file (for example, 1.7.6) from the official SLF4J distribution.

    3. Copy the downloaded file into the directory of your Kafka library files (for example, /opt/kafka/lib/).

7.9.2. How syslog-ng OSE interacts with Apache Kafka

When stopping the syslog-ng OSE application, syslog-ng OSE will not stop until all Java threads are finished, including the threads started by the Kafka Producer. There is no way (except for the kill -9 command) to stop syslog-ng OSE before the Kafka Producer stops. To change this behavior set the properties of the Kafka Producer in its properties file, and reference the file in the properties-file option.

The syslog-ng OSE kafka destination tries to reconnect to the brokers in a tight loop. This can look as spinning, because of a lot of similar debug messages. To decrease the amount of such messages, set a bigger timeout using the following properties:

retry.backoff.ms=1000
reconnect.backoff.ms=1000

For details on using property files, see Section properties-file(). For details on the properties that you can set in the property file, see the Apache Kafka documentation.

7.9.3. Kafka destination options

The kafka destination of syslog-ng OSE can directly publish log messages to the Apache Kafka message bus, where subscribers can access them. The kafka destination has the following options.

Required options: 

The following options are required: kafka-bootstrap-servers(), topic(). Note that to use kafka, you must add the following lines to the beginning of your syslog-ng OSE configuration:

@module mod-java
@include "scl.conf"

client-lib-dir()

Type: string
Default: The syslog-ng OSE module directory: /opt/syslog-ng/lib/syslog-ng/java-modules/

Description: The list of the paths where the required Java classes are located. For example, class-path("/opt/syslog-ng/lib/syslog-ng/java-modules/:/opt/my-java-libraries/libs/"). If you set this option multiple times in your syslog-ng OSE configuration (for example, because you have multiple Java-based destinations), syslog-ng OSE will merge every available paths to a single list.

For the kafka destination, include the path to the directory where you copied the required libraries (see Procedure 7.9.1, Prerequisites), for example, client-lib-dir("/opt/syslog-ng/lib/syslog-ng/java-modules/KafkaDestination.jar:/usr/share/kafka/lib/*.jar").

kafka-bootstrap-servers()

Type: list of hostnames
Default:  

Description: Specifies the hostname or IP address of the Kafka server. When specifying an IP address, IPv4 (for example, 192.168.0.1) or IPv6 (for example, [::1]) can be used as well. Use a colon (:) after the address to specify the port number of the server. When specifying multiple addresses, use a comma to separate the addresses, for example, kafka-bootstrap-servers("127.0.0.1:2525,remote-server-hostname:6464")

frac-digits()

Type: number
Default: 0

Description: The syslog-ng application can store fractions of a second in the timestamps according to the ISO8601 format. The 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. Note that syslog-ng can add the fractions to non-ISO8601 timestamps as well.

on-error()

Accepted values: drop-message|drop-property|fallback-to-string|silently-drop-message|silently-drop-property|silently-fallback-to-string
Default: Use the global setting (which defaults to drop-message)

Description: Controls what happens when type-casting fails and syslog-ng OSE cannot convert some data to the specified type. By default, syslog-ng OSE drops the entire message and logs the error. Currently the value-pairs() option uses the settings of on-error().

  • drop-message: Drop the entire message and log an error message to the internal() source. This is the default behavior of syslog-ng OSE.

  • drop-property: Omit the affected property (macro, template, or message-field) from the log message and log an error message to the internal() source.

  • fallback-to-string: Convert the property to string and log an error message to the internal() source.

  • silently-drop-message: Drop the entire message silently, without logging the error.

  • silently-drop-property: Omit the affected property (macro, template, or message-field) silently, without logging the error.

  • silently-fallback-to-string: Convert the property to string silently, without logging the error.

key()

Type: template
Default: N/A

Description: The key of the partition under which the message is published. You can use templates to change the topic dynamically based on the source or the content of the message, for example, key("${PROGRAM}").

log-fifo-size()

Type: number
Default: Use global setting.

Description: The number of messages that the output queue can store.

properties-file()

Type: string (absolute path)
Default: N/A

Description: The absolute path and filename of the Kafka properties file to load. For example, properties-file("/opt/syslog-ng/etc/kafka_dest.properties"). The syslog-ng OSE application reads this file and passes the properties to the Kafka Producer. If a property is defined both in the syslog-ng OSE configuration file (syslog-ng.conf) and in the properties file, then syslog-ng OSE uses the definition from the syslog-ng OSE configuration file.

The syslog-ng OSE kafka destination supports all properties of the official Kafka producer. For details, see the Apache Kafka documentation.

The kafka-bootstrap-servers option is translated to the bootstrap.servers property.

For example, the following properties file defines the acknowledgement method and compression:

acks=all
compression.type=snappy

retries()

Type: number (of attempts)
Default: 3

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

sync-send()

Type: true | false
Default: false

Description: When sync-send is set to true, syslog-ng OSE sends the message reliably: it sends a message to the Kafka server, then waits for a reply. In case of failure, syslog-ng OSE repeats sending the message, as set in the retries() parameter. If sending the message fails for retries() times, syslog-ng OSE drops the message.

This method ensures reliable message transfer, but is very slow.

When sync-send is set to false, syslog-ng OSE sends messages asynchronously, and receives the response asynchronously. In case of a problem, syslog-ng OSE cannot resend the messages.

This method is fast, but the transfer is not reliable. Several thousands of messages can be lost before syslog-ng OSE recognizes the error.

template()

Type: template or template function
Default: $ISODATE $HOST $MSGHDR$MSG\n

Description: The message as published to Apache Kafka. You can use templates and template functions (for example, format-json()) to format the message, for example, template("$(format-json --scope rfc5424 --exclude DATE --key ISODATE)").

For details on formatting messages in JSON format, see Section format-json.

throttle()

Type: number
Default: 0

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

topic()

Type: template
Default: N/A

Description: The Kafka topic under which the message is published. You can use templates to change the topic dynamically based on the source or the content of the message, for example, topic("${HOST}").

time-zone()

Type: name of the timezone, or the timezone offset
Default: unspecified

Description: 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. Converting the timezone changes the values of all date-related macros derived from the timestamp, for example, HOUR. For the complete list of such macros, see Section 11.1.3, Date-related macros.

The timezone can be specified as using the name of the (for example time-zone("Europe/Budapest")), or as the timezone offset in +/-HH:MM format (for example +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

ts-format()

Type: rfc3164, bsd, rfc3339, iso
Default: rfc3164

Description: Override the global timestamp format (set in the global ts-format() parameter) for the specific destination. For details, see