You are reading the reference manual of an upcoming release. Read the current manual »
ContainerSSH comes with configurable logging facilities. You can configure the following options:
- The minimum log level to filter unnecessary log messages
- The log format
- The log destination
Configuring the minimum log level¶
You can configure the minimum log level by adding the following to your configuration:
You can configure the log level on a per-user basis using the configuration server.
The supported levels are in accordance with the Syslog standard:
Configuring the log format¶
ContainerSSH can log in both text and newline-delimited JSON (
ljson) format. You can change the format with the following setting:
The JSON log format¶
The LJSON format outputs a JSON-formatted string per log message. For file and stdout these JSON messages are separated by a newline from each other.
When writing to the
file destinations the format is the following:
"timestamp":"Timestamp in RFC3339 format",
"level":"the log level",
"message":"the message (optional)",
"the detail object if any (optional)"
When writing to syslog the format is the same, but does not contain the
level fields as they are redundant. The error codes are documented in the troubleshooting section.
The text log format¶
When writing to the
file destinations the text log format has the following fields delimited by a tab (
TIMESTAMP will be formatted according to RFC3339, while the
LEVEL will be the text-representation of the log level. The
MESSAGE field will contain the text representation of the message.
The text message is not intended for machine processing and may change across versions. If you intend to do machine processing please use the
details field from the
Setting the output¶
The output configuration of ContainerSSH is the following:
<other destination options>
Writing to the stdout¶
The stdout destination is the simplest: it will write error messages to the standard output of ContainerSSH. This is the default logging method.
Writing to a file¶
You can write to a specific file using the following options:
ContainerSSH will write to the specified file in the specified format.
ContainerSSH supports log rotation. You can trigger a log rotation by sending a HUP (hangup) signal to ContainerSSH.
Writing to syslog¶
ContainerSSH supports writing to syslog via a Unix socket or UDP. TCP syslog is not supported due to the complexity of maintaining a stable connection and buffering messages between disconnects.
Syslog can be configured as follows:
# Change to IP and port for UDP
# See below for supported names
# Program name to log as
# Log PID with program name
The following facilities are supported:
ContainerSSH can log very long messages with lots of details. Please make sure to bump your maximum line length to at least 4096 characters in your Syslog server to avoid message truncation. (rsyslog and syslog-ng have higher default values, so you don't need to change the configuration if you are using these syslog servers.)