﷽
This document gives you details on configuring residue
Residue is fully configurable to support various features and for security. Configuration is always in JSON format.
You can use Server Config Tool to generate configurations for your server
- admin_port
- connect_port
- logging_port
- default_key_size
- server_key
- server_rsa_private_key
- server_rsa_public_key
- server_rsa_secret
- enable_cli
- enable_dynamic_buffer
- allow_insecure_connection
- allow_unmanaged_loggers
- allow_unmanaged_clients
- immediate_flush
- requires_timestamp
- compression
- file_mode
- allow_bulk_log_request
- max_items_in_bulk
- timestamp_validity
- client_age
- non_acknowledged_client_age
- client_integrity_task_interval
- dispatch_delay
- archived_log_directory
- archived_log_filename
- archived_log_compressed_filename
- managed_clients
- managed_clients_endpoint
- managed_loggers
- managed_loggers_endpoint
- extensions
- loggers_blacklist
- Comments
- Sample
[Integer] Port that admin server listens to. All the admin requests are sent to this port. These requests must be encrypted using server_key.
Default: 8776
[Integer] Port that connection server listens to. All the connection requests are sent to this port and handled accordingly. This is the port that all the clients libraries initially connect to.
Default: 8777
[Integer] Port that logging server listens to. This is where all the log requests are sent.
Default: 8778
[Integer] Default symmetric key size (128, 192 or 256) for clients that do not specify key size. See key_size
Default: 256
[String] A 256-bit server key that is used for admin services. See admin_port
Default: Randomly generated and residue outputs it in start-up
[Optional, String] RSA private key (PEM format file path). You can use $RESIDUE_HOME environment variable in this file path. If provided, it is used to read initial requests for extra security.
[String] Corresponding public key for server_rsa_private_key. You can use $RESIDUE_HOME environment variable in this file path.
[String] If private key is encrypted, this is the secret (passphrase) to decrypt it. THIS SHOULD BE HEX ENCODED.
[Boolean] Whether CLI is enabled on server or not. See CLI_COMMANDS.md for possible input commands.
Default: true
[Boolean] Dynamic buffer is a feature that allows failed logs (logs that were failed to be written to file) to be clogged up in an internal buffer. Once logs can be written to the file all the logs from this dynamic buffer will be flushed to the file so no logs are lost.
You can turn this feature on or off with this flag.
NOTE This is an experimental feature introduced in v2.1.1 and should not be used in production at this point.
Default: false
[Boolean] Specifies whether plain connections to the server are allowed or not. Either this should be true or server key pair must be provided (or both)
Default: true
[Boolean] Specifies whether loggers other than the ones in managed_loggers list are allowed or ignored / rejected.
Default: true
[Boolean] Specifies whether clients other than the ones in managed_clients list are allowed or ignored / rejected.
Default: true
[Boolean] Specifies whether to flush logger immediately after writing to it or not. Performance of the server is not affected with turning it on as we use separate thread for logging.
Default: true
[Boolean] Specifies whether timestamp is absolutely required or not. Timestamp is _t value for each incoming requests.
This does not affect admin requests, timestamps for admin requests is always required.
Default: true
[Boolean] Specifies whether compression is enabled or not.
Default: true
[Integer] Default file mode for the log files
[Boolean] Specifies whether clients can send bulk log requests or not.
See max_items_in_bulk and compression
Default: true
[Integer] Maximum number of bulk items allowed.
If client sends more requests than this all the extra requests are ignored by server (with verbose warning). User is not informed about this as we handle log requests asynchronously.
Default: 5
You may be interested in compression
[Integer] Integer value in seconds that specifies validity of timestamp _t in request
Minimum: 30
Default: 120
[Integer] Value (in seconds) that defines the age of a client. After this age, client is considered dead. Clients library can TOUCH request just before (subject to TOUCH_THRESHOLD value in the library) dying to bring it back to life provided it's not already dead. After client is dead, it needs to reconnect and obtain a new key.
Default: 259200 (3 days)
Minimum: 120
Forever: 0 (not recommended)
[Integer] Value (in seconds) that defines the age of a client that is not yet acknowledged by client library.
Note: You cannot TOUCH a non-acknowledged client.
Minimum: 120
Default: 300 (5 minutes)
Cannot set it to forever
[Integer] Value that should be >= client_age or non_acknowledged_client_age (whichever is lower).
This is a task that ensures integrity of the clients to remove dead clients that are unusable
Default: 300 or min(client_age, non_acknowledged_client_age) [whichever is higher]
Minimum: 300
[Integer] Value that defines the delay (in milliseconds) between two log message dispatch.
Note Increasing this value is going to slow down your server (for obvious reasons, i.e, it's a delay).
Default: 1 (recommended)
Maximum: 500
Turn off delay: 0 (not recommended)
[String] Default destination for archived logs files
Default: It must be provided by the user
[String] Default filename for archived log files.
Default: It must be provided by the user
[String] Filename for compressed archived log files. It should not contain / or \ characters.
Default: It must be provided by the user
[Array] Object of client that are managed to the server. These clients will have allocated RSA public key that will be used to transfer the symmetric key.
[String] The client ID (should be alpha-numeric and can include -, _, @, . and # symbols)
[String] Path to RSA public key file for associated client ID. This key must be present and readable at the time of starting the server.
You can use $RESIDUE_HOME environment variable in this file path.
[Optional, Integer] Integer value of 128, 192 or 256 to specify key size for this client.
This is useful when client libraries connecting cannot handle bigger sizes, e.g, java clients without JCE Policy Files.
See default_key_size
[Optional, Array] Object of logger IDs that must be present in managed_loggers array.
This is to map the client with multiple loggers. Remember, client is not validated against the logger using this array, this is only for extra information.
[String] Default logger for the client. This is useful when logging using unmanaged logger but connected as managed client. The configurations from this logger is used.
Default: default
[String] Linux / macOS user. All the log files associated to the corresponding loggers will belong to this user with RW-R----- permissions (subject to file_mode config)
Default: Current process user
[String] This is URL where we can pull more managed clients from. The endpoint should return JSON with object managed_clients, e.g,
<?php
header('Content-Type: application/json');
$list = array(
"managed_loggers" => array(
array(
"logger_id" => "another",
"configuration_file" => "samples/configurations/blah.conf"
),
),
);
echo json_encode($list);
Call this file localConfig.php and run it as server php -S localhost:8000
Endpoint URL is http://localhost:8000/localConfig.php
You need to make sure that configuration_file exists on the server.
[Array] Object of loggers that are managed to the server.
[String] The logger ID
[String] Path to Easylogging++ configuration file. You can use $RESIDUE_HOME environment variable in this file path. When the new logger is registered, it's configured using this configuration.
[String] One of [never, hourly, six_hours, twelve_hours, daily, weekly, monthly, yearly] to specify rotation frequency for corresponding log files. This is rotated regardless of file size.
Default: never
[String] Linux / mac user assigned to managed logger. All the log files associated to the corresponding logger will belong to this user with RW-R----- permissions (subject to file_mode)
Default: Current process user
[String] Filename for rotated or archived log file
[String] Filename for rotated or archived log file in compressed form (ideally ending with .tar.gz)
See archived_log_compressed_filename
[String] Overrides default archived_log_directory to logger specific directory.
[String] This is URL same as managed_clients_endpoint with JSON object containing same properties as managed_loggers
[Array] Contains various types of extensions. You can specify each type of extension's array shared library modules.
Extensions API documentation is available here
NOTE You will need libresidue-extension in your LD_LIBRARY_PATH
[Array] String where each string is logger ID. Whenever request using these loggers are received, they are ignored without notifying the user.
Because Residue configuration is in JSON format, comments are not supported as there should be no comment in JSON file. With that said there are ways to have comments around it.
- You can have a seperate "object" for comment e.g,
...
"comment", "following backup directory will be in original logging directory",
"archived_log_directory": "%original/backups/%logger/",
"comment", "another comment",
"archived_log_filename": "%hour-%min-%day-%month-%year.log",
"comment", "another comment",
"archived_log_compressed_filename": "%hour-%min-%day-%month-%year.tar.gz",
"managed_clients": [
...Please note, this is not preferred way as parsing may get slower with increasing comments.
- You can have comment using
//or/* */in the file and then before you pass it on to residue, run it through jsMin. e.g, for filetest.json
...
// following backup directory will be in original logging directory
"archived_log_directory": "%original/backups/%logger/",
// another comment
"archived_log_filename": "%hour-%min-%day-%month-%year.log",
// another comment
"archived_log_compressed_filename": "%hour-%min-%day-%month-%year.tar.gz",
"managed_clients": [
...cat test.json | jsmin > test-nocomments.json && residue test-nocomments.json
This is preferred way as it will only pass on what is really needed.
Please refer to sample configuration file for understanding it better.