View Source

Affected version(s): all

Problem

Normal EAS logs haven't enough information to debug a problem.

Solution

The usmsession Tool allows OX admins to enable/disable EAS Debug Logging and report if EAS Debug Logging is enabled for given USM-sessions. For all matching USM-Sessions the tool will report if EAS Debug Logging is enabled. Calling the Tool with -e <keyword> <session-filter> will activate EAS Debug Logging for all EAS sessions matching the filter specified by <session-filter>, the text specified as <keyword> will be logged with every EAS Debug Log message to the open-xchange.log Logfile so that it can be easily searched for. Invoking the Tool with -d will deactivate EAS Debug Logging for all matching sessions.

EAS Debug Logging can only be activated for USM/EAS sessions the tool will report a warning if -d or -e is given and any non-EAS-sessions are specified.

Usage

usage: usmsessions [-h | -X]
usmsessions [-e <keyword> | -r | -d] [-q | -v] [-l <login>] [-p <port>] [-s <password>] (<Session-Filter>|<Request-Parameters>)+

Session-filter: [<ContextID>]:[<UserID>]:[<Session-ID>]:[<Protocol>]:[<DeviceID>]
Protocol: (EAS|JSON)
Request-Parameters: <URL> or <URL-Parameters>

-e,--enableEASDebugLog <keyword> Enable EAS debug logging with the given keyword in the log messages (only for EAS sessions)
-r,--reportEASDebugLog Report if (and under which keyword) debug logging is enabled (only for EAS sessions)
-d,--disableEASDebugLog Disable debug logging (only for EAS sessions)
-q,--quiet Quiet mode: Only print errors/warnings. If -r is specified, print only EAS debug logging keyword (or empty line if EAS debug logging is disabled)
-v,--verbose Verbose output: Report all persistent fields for matching USM sessions
-h,--help Prints this help text
-X,--examples Prints this help text with usage examples
-l,--login <login> The optional JMX login (if JMX has authentication enabled)
-p,--port <port> The optional JMX port (default:9999)
-s,--password <password> The optional JMX password (if JMX has authentication enabled)

Options -d,-e,-r are mutually exclusive, as are options -q,-v.

Arguments may be given as Session-filter or Request-URL-parameters.

Currently available protocols are EAS (Active Sync) and JSON (OX Connector for Outlook). PLEASE NOTE: Enabling the EAS debug log for specific sessions is only possible for EAS sessions. If enabled, it logs communication data at level INFO. It does not enable logging of debug log messages at a higher level.

Examples

While usmsession can also be used to determine CID, OX ID from USM-Session ID and apache access log entries and vice-versa as well as enabling/disabling logging for JSON (OX Connector for Outlook) the following examples only cover general usage for EAS sessions.

Enabling system- and context wide EAS Debug logging for a specific user:

root@eas-test~# usmsessions -e EAS-UID7 :7::EAS:
CID: 1, ID: 7, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 9

this enables EAS logging matching every user with UID 7 in any context, with any Session ID using any Device. The keyword to search for in the logs is EAS-UID7 in this case. The log entry inside of the open-xchange.log Logfile looks like this then:

2015-03-06T15:11:39,643+0100 INFO [OXWorker-0000028] com.openexchange.usm.eas.servlet.DebugLogWriter.log(DebugLogWriter.java:31)
EAS-UID7 c9609b86-8d02-4087-a199-36118ff7887d --- Outgoing result: application/vnd.ms-sync.wbxml ---
<?xml version='1.0' encoding='utf-8' ?>
...
followed by the complete EAS payload embedded inside of the complete XML structure of the EAS data. This means that the whole User content (Mail, Appointment, etc.) will be logged - please keep this in mind when operating with EAS Debug Logs.

Enabling EAS Debug logging for a specific user inside of a specific Context:

root@eas-test~# usmsessions -e EAS-CID1UID6 1:6::EAS:
CID: 1, ID: 6, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 7

this enables EAS Debug logging matching user with UID 6 inside of Context 1, with any Session ID using any Device. The keyword to search for in the logs is EAS-CID1UID6 in this case.

You can also search for a specific device identified by the Device ID if this is know. Additionally you may combine this with all other matching Rules:

Enabling EAS Debug logging for a specific device:

root@eas-test~# usmsessions -e EAS-MyiPad :::EAS:1CQ33J21ABCDEN3D7MO456EP18S
CID: 1, ID: 6, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 7
CID: 1, ID: 7, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 9

this enables system- and context wide EAS Debug logging for all EAS connections to/from Device matching Device ID 1CQ33J21ABCDEN3D7MO456EP18S. The keyword to search for in the logs is MyiPad in this case.

the same for a specific user using this device in a specific context:

Enabling EAS Debug logging for a specific device:

root@eas-test~# usmsessions -e EAS-MyiPadCID1UID7 1:7::EAS:1CQ33J21ABCDEN3D7MO456EP18S
CID: 1, ID: 7, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 9

The keyword to search for in the logs is EAS-MyiPadCID1UID7 in this case.

Reporting if an EAS Debug Logging is active for a specific filter:
if you need to check if an EAS Debug Logging is currently active on your system or not (and under which keyword it will be logged) you may invoke the usmsession command using the same parameters excluding the <keyword>:

root@eas-test~# usmsessions -r 1:7::EAS:1CQ33J21ABCDEN3D7MO456EP18S
CID: 1, ID: 7, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 9
EAS Debug Logging is activated with keyword "EAS-MyiPadCID1UID7"

the same parameters but using option -d now are used to remove an EAS Debug Logging Filter being logged:

Removing an EAS Debug Logging filter from being logged:

root@eas-test~# usmsessions -d 1:7::EAS:1CQ33J21ABCDEN3D7MO456EP18S
CID: 1, ID: 7, Protocol: EAS, Device: 1CQ33J21ABCDEN3D7MO456EP18S, usmSessionId: 9

Please note that the Logging filters will remain active until you remove them with -d or restart OX.

Problem

Solution

Usage

Examples

Related articles