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 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 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:
maverick.log.connection.level=DEBUG
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.
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 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:
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 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:
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 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
maverick.log.connection.myapp.<key>
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 start logging manually you can do so, by calling the startLogging method on the Connection object.
con.startLogging(Level.TRACE);
