Documentation

How to enable per-connection logging

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 has a problem.

Like the standard logging mechanism, per-connection logging can be controlled through the logging.properties 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, which defaults to NONE, so there is no per-connection logging. To enable per-connection logging for all connections, you would configure the properties with:

maverick.log.connection.level=DEBUG

When per-connection logging is enabled, without any further configuration of the logging properties, you will see log files created in the current working directory for each connection 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.

Options

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 some 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 several options available to control what connections are 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 established connections, whether 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 instances, the “client” manager and the “server” manager. 

When running both client and server operations within the same JVM, you may want only to enable per-connection logging for one type of connection. This can be done by 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:

maverick.log.connection.client.level=DEBUG

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

maverick.log.connection.server.level=DEBUG

This applies to all available property keys; 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:

maverick.log.connection.server.filenameFormat=${timestamp}__${uuid}__server.log

Or setting different logging levels for each ConnectionManager:

maverick.log.connection.client.level=DEBUG
maverick.log.connection.server.level=TRACE

Custom ConnectionManager

If you have configured your 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, you can override any of the settings using your ConnectionManager’s name.

When you created the ConnectionManager, you provided a name; 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.

maverick.log.connection.myapp.<key>Code language: CSS (css)

Therefore, to set the default level, you would use

maverick.log.connection.myapp.level=DEBUG

Manually Starting Connection Logging

If you have other criteria or want to log manually, call the startLogging method on the Connection object.

con.startLogging(Level.TRACE);Code language: CSS (css)