This driver writes messages to the terminal of a logged-in user.
The usertty() driver has a single required argument, specifying a username who should receive a copy of matching messages. Use the asterisk * to specify every user currently logged in to the system.
Declaration:
usertty(username);
The usertty() does not have any further options nor does it support templates.
Log paths determine what happens with the incoming log messages. Messages coming from the sources listed in the log statement and matching all the filters are sent to the listed destinations.
To define a log path, add a log statement to the syslog-ng configuration file using the following syntax:
log {
source(s1); source(s2); ...
optional_element(filter1|parser1|rewrite1);
optional_element(filter2|parser2|rewrite2);
...
destination(d1); destination(d2); ...
flags(flag1[, flag2...]);
};
|
|
Caution:
Log statements are processed in the order they appear in the configuration file, thus the order of log paths may influence what happens to a message, especially when using filters and log flags. |
|
|
NOTE:
The order of filters, rewriting rules, and parsers in the log statement is important, as they are processed sequentially. |
Example 8.1. A simple log statement
The following log statement sends all messages arriving to the localhost to a remote server.
source s_localhost { network(ip(127.0.0.1) port(1999)); };
destination d_tcp { network("10.1.2.3" port(1999) localport(999)); };
log { source(s_localhost); destination(d_tcp); };All matching log statements are processed by default, and the messages are sent to every matching destination by default. So a single log message might be sent to the same destination several times, provided the destination is listed in several log statements, and it can be also sent to several different destinations.
This default behavior can be changed using the flags() parameter. Flags apply to individual log paths, they are not global options. For details and examples on the available flags, see the section called “Log path flags”. The effect and use of the flow-control flag is detailed in the section called “Managing incoming and outgoing messages with flow-control”.
Starting from version 3.0, syslog-ng can handle embedded log statements (also called log pipes). Embedded log statements are useful for creating complex, multi-level log paths with several destinations and use filters, parsers, and rewrite rules.
For example, if you want to filter your incoming messages based on the facility parameter, and then use further filters to send messages arriving from different hosts to different destinations, you would use embedded log statements.
Embedded log statements include sources — and usually filters, parsers, rewrite rules, or destinations — and other log statements that can include filters, parsers, rewrite rules, and destinations. The following rules apply to embedded log statements:
Only the beginning (also called top-level) log statement can include sources.
Embedded log statements can include multiple log statements on the same level (that is, a top-level log statement can include two or more log statements).
Embedded log statements can include several levels of log statements (that is, a top-level log statement can include a log statement that includes another log statement, and so on).
After an embedded log statement, you can write either another log statement, or the flags() option of the original log statement. You cannot use filters or other configuration objects. This also means that flags (except for the flow-control flag) apply to the entire log statement, you cannot use them only for the embedded log statement.
Embedded log statements that are on the same level receive the same messages from the higher-level log statement. For example, if the top-level log statement includes a filter, the lower-level log statements receive only the messages that pass the filter.
Embedded log filters can be used to optimize the processing of log messages, for example, to re-use the results of filtering and rewriting operations.
Embedded log statements (for details, see the section called “Embedded log statements”) re-use the results of processing messages (for example the results of filtering or rewriting) to create complex log paths. Embedded log statements use the same syntax as regular log statements, but they cannot contain additional sources. To define embedded log statements, use the following syntax:
log {
source(s1); source(s2);...
optional_element(filter1|parser1|rewrite1);
optional_element(filter2|parser2|rewrite2);
...
destination(d1); destination(d2); ...
#embedded log statement
log {
optional_element(filter1|parser1|rewrite1);
optional_element(filter2|parser2|rewrite2);
...
destination(d1); destination(d2); ...
#another embedded log statement
log {
optional_element(filter1|parser1|rewrite1);
optional_element(filter2|parser2|rewrite2);
...
destination(d1); destination(d2);
...
};
};
#set flags after the embedded log statements
flags(flag1[, flag2...]);
};
Example 8.2. Using embedded log paths
The following log path sends every message to the configured destinations: both the d_file1 and the d_file2 destinations receive every message of the source.
log { source(s_localhost); destination(d_file1); destination(d_file2); };
The next example is equivalent with the one above, but uses an embedded log statement.
log { source(s_localhost); destination(d_file1);
log {destination(d_file2); };
};
The following example uses two filters:
messages coming from the host 192.168.1.1 are sent to the d_file1 destination, and
messages coming from the host 192.168.1.1 and containing the string example are sent to the d_file2 destination.
filter filter_host { host(192.168.1.1) };
filter filter_example { message("example") };
log { source(s_localhost); filter(filter_host); destination(d_file1);
log {filter(filter_example); destination(d_file2); };
};
The following example collects logs from multiple source groups and uses the source() filter in the embedded log statement to select messages of the s_network source group.
log { source(s_localhost); source(s_network); destination(d_file1);
log {source(s_network); destination(d_file2); };
};Flags influence the behavior of syslog-ng, and the way it processes messages. The following flags may be used in the log paths, as described in the section called “Log paths”.
Table 8.1. Log statement flags
| Flag | Description |
|---|---|
| catchall | This flag means that the source of the message is ignored, only the filters of the log path are taken into account when matching messages. A log statement using the catchall flag processes every message that arrives to any of the defined sources. |
| fallback |
This flag makes a log statement 'fallback'. Fallback log statements process messages that were not processed by other, 'non-fallback' log statements. 'Processed' means that every filter of a log path matched the message. Note that in case of embedded log paths, the message is considered to be processed if it matches the filters of the outer log path, even if it does not match the filters of the embedded log path. For details, see Example 8.3, “Using log path flags”. |
| final |
This flag means that the processing of log messages processed by the log statement ends here, other log statements appearing later in the configuration file will not process the messages processed by the log statement labeled as 'final'. Note that this does not necessarily mean that matching messages will be stored only once, as there can be matching log statements processed before the current one (syslog-ng PE evaluates log statements in the order they appear in the configuration file). 'Processed' means that every filter of a log path matched the message. Note that in case of embedded log paths, the message is considered to be processed if it matches the filters of the outer log path, even if it does not match the filters of the embedded log path. For details, see Example 8.3, “Using log path flags”. |
| flow-control | Enables flow-control to the log path, meaning that syslog-ng will stop reading messages from the sources of this log statement if the destinations are not able to process the messages at the required speed. If disabled, syslog-ng will drop messages if the destination queues are full. If enabled, syslog-ng will only drop messages if the destination queues/window sizes are improperly sized. For details, see the section called “Managing incoming and outgoing messages with flow-control”. |
|
|
Caution:
The |
Example 8.3. Using log path flags
Let's suppose that you have two hosts (myhost_A and myhost_B) that run two applications each (application_A and application_B), and you collect the log messages to a central syslog-ng server. On the server, you create two log paths:
one that processes only the messages sent by myhost_A, and
one that processes only the messages sent by application_A.
This means that messages sent by application_A running on myhost_A will be processed by both log paths, and the messages of application_B running on myhost_B will not be processed at all.
If you add the final flag to the first log path, then only this log path will process the messages of myhost_A, so the second log path will receive only the messages of application_A running on myhost_B.
If you create a third log path that includes the fallback flag, it will process the messages not processed by the first two log paths, in this case, the messages of application_B running on myhost_B.
Adding a fourth log path with the catchall flag would process every message received by the syslog-ng server.
log { source(s_localhost); destination(d_file); flags(catchall); };The following example shows a scenario that can result in message loss. Do NOT use such a configuration, unless you know exactly what you are doing. The problem is if a message matches the filters in the first part of the first log path, syslog-ng PE treats the message as 'processed'. Since the first log path includes the final flag, syslog-ng PE will not pass the message to the second log path (the one with the fallback flag). As a result, syslog-ng PE drops messages that do not match the filter of the embedded log path.
# Do not use such a configuration, unless you know exactly what you are doing.
log {
source(s_network);
# Filters in the external log path.
# If a message matches this filter, it is treated as 'processed'
filter(f_program);
filter(f_message);
log {
# Filter in the embedded log path.
# If a message does not match this filter, it is lost, it will not be processed by the 'fallback' log path
filter(f_host);
destination(d_file1);
};
flags(final);
};
log {
source(s_network);
destination(d_file2);
flags(fallback);
};This section describes the internal message-processing model of syslog-ng, as well as the flow-control feature that can prevent message losses. To use flow-control, the flow-control flag must be enabled for the particular log path.
The syslog-ng application monitors (polls) the sources defined in its configuration file, periodically checking each source for messages. When a log message is found in one of the sources, syslog-ng polls every source and reads the available messages. These messages are processed and put into the output buffer of syslog-ng (also called fifo). From the output buffer, the operating system sends the messages to the appropriate destinations.
In large-traffic environments many messages can arrive during a single poll loop, therefore syslog-ng reads only a fixed number of messages from each source. The log-fetch-limit() option specifies the number of messages read during a poll loop from a single source.
|
|
NOTE:
The |
Every destination has its own output buffer. The output buffer is needed because the destination might not be able to accept all messages immediately. The log-fifo-size() parameter sets the size of the output buffer. The output buffer must be larger than the log-fetch-limit() of the sources, to ensure that every message read during the poll loop fits into the output buffer. If the log path sends messages to a destination from multiple sources, the output buffer must be large enough to store the incoming messages of every source.
TCP and unix-stream sources can receive the logs from several incoming connections (for example many different clients or applications). For such sources, syslog-ng reads messages from every connection, thus the log-fetch-limit() parameter applies individually to every connection of the source.
The flow-control of syslog-ng introduces a control window to the source that tracks how many messages can syslog-ng accept from the source. Every message that syslog-ng reads from the source lowers the window size by one, every message that syslog-ng successfully sends from the output buffer increases the window size by one. If the window is full (that is, its size decreases to zero), syslog-ng stops reading messages from the source. The initial size of the control window is by default 1000: the log-fifo-size() must be larger than this value in order for flow-control to have any effect. If a source accepts messages from multiple connections, all messages use the same control window.
When flow-control is used, every source has its own control window. As a worst-case situation, the output buffer of the destination must be set to accommodate all messages of every control window, that is, the log-fifo-size() of the destination must be greater than number_of_sources*log-iw-size(). This applies to every source that sends logs to the particular destination. Thus if two sources having several connections and heavy traffic send logs to the same destination, the control window of both sources must fit into the output buffer of the destination. Otherwise, syslog-ng does not activate the flow-control, and messages may be lost.
The syslog-ng application handles outgoing messages the following way:
Output queue: Messages from the output queue are sent to the target syslog-ng server. The syslog-ng application puts the outgoing messages directly into the output queue, unless the output queue is full. The output queue can hold 64 messages, this is a fixed value and cannot be modified.
Disk buffer: If the output queue is full and disk-buffering is enabled, syslog-ng Premium Edition puts the outgoing messages into the disk buffer of the destination.
Overflow queue: If the output queue is full and the disk buffer is disabled or full, syslog-ng puts the outgoing messages into the overflow queue of the destination. (The overflow queue is identical to the output buffer used by other destinations.) The log-fifo-size() parameter specifies the number of messages stored in the overflow queue. For details on sizing the log-fifo-size() parameter, see the section called “Managing incoming and outgoing messages with flow-control”.
There are two types of flow-control: Hard flow-control and soft flow-control.
Soft flow-control: In case of soft flow-control there is no message lost if the destination can accept messages, but it is possible to lose messages if it cannot accept messages (for example non-writeable file destination, or the disk becomes full), and all buffers are full. Soft flow-control cannot be configured, it is automatically available for file and logstore destinations.
Example 8.4. Soft flow-control
source s_file {file("/tmp/input_file.log");};
destination d_file {file("/tmp/output_file.log");};
destination d_tcp { network("127.0.0.1" port(2222) log-fifo-size(1000)); };
log{ source(s_file); destination(d_file); destination(d_tcp);};
|
|
Caution:
Hazard of data loss! For destinations other than file and logstore, soft flow-control is not available. Thus, it is possible to lose log messages on those destinations. To avoid data loss on those destinations, use hard flow-control. |
Hard flow-control: In case of hard flow-control there is no message lost. To use hard flow-control, enable the flow-control flag in the log path. Hard flow-control is available for all destinations.
Example 8.5. Hard flow-control
source s_file {file("/tmp/input_file.log");};
destination d_file {file("/tmp/output_file.log");};
destination d_tcp { network("127.0.0.1" port(2222) log-fifo-size(1000)); };
log{ source(s_file); destination(d_file); destination(d_tcp) flags(flow-control);};
Using flow-control on a source has an important side-effect if the messages of the source are sent to multiple destinations. If flow-control is in use and one of the destinations cannot accept the messages, the other destinations do not receive any messages either, because syslog-ng stops reading the source. For example, if messages from a source are sent to a remote server and also stored locally in a file, and the network connection to the server becomes unavailable, neither the remote server nor the local file will receive any messages.
|
|
NOTE:
Creating separate log paths for the destinations that use the same flow-controlled source does not avoid the problem. |
If you use flow-control and reliable disk-based buffering together with multiple destinations, the flow-control starts slowing down the source only when:
For details on how flow-control works, see the section called “Managing incoming and outgoing messages with flow-control”. The summary of the main points is as follows:
The syslog-ng application normally reads a maximum of log-fetch-limit() number of messages from a source.
From TCP and unix-stream sources, syslog-ng reads a maximum of log-fetch-limit() from every connection of the source. The number of connections to the source is set using the max-connections() parameter.
Every destination has an output buffer (log-fifo-size()).
Flow-control uses a control window to determine if there is free space in the output buffer for new messages. Every source has its own control window, the log-iw-size() parameter sets the size of the control window.
When a source accepts multiple connections, the size of the control window is divided by the value of the max-connections() parameter and this smaller control window is applied to each connection of the source.
The output buffer must be larger than the control window of every source that logs to the destination.
If the control window is full, syslog-ng stops reading messages from the source until some messages are successfully sent to the destination.
If the output buffer becomes full, and neither disk-buffering nor flow-control is used, messages may be lost.
|
|
Caution:
If you modify the |
Example 8.6. Sizing parameters for flow-control
Suppose that syslog-ng has a source that must accept up to 300 parallel connections. Such situation can arise when a network source receives connections from many clients, or if many applications log to the same socket. Therefore, set the max-connections() parameter of the source to 300. However, the log-fetch-limit() (default value: 10) parameter applies to every connection of the source individually, while the log-iw-size() (default value: 1000) parameter applies to the source. In a worst-case scenario, the destination does not accept any messages, while all 300 connections send at least log-fetch-limit() number of messages to the source during every poll loop. Therefore, the control window must accommodate at least max-connections()*log-fetch-limit() messages to be able to read every incoming message of a poll loop. In the current example this means that (log-iw-size() should be greater than 300*10=3000. If the control window is smaller than this value, the control window might fill up with messages from the first connections — causing syslog-ng to read only one message of the last connections in every poll loop.
The output buffer of the destination must accommodate at least log-iw-size() messages, but use a greater value: in the current example 3000*10=30000 messages. That way all incoming messages of ten poll loops fit in the output buffer. If the output buffer is full, syslog-ng does not read any messages from the source until some messages are successfully sent to the destination.
source s_localhost {
network(ip(127.0.0.1) port(1999) max-connections(300)); };
destination d_tcp {
network("10.1.2.3" port(1999); localport(999)); log-fifo-size(30000); };
log { source(s_localhost); destination(d_tcp); flags(flow-control); };
If other sources send messages to this destination, than the output buffer must be further increased. For example, if a network host with maximum 100 connections also logs into the destination, than increase the log-fifo-size() by 10000.
source s_localhost {
network(ip(127.0.0.1) port(1999) max-connections(300)); };
source s_tcp {
network(ip(192.168.1.5) port(1999) max-connections(100)); };
destination d_tcp {
network("10.1.2.3" port(1999); localport(999)); log-fifo-size(40000); };
log { source(s_localhost); destination(d_tcp); flags(flow-control); };The syslog-ng Premium Edition application can store messages on the local hard disk if the destination (for example, the central log server) or the network connection to the destination becomes unavailable. The syslog-ng PE application automatically sends the stored messages to the destination when the connection is reestablished. The disk buffer is used as a queue: when the connection to the destination is reestablished, syslog-ng PE sends the messages to the destination in the order they were received.
|
|
NOTE:
Disk-based buffering can be used in conjunction with flow-control. For details on flow-control, see the section called “Managing incoming and outgoing messages with flow-control”. |
The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)
Every such destination uses a separate disk buffer (similarly to the output buffers controlled by log-fifo-size()). The hard disk space is not pre-allocated, so ensure that there is always enough free space to store the disk buffers even when the disk buffers are full.
If syslog-ng PE is restarted (using the /etc/init.d/syslog-ng restart command, or another appropriate command on your platform), it automatically saves any unsent messages from the disk buffer and the output queue. After the restart, syslog-ng PE sends the saved messages to the destination. In other words, the disk buffer is persistent. The disk buffer is also resistant to syslog-ng PE crashes.
The syslog-ng PE application supports two types of disk buffering: reliable and normal. For details, see the section called “Enabling reliable disk-based buffering” and the section called “Enabling normal disk-based buffering”, respectively.
Message handling and normal disk-based buffering. When you use disk-based buffering, and the reliable() option is set to no, syslog-ng PE handles outgoing messages the following way:
Output queue: Messages from the output queue are sent to the destination (for example, your central log server). The syslog-ng PE application puts the outgoing messages directly into the output queue, unless the output queue is full. By default, the output queue can hold 64 messages (you can adjust it using the quot-size() option).
Disk buffer: If the output queue is full, disk-buffering is enabled, and reliable() is set to no, syslog-ng PE puts the outgoing messages into the disk buffer of the destination. (The disk buffer is enabled if the log-disk-fifo-size() parameter of the destination is larger than 0. This option specifies the size of the disk buffer in bytes.)
Overflow queue: If the output queue is full and the disk buffer is disabled or full, syslog-ng PE puts the outgoing messages into the overflow queue of the destination. (The overflow queue is identical to the output buffer used by other destinations.) The log-fifo-size() parameter specifies the number of messages stored in the overflow queue. For details on sizing the log-fifo-size() parameter, see also the section called “Managing incoming and outgoing messages with flow-control”.
|
|
NOTE:
Using disk buffer can significantly decrease performance. |
Message handling and reliable disk-based buffering. When you use disk-based buffering, and the reliable() option is set to yes, syslog-ng PE handles outgoing messages the following way.
The mem-buf-size() option determines when flow-control is triggered. All messages arriving to the log path that includes the destination using the disk-buffer are written into the disk-buffer, until the size of the disk-buffer reaches (disk-buf-size() minus mem-buf-size()). Above that size, messages are written into both the disk-buffer and the memory-buffer, indicating that flow-control needs to slow down the message source. These messages are not taken out from the control window (governed by log-iw-size()), causing the control window to fill up. If the control window is full, the flow-control completely stops reading incoming messages from the source. (As a result, mem-buf-size() must be at least as large as log-iw-size().)
The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)
To enable reliable disk-based buffering, use the disk-buffer(reliable(yes)) parameter in the destination. Use reliable disk-based buffering if you do not want to lose logs in case of reload/restart, unreachable destination or syslog-ng PE 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. The filename of the reliable disk buffer file is the following: <syslog-ng path>/var/syslog-ng-00000.rqf.
Example 8.7. Example for using reliable disk-based buffering
destination d_BSD {
network(
"127.0.0.1"
port(3333)
disk-buffer(
mem-buf-size(10000)
disk-buf-size(2000000)
reliable(yes)
)
);
}; The following destination drivers can use disk-based buffering: elasticsearch(), elasticsearch2(), hdfs(), kafka(), mongodb(), program(), smtp(), snmp(), sql(), unix-dgram(), and unix-stream(). The network(), syslog(), tcp(), and tcp6() destination drivers can also use disk-based buffering, except when using the udp transport method. (The other destinations or protocols do not provide the necessary feedback mechanisms required for disk-based buffering.)
To enable normal disk-based buffering, use the disk-buffer(reliable(no)) parameter in the destination. Use normal disk-based buffering if you want a solution that is faster than the reliable disk-based buffering. In this case, disk buffering will be less reliable and it is possible to lose logs in case of syslog-ng PE crash. The filename of the normal disk buffer file is the following: <syslog-ng path>/var/syslog-ng-00000.qf.
It is possible to use this option without using the disk-buffer plugin. In this case, use the log-disk-fifo-size() parameter in the destination.
Example 8.8. Example for using normal disk-based buffering
When using the disk-buffer plugin
destination d_BSD {
network(
"127.0.0.1"
port(3333)
disk-buffer(
mem-buf-length(10000)
disk-buf-size(2000000)
reliable(no)
)
);
};
Without disk-buffer plugin
destination d_BSD {
network(
"127.0.0.1"
port(3333)
log-disk-fifo-size(2000000)
log-fifo-size(10000)
);
}; To enable memory buffering, use the log-fifo-size() parameter in the destination. All destination drivers can use memory buffering. Use memory buffering if you want to send logs to destinations where disk-based buffering is not available. Or if you want the fastest solution, and if syslog-ng PE crash or network downtime is never expected. In these cases, losing logs is possible. This solution does not use disk-based buffering, logs are stored only in the memory.
Example 8.9. Example for using memory buffering
destination d_BSD {
network(
"127.0.0.1"
port(3333)
log-fifo-size(10000)
);
};© ALL RIGHTS RESERVED. 使用条款 隐私 Cookie Preference Center