The syslog-ng PE application can store log messages securely in encrypted, compressed and timestamped binary files. Timestamps can be requested from an external Timestamping Authority (TSA).
Logstore files consist of individual chunks, every chunk can be encrypted, compressed, and timestamped separately. Chunks contain compressed log messages and header information needed for retrieving messages from the logstore file.
The syslog-ng PE application generates an SHA-1 hash for every chunk to verify the integrity of the chunk. The hashes of the chunks are chained together to prevent injecting chunks into the logstore file. The syslog-ng PE application can encrypt the logstore using various algorithms, using the aes128 encryption algorithm in CBC mode and the hmac-sha1 hashing (HMAC) algorithm as default. For other algorithms, see cipher() and digest().
The destination filename may include macros which get expanded when the message is written, thus a simple logstore() driver may create several files. For more information on available macros see Macros of syslog-ng PE.
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 logstore() has a single required parameter that specifies the filename that stores the log messages. For the list of available optional parameters, see logstore() destination options.
Declaration
logstore(filename options());
Example: Using the logstore() driver
A simple example saving and compressing log messages.
destination d_logstore { logstore("/var/log/messages.lgs" compress(5) ); };
A more detailed example that encrypts messages, modifies the parameters for closing chunks, and sets file privileges.
destination d_logstore {
logstore("/var/log/messages-logstore.lgs"
encrypt-certificate("/opt/syslog-ng/etc/syslog-ng/keys/10-100-20-40/public-certificate-of-the-server.pem")
owner("example")
group("example")
perm(0777)
);
};
The URL to the Timestamping Authority and if needed, the OID of the timestamping policy can be set as global options, or also per logstore destination. The following example specifies the URL and the OID as global options:
options {
timestamp-url("http://10.50.50.50:8080/");
timestamp-policy("0.4.0.2023.1.1");
};
NOTE: When using the logstore() destination, update the configuration of your log rotation program to rotate these files. Otherwise, the log files can become very large.
|
|
Caution:
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. |
To display the contents of a logstore file, use the lgstool (formerly called logcat) command supplied with syslog-ng, for example, lgstool cat /var/log/messages.lgs. Log messages available in the journal file of the logstore (but not yet written to the logstore file itself) are displayed as well.
To display the contents of encrypted log files, specify the private key of the certificate used to encrypt the file, for example, lgstool cat -k private.key /var/log/messages.lgs. The contents of the file are sent to the standard output, so it is possible to use grep and other tools to find particular log messages, for example, lgstool cat /var/log/messages.lgs |grep 192.168.1.1. For further details, see The logstore tool manual page.
|
|
Caution:
For files that are in use by syslog-ng, the last chunk that is open cannot be read. |
The syslog-ng PE application processes log messages into a journal file before writing them to the logstore file. That way logstore files are consistent even if syslog-ng PE crashes unexpectedly, avoiding losing messages. Note that this does not protect against losing messages if the operating system crashes.
A journal file is automatically created for every logstore file that syslog-ng PE opens. A journal file consists of journal blocks that store the log messages. When a journal block fills up with messages, syslog-ng PE writes the entire block into the logstore file and starts to reuse the journal block (one journal block becomes one chunk in the logstore file).
If the messages cannot be written to the logstore file (for example, because the disk becomes inaccessible, or file operations are slow), messages are put to the next journal block (syslog-ng PE uses four blocks by default). When all journal blocks become full, syslog-ng PE will stop processing incoming traffic. syslog-ng PE starts accepting messages to the logstore file again when the first journal block is successfully written to the logstore file. If syslog-ng PE receives a HUP or STOP signal, or no new message arrives into the logstore for the period set in the time-reap() parameter, it writes every journal block to the logstore.
When syslog-ng PE is restarted, it automatically processes the journal files to the logstore files, unless a particular logstore file is not part of configuration of syslog-ng PE. Such orphaned journal files can be processed with the lgstool recover command. For details on processing orphaned journal files, see The logstore tool manual page.
|
|
Caution:
-
If a particular logstore destination receives messages at a constant but very low message rate (for example, a 100-byte message every 30 seconds), messages do not get written to the logstore file for a long time, because the journal block does not get full, and messages are more frequent than the time-reap() time. This becomes a problem when using logrotate to rotate the logstore files, because log messages will not be in the files they are expected. To avoid this situation, either use time-based macros in the filenames of the logstore files, or send a HUP signal to syslog-ng PE right before rotating the logstore files.
-
When every block of a journal becomes full and syslog-ng PE stops processing incoming traffic, it will not read new messages at all until a block is successfully written to the related logstore file. This is in contrast with flow-control, where only messages from the source related to the particular destination are not processed.
-
The messages in the journal file are in plain-text format. They are neither encrypted nor compressed. The journal file has the same permission as the logstore: by default, root privileges are required to access them. Make sure you consider this if you change the permissions of the journal file (owner, group, perm) in the syslog-ng PE configuration file. |
NOTE: Journal files are located in the same folder as the logstore file. The name of the journal file is the same as the logstore file with .jor suffix added. For example, the journal file for messages.lgs is messages.lgs.jor.
The syslog-ng PE application uses a separate journal file for every logstore file. Every journal file is processed by a separate thread. The journal files are mapped into the memory. The journal of an individual logstore file uses up to journal-block-size()*journal-block-count() memory address, which is 4MB by default. However, if you have several logstore files open in parallel (for example, you are collecting log messages from 500 hosts and storing them in separate files for every host, and the hosts are continuously sending messages), the memory requirements for journaling rise quickly (to approximately 2GB for the 500 hosts). To limit the memory use of journals, adjust the logstore-journal-shmem-threshold() global option (by default, it is 512MB).
If the memory required for the journal files exceeds the logstore-journal-shmem-threshold() limit, syslog-ng PE will store only a single journal block of every journal file in the memory, and — if more blocks are needed for a journal — store the additional blocks on the hard disk. Opening new logstore files means allocating memory for one new journal block for every new file. In extreme situations involving large traffic, this can lead to syslog-ng PE consuming the entire memory of the system. Adjust the journal-block-size() and your file-naming conventions as needed to avoid such situations. For details on logstore journals, see Journal files.
|
|
Caution:
If you have a large amount of open logstore files in parrallel (for example, you are using the ${HOST} or ${PROGRAM} macros in your filenames) consider lowering the journal-block-size() to avoid syslog-ng PE consuming the entire memory of the system. |
Example: Calculating memory usage of logstore journals
If you are using the default settings (4 journal blocks for every logstore journal, one block is 1MB, logstore-journal-shmem-threshold() is 512MB), this means that syslog-ng PE will allocate 4MB memory for every open logstore file, up to 512MB if you have 128 open logstore files. Opening a new logstore file would require 4 more megabytes of memory for journaling, bringing the total required memory to 516MB, which is above the logstore-journal-shmem-threshold(). In this case, syslog-ng PE switches to storing only a single journal block in the memory, lowering the memory requirements of journaling to 129MB. However, opening more and more logstore files will require more and more memory, and this is not limited, except when syslog-ng PE reaches the maximum number of files that can be open (as set in the --fd-limit command-line option).
The logstore driver stores log messages in binary files that can be encrypted, compressed, checked for integrity, and timestamped by an external Timestamping Authority (TSA). Otherwise, it is very similar to the file() destination.
|
|
Caution:
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 The syslog-ng manual page manual page. For setting the ulimit parameter of the host, see the documentation of your operating system. |
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 PE using the syslog-ng-ctl reload command, or use another method to send a SIGHUP to syslog-ng PE.
The logstore() has a single required parameter that specifies the filename that stores the log messages.
Declaration
logstore(filename options());
The logstore() destination has the following options:
cipher()
| Type: |
string |
| Default: |
aes-128-cbc |
Description: Set the cipher method used to encrypt the logstore. The following cipher methods are available: aes-128-cbc, aes-128-cfb, aes-128-cfb1, aes-128-cfb8, aes-128-ecb, aes-128-ofb , aes-192-cbc, aes-192-cfb, aes-192-cfb1, aes-192-cfb8, aes-192-ecb, aes-192-ofb , aes-256-cbc, aes-256-cfb, aes-256-cfb1, aes-256-cfb8, aes-256-ecb, aes-256-ofb , aes128 , aes192 , aes256, bf , bf-cbc , bf-cfb, bf-ecb , bf-ofb , blowfish, cast , cast-cbc , cast5-cbc , cast5-cfb, cast5-ecb, cast5-ofb , des, des-cbc, des-cfb , des-cfb1 , des-cfb8 , des-ecb , des-ede, des-ede-cbc, des-ede-cfb , des-ede-ofb, des-ede3 , des-ede3-cbc, des-ede3-cfb, des-ede3-ofb, des-ofb , des3 , desx , desx-cbc, rc2, rc2-40-cbc , rc2-64-cbc, rc2-cbc, rc2-cfb, rc2-ecb , rc2-ofb, rc4, and rc4-40. By default, syslog-ng PE uses the aes-128-cbc method.
Note that the size of the digest hash must be equal to or larger than the key size of the cipher method. For example, to use the aes-256-cbc cipher method, the digest method must be at least SHA-256.
chunk-size()
| Type: |
number (kilobytes) |
| Default: |
128 |
Description: This option is obsolete. Use the journal-block-size() option instead.
Size of a logstore chunk in kilobytes. Note that this size refers to the compressed size of the chunk. Also, the gzip library used for compressing the messages has a 32k long buffer, so messages may not appear in the actual logfile until this buffer is not filled. Logstore chunks are closed when they reach the specified size, or when the time limit set in chunk-time() expires.
chunk-time()
| Type: |
number (seconds) |
| Default: |
5 |
Description: This option is obsolete.
Time limit in seconds: syslog-ng PE closes the chunk if no new messages arrive until the time limit expires. Logstore chunks are closed when the time limit expires, or when they reach the size specified in the chunk-size() parameter. If the time limit set in the time-reap() parameter expires, the entire file is closed.
compress()
| Type: |
number (between 0-9) |
| Default: |
3 |
Description: Compression level. 0 means uncompressed files, while 1-9 is the compression level used by gzip (9 means the highest but slowest compression, 3 is usually a good compromise).
create-dirs()
| Type: |
yes or no |
| Default: |
no |
Description: Enable creating non-existing directories when creating files or socket files.
digest()
| Type: |
string |
| Default: |
SHA1 |
Description: Set the digest method to use. The following digest methods are available: MD4, MD5, SHA0 (SHA), SHA1, RIPEMD160, SHA224, SHA256, SHA384, and SHA512. By default, syslog-ng PE uses the SHA1 method.
Note that the size of the digest hash must be equal to or larger than the key size of the cipher method. For example, to use the aes-256-cbc cipher method, the digest method must be at least SHA256.
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().
Starting with version 7.0.9, the default value of this option is -1, so syslog-ng PE does not change the ownership, unless explicitly configured to do so.
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).
encrypt-certificate()
| Type: |
filename |
| Default: |
none |
Description: Name of a file, that contains an X.509 certificate (and the public key) in PEM format. The syslog-ng PE application uses this certificate to encrypt the logstore files which can be decrypted using the private key of the certificate.
flags()
| Type: |
serialized |
| Default: |
empty set |
Description: Flags influence the behavior of the destination driver.
frac-digits()
Description: The syslog-ng PE 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: The syslog-ng PE application can add the fractions to non-ISO8601 timestamps as well.
NOTE: As syslog-ng PE is precise up to the microsecond, when the frac-digits() option is set to a value higher than 6, syslog-ng PE will truncate the fraction seconds in the timestamps after 6 digits.
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().
log-fifo-size()
| Type: |
number |
| Default: |
Use global setting. |
Description: The number of messages that the output queue can store.
journal-block-count()
| Type: |
number (1-255) |
| Default: |
4 |
Description: The number of blocks in the journal file. If set to 0, syslog-ng will set it to the default value (4). The maximal value is 255. If journal-block-count() is set higher than 255, syslog-ng will use the maximum value.
NOTE: By default, journal files are mapped into the memory of the host. To influence the amount of memory addresses used by journal files, see the logstore-journal-shmem-threshold() global option.
Example: Setting journal block number and size
The following example sets the size of a journal block to 512KB and increases the number of blocks to 5.
destination d_logstore {
logstore("/var/log/messages-logstore.lgs"
encrypt-certificate ("/opt/syslog-ng/etc/syslog-ng/keys/public-server-certificate.pem")
journal-block-size(524288)
journal-block-count(5)
);
};
journal-block-size()
| Type: |
number (bytes) |
| Default: |
1048576 |
Description: The size of blocks (in bytes) in the journal file. The size of the block must be a multiple of the page size: if not, syslog-ng PE automatically increases it to the next multiple of the page size. The maximum size of a journal block is 32MB, the minimum size is 256KB. If the value specified as journal-block-size() is lower than minimum size or higher than the maximum size, syslog-ng PE will use the minimum or maximum size, respectively.
NOTE: In addition, consider the following:
-
At least one journal block for every logstore file open is mapped into the memory. For details on logstore journals, see Journal files.
-
The size of the journal block is not equal with the size of logstore chunks, because the records in the logstore file can be encrypted or compressed.
Example: Setting journal block number and size
The following example sets the size of a journal block to 512KB and increases the number of blocks to 5.
destination d_logstore {
logstore("/var/log/messages-logstore.lgs"
encrypt-certificate ("/opt/syslog-ng/etc/syslog-ng/keys/public-server-certificate.pem")
journal-block-size(524288)
journal-block-count(5)
);
};
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().
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().
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 Macros of syslog-ng PE. 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()
Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using the disk-buffer option as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.
timestamp-freq()
| Type: |
number (seconds) |
| Default: |
Use global setting. |
Description: The minimum time (in seconds) that should expire between two timestamping requests. When syslog-ng closes a chunk, it checks how much time has expired since the last timestamping request: if it is higher than the value set in the timestamp-freq() parameter, it requests a new timestamp from the authority set in the timestamp-url() parameter.
By default, timestamping is disabled: the timestamp-freq() global option is set to 0. To enable timestamping, set it to a positive value.
timestamp-policy()
Description: If the Timestamping Server has timestamping policies configured, specify the OID of the policy to use with this parameter. syslog-ng PE will include this ID in the timestamping requests sent to the TSA. This option is available in syslog-ng PE 3.1 and later.
timestamp-url()
| Type: |
string |
| Default: |
Use global setting. |
Description: The URL of the Timestamping Authority used to request timestamps to sign logstore chunks. Note that syslog-ng PE currently supports only Timestamping Authorities that conform to RFC3161 Internet X.509 Public Key Infrastructure Time-Stamp Protocol, other protocols like Microsoft Authenticode Timestamping are not supported.
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 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 ts-format().
