How to enable per-connection logging

Lee Painter

The Maverick Synergy Java SSH API supports a mode of logging that enables you to log on an individual connection basis. This can be useful in support situations where only a specific device is having a problem.

Like the standard logging mechanism, per-connection logging can be controlled through the file, or System properties. Using the properties file is the most convenient option as you can change this at runtime to reconfigure logging whilst an application is running.


Enable Per-Connection Logging

The default level of connection logging is controlled with the maverick.log.connection.level option and this defaults to NONE so there is no per-connection logging by default. To enable per-connection logging for all connections you would configure the properties with:


When per-connection logging is enabled, without any further configuration of the logging properties you will start to see log files created in the current working directory for each connection that is accepted or established by the API. The filename for each file is in the format <timestamp>__<uuid>.log where timestamp is the date and time that the initial connection was made, and the uuid is the unique identifier of the connection.


The following options are available for you to configure per-connection log files.

maverick.log.connection.level NONE The default level of logging for the per-connection logger
maverick.log.connection.filenameFormat ${timestamp}__${uuid}.log The filename format for per-connection log files
maverick.log.connection.maxFiles  10 The maximum number of rollover files
maverick.log.connection.maxSize  20MB The maximum size of each rollover file
maverick.log.connection.timestampPattern yyyy-MM-dd-HH-mm-ss-SSS The format of the timestamp generated when ${timestamp} is used

Changing the Filename Format

There are a number of replacement tokens you can use in the filename format.

${timestamp} The date and time that the connection was established
${uuid} The unique identifier of the connection
${remotePort} The remote port of the connection
${remoteAddr} The remote IP address of the connection
${localPort} The local port of the connection
${localAddr} The local IP address of the connection
${ident} The remote identification value of the remote side
${user} The name of the user


Selective Logging

There are also a number of options available to control what connections are actually logged. This enables you to filter to ensure that only the connections you need logging have logging enabled.

maverick.log.connection.remoteAddr A comma-separated list of IP addresses to match against the remote IP address of the connection
maverick.log.connection.remotePort A comma-separated list of port numbers to match against the remote port of the connection
maverick.log.connection.localAddr A comma-separated list of IP addresses to match against the local IP address of the connection
maverick.log.connection.localPort A comma-separated list of port numbers to match against the local port of the connection
maverick.log.connection.ident A comma-separated list of whole or partial matches to the remote identification string e.g. "OpenSSH_7.9" or "OpenSSH"
maverick.log.connection.user A comma-separated list of usernames to log. Please note, logs will only be enabled for users once the username has been declared at the start of authentication.



Configure Specific Connection Manager

So far all the settings have applied globally to all the connections that are established, regardless of whether they are client or server connections. By default, when a connection is created it is put on the default ConnectionManager for the API. There are two default ConnectionManager's, the "client" manager and the "server" manager. 

In the case where you are running both client and server operations within the same JVM you may want to only enable per-connection logging for one type of connection. This can easily be done by simply modifying the logging property key to indicate which ConnectionManager you want to configure.

For example, to enable per-connection logging for all client connections and keep the default of no logging for server connections you would use the following property:


Similarly, if you want to enable server but not client logging use:


This applies to all of the available property keys, simply place "client" or "server" before the final element of the key name.

Here are some more examples:

To change the filename format for server connection logs:


Or setting different logging levels for each ConnectionManager:



Custom ConnectionManager

If you have configured your own ConnectionManager instance when creating SshContext, either on the SshServerContext or SshClientContext, you can also configure its logging setup through the properties file. The global settings will apply as defaults, however like the "client" and "server" ConnectionManager's you can also override any of the settings using your own ConnectionManager's name.

When you created the ConnectionManager you provided a name, simply use the name in place of "client" or "server".

For example, you created a ConnectionManager with the name "myapp". You would set properties using the format


Therefore, to set the default level you would use



Manually Starting Connection Logging

If you have other criteria or want to start logging manually you can do so, by calling the startLogging method on the Connection object.