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 the section called “cipher()” and the section called “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 the section called “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).
Starting with syslog-ng Premium Edition 3.2, syslog-ng PE 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 which 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 unaccessible, 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 section called “The recover command”.
|
|
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 ~2GB for the 500 hosts). To limit the memory use of journals, adjust the logstore-journal-shmem-threshold() global option (by default, it is 512 MB).
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 the section called “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 7.16. 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).
logstore() destination options
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 syslog-ng(8) 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:
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. This option is available in syslog-ng PE 3.1 and later.
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.
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.
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).
Description: Enable creating non-existing directories.
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. This option is available in syslog-ng PE 3.1 and later.
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().
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().
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).
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.
Description: Flags influence the behavior of the destination driver.
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.
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().
Description: The number of messages that the output queue can store.
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 7.17. 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));
};
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:
-
At least one journal block for every logstore file open is mapped into the memory. For details on logstore journals, see the section called “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 7.18. 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));
};
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().
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().
Description: Specifies a template defining the logformat to be used in the destination. Macros are described in the section called “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.
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.
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.
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.
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.
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 the section called “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.
