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.
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=DEBUGWhen 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.
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 |
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 |
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. |
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=DEBUGSimilarly, if you want to enable server but not client logging, use:
maverick.log.connection.server.level=DEBUGThis 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.logOr setting different logging levels for each ConnectionManager:
maverick.log.connection.client.level=DEBUG
maverick.log.connection.server.level=TRACEIf 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>Therefore, to set the default level, you would use
maverick.log.connection.myapp.level=DEBUGIf you have other criteria or want to log manually, call the startLogging method on the Connection object.
con.startLogging(Level.TRACE);