OXReportClient

Revision as of 10:25, 19 February 2016 by Thomas.siedentopf (talk | contribs) (Explanation of the appsuite report console output)

Introduction

  • For customers who are using OX App Suite please click here

Beginning with the release of Open-Xchange Server version 6.18, generating a report every month is mandatory in order to have access to the maintenance updates available in the updates directory on software.open-xchange.com.

You have been blocked already?

Don't panic, you can still access http://software.open-xchange.com/OX6/stable, because that is open for everyone. So install the Report Client from stable instead of updates and once you're done, update to the latest version.

The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.

You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)


Install on OX v6.22.x

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/backend/DebianBuster/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/backend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-report-client

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/backend/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/backend/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-report-client


Configuration

A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our installation guide documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.

If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:

$ vim /opt/open-xchange/etc/common/licensekeys.properties 

or on 6.22 or newer

$ vim /opt/open-xchange/etc/licensekeys.properties 
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE

If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:

$ vim /opt/open-xchange/etc/groupware/reportclient.properties

or on 6.22 or newer

$ vim /opt/open-xchange/etc/reportclient.properties

After editing this file accordingly to your proxy needs, try to start the report client again.

Using the Report tool

Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange

activation.open-xchange.com:443

Report kinds

In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination.

Display data usage report

$ /opt/open-xchange/sbin/report -d

If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:

Send data usage report

$ /opt/open-xchange/sbin/report -s

If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.

Available options

$ /opt/open-xchange/sbin/report -h

lists all available options:

Usage: report
-h,--help                                         Prints a help text          
   --environment                                  Show info about commandline environment
   --nonl                                         Remove all newlines (\n) from output
   --responsetimeout <responsetimeout>            response timeout in seconds for reading response from
                                                   the backend (default 0s; infinite)
-H,--host <host>                                  specifies the host          
-T,--timeout <timeout>                            timeout (in s) to conntect to the backend (default 15s)
-J,--jmxauthuser <jmxauthuser>                    jmx username (when jmx authentication enabled)
-P,--jmxauthpassword <jmxauthpassword>            jmx password (when jmx authentication enabled)
-s,--sendonly                                     Send report without displaying it (Disables default)
-d,--displayonly                                  Display report without sending it (Disables default)
-c,--csv                                          Show output as CSV          
-a,--advancedreport                               Run an advanced report
-f,--savereport                                   Save the report as JSON String instead of sending it
-b,--showaccesscombination <showaccesscombination>  Show access combination for bitmask
-e,--run-appsuite-report                          Schedule an appsuite style report
-t,--report-type <report-type>                    The type of the report to run
   --inspect-appsuite-reports                     Prints information about currently running reports
   --cancel-appsuite-reports                      Cancels pending reports     
-g,--get-appsuite-report                          Retrieve the report that was generated
-x,--run-and-deliver-report                       Create a new report and send it immediately
-o,--run-and-deliver-old-report                   Run old report type. Used to have a backward compatibility.

Explanation of the appsuite report console output

 $ /opt/open-xchange/sbin/report -d
 Starting the Open-Xchange report client. Note that the report generation may take a little while.

 f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) 
 UUID: f5f511d663ff462f8f963dfa41bd8cd2
 Type: default
 Total time: 389 milliseconds
 Avg. time per context: 77 milliseconds
 Report was finished: Wed Jul 08 13:42:25 CEST 2015

 ------ report -------
 {
   "macdetail" : {
     "capabilitySets" : [ {
       "total" : 2,
       "capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],
       "quota" : 1073741824,
       "admin" : 0,
       "disabled" : 0
     }, {
       "total" : 11,
       "capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
       "quota" : 1073741824,
       "admin" : 3,
       "disabled" : 0
     }, {
       "total" : 6,
       "capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],
       "quota" : 1073741824,
       "admin" : 2,
       "disabled" : 0
     } ]
   },
   "total" : {
     "guests" : 22,
     "links" : 10,
     "contexts" : 5,
     "users" : 19,
     "report-format" : "appsuite-short"
   },
   "clientlogincountyear" : {
     "appsuite" : "7",
     "olox2" : "0",
     "caldav" : "0",
     "usm-eas" : "0",
     "mobileapp" : "0",
     "ox6" : "9",
     "carddav" : "1"
   },
   "clientlogincount" : {
     "appsuite" : "4",
     "olox2" : "0",
     "caldav" : "0",
     "usm-eas" : "0",
     "mobileapp" : "0",
     "ox6" : "2",
     "carddav" : "1"
   },
   "uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",
   "reportType" : "default",
   "timestamps" : {
     "start" : 1436355744714,
     "stop" : 1436355745103
   },
   "version" : {
     "version" : "7.8.0-Rev0",
     "buildDate" : "develop"
   },
   "configs" : {
     "com.openexchange.mail.adminMailLoginEnabled" : "true"
   }
 }
 ------ end -------

macdetail:

detailed information about existing module access combinations and its usage

total:

accumulated user, guest, link (anonymous share) and context count

clientlogincountyear:

number of client logins for the last year (1 year back from current date)

clientlogincount:

number of client logins for the last month

uuid:

a unique id for the report

reportType:

given name for that report (normally 'default')

timestamps:

timestamps of the start and end time of the report

versions:

version and build date of the server

configs:

server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')

Explanation of the old console output

$ /opt/open-xchange/sbin/report -o -d
Starting the Open-Xchange report client. Note that the report generation may take a little while.

module    version    
admin     6.20.5 Rev1
groupware 6.20.5 Rev1

contexts users guests links
5        19    22     10 

mac       count adm disabled
268435455 6     1   0       
237044501 48    0   0       
5         2     2   0       

key                                         value
com.openexchange.mail.adminMailLoginEnabled true 

usmeas olox2 mobileapp carddav caldav
1      0     0         0       0

usmeasyear olox2year mobileappyear carddavyear caldavyear
4          12        7             11          10        


contexts:

total number of contexts

users:

total number of users

guests:

total number of guests

linkss:

total number of links shared to anonymous users

mac:

decimal value of the module access. For conversion decimal to human readable permission please use report -b as described below

count:

amount of users with this module access

adm:

amount of admin users with this specific module access

disabled:

amount of users that are disabled

key:

key of the configuration property

value:

value of the configuration property

The last rows show the amount of users that did login to Open-Xchange within the last 30 days and the last year using the specified OXtender/service.

If you want to know the access permissions of a specific mac, run e.g.

$  /opt/open-xchange/sbin/report -b 237044501

usmeas:

using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days

olox2:

using OXtender 2 for Microsoft Outlook within the last 30 days

mobileapp:

using Open-Xchange Mobile Web Interface within the last 30 days

carddav/caldav:

using the CalDAV/CardDAV feature within the last 30 days

usmeasyear:

using mobile phone via active sync (OXtender for Business Mobility) within the last year

olox2:

using OXtender 2 for Microsoft Outlook within the last year

mobileapp:

using Open-Xchange Mobile Web Interface within the last year

carddav/caldav:

using the CalDAV/CardDAV feature within the last year

Example: a value of 7 below olox2 means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.

Automatic reports

Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:

$ vim /etc/cron.d/open-xchange_report

0 3 * * 7	open-xchange	/opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1

What will be reported using the send method?

The report client will display and / or transfer the following information:

  1. Version number of the Open-Xchange server package
  2. Version number of the Open-Xchange admin package
  3. Total user count
  4. Total context count
  5. Detailed context information: context age, creation date or date of creation, user count, context id, capability sets
  6. Detailed user information (per context): User access combination flags (which modules have been activated for the users)