KeyReporter

Overview

KeyReporter is run as a service that you configure to automatically run K2's usage and audit reports on a schedule. KeyReporter publishes its archive of completed reports in html format for viewing with any web browser. The archive of KeyReporter saved reports can also be viewed using the admin component, KeyConfigure. When viewed in KeyConfigure, these reports are fully integrated into the administrative interface (e.g. with support for drag & drop etc.) just like reports initiated directly from a KeyConfigure menu command.

The KeyReporter process interacts with the KeyServer process (and its databases) in much the same way as KeyConfigure. But unlike KeyConfigure, the KeyReporter process itself has no user interface - instead, a web browser is used as the front end for defining report templates, specifying scheduled run times, running reports, and accessing the archived the results.

As illustrated in the diagram above, the combination of a Web Browser plus KeyReporter is roughly equivalent to the reporting functionality implemented by KeyConfigure alone. Use your favorite web browser to connect to the KeyReporter web server process- the url is the ip address (or a DNS name) of the computer hosting KeyReporter.

KeyReporter is an optional component included in the K2 toolkit - the same set of "report modules" is used by KeyConfigure to display usage and audit summary reports in its own windows without using a web browser. When the usage and audit databases become large, however, some reports may take a considerable time to complete. Then it will be convenient to instruct KeyReporter (using a web browser) to run these same reports on an overnight schedule - perhaps automated to produce weekly or monthly summaries. Access to KeyReporter's archive of completed reports from either a web browser or KeyConfigure is an additional benefit.

Installation & Configuration

The installers for KeyServer and KeyReporter are designed to let you quickly install both functions on a single host computer. Like KeyConfigure, the KeyReporter process must logon to KeyServer using KeyServer's IP address or DNS name. In KeyConfigure you enter the target address into the logon dialog. KeyReporter has no user interface so the target address for the KeyServer is specified in its configuration file. By default, the target KeyServer address is set to "localhost" which corresponds to the assumption that the KeyServer is hosted on the same computer as KeyReporter.

If there is already a service running on port 80 (e.g. a web server ), either KeyReporter or the other service will have to be reconfigured to use a different port, a different network interface, or a different host.

The "kr.conf" file (an xml file contained in the "KeyReporter Data Folder") specifies KeyReporter's port, the target KeyServer address, plus other configuration parameters. This file can be read as a text file and the <string> values edited as necessary - but be very careful when editing parameter values so that the syntax (tags, punctuation, etc.) is preserved exactly! Comments explain the meaning of various <key> fields.

If KeyReporter is installed on a separate host computer, not the same host as KeyServer, then the default target address, "loopback", for the "server" key must be changed in kr.conf to the actual ip address (or DNS name) of the separate KeyServer host. The url specified in a browser to access KeyReporter will of course have to change accordingly. If KeyReporter is reconfigured to use a non-standard port, then the url must have ":" and the port number appended.

Once you have started KeyReporter (after optionally changing the ip address of the server, or the port which KeyReporter users), you can connect to KeyReporter in a web browser. When you enter the ip address (or DNS name) of the computer hosting KeyReporter into your favorite browser, a login screen will be displayed where you must enter a valid KeyServer account name and password. You can use the "Administrator" account and the corresponding password, "Sassafras" (or your custom password, if the default has been replaced). KeyReporter can publish reports for public "Guest" viewing with no login password required - but this behavior is disabled by default. There is a section below about configuring the Guest account.

The characters    %  &  :  =  /  +  #  ?  @     cannot be processed by KeyReporter's account login process. Therefore, in addition to the usual "printable" character restriction, these characters are forbidden in any account name or password that will be used by KeyReporter.

When the KeyReporter Guest account is enabled, KeyReporter will display the Guest home page at the host address url instead of displaying the login form -the Guest home page has a "Log In" link that will bring up the login form.

Optional Secure Connections (SSL)

By default, KeyReporter is configured to serve pages using non-secure connections to browsers.  While KeyReporter uses JavaScript to protect passwords on the network, the actual report pages are sent in cleartext.  For security-conscious sites, KeyReporter can be configured to use the Secure Sockets Layer (SSL) for all connections to browsers.  This option secures all data transmitted between KeyReporter and browsers that support SSL. When KeyReporter is configured to use SSL, the login process from a browser will no longer require JavaScript so it will be much quicker. Connecting to KeyReporter with SSL also allows the administrator to manage additional configuration options that are not allowed when using standard http.

SSL requires a "public/private key certificate" on the server side of the connection. KeyReporter comes with a "self-signed" certificate for ease of setup, but you should consider replacing this certificate with one that is specific to the KeyReporter host and which has been signed by a well-known Certificate Authority (CA). Note: most browsers will post a caution message when KeyReporter is using the self-signed certificate but the connection will be made silently when using a signed certificate.

To enable SSL connections using the built-in self-signed certificate:

1. Log in to the KeyReporter interface as Administrator.

2. Click "Configuration", on the right side of the main page.

3. In the "Network" section, select the "Listen on standard HTTPS port (443)" radio button.

4. Click "Commit Changes".

Alternatively, you can enable SSL by hand editing the "kr.conf" file:

1. Open the "kr.conf" file (in the KeyReporter Data Folder) with a simple text editor and find the "port" value.  By default, this value is set to 80 (although perhaps you have changed it to a different port).  Add a new entry like this:

	<key>authport</key>
	<string>443</string>

2. Stop and start the KeyReporter process, using the appropriate method for the host OS platform.

The above instructions assume there is not already an HTTP server running on port 443.  If there is, you must either disable this other server or move KeyReporter to a different host where port 443 is available.

After enabling secure connections, connect to KeyReporter using the URL "https://hostname/" where hostname is replaced with the host name or IP address of the computer running KeyReporter (include the ":portnumber" as suffix to the hostname if you are using something other than the standard SSL port 443).  If asked when connecting, you should allow the browser to use the certificate. You will now see KeyReporter's Home page or Login page as usual, and the browser will give an indication that the connection is secure. Note: while using an SSL connection, the Configuration screen lets you configure several "advanced" settings - this includes the ability to point KeyReporter to exported data (using a DSN for the target database server) instead of using the standard KeyServer target. See the KeyConfigure reports documentation for details.

To use your own host-specific, CA signed, certificate:

1. Follow the documentation from your Certificate Authority in order to generate and sign an appropriate certificate.

2. Export the certificate in PKCS#12 format - create the required certificate name and encryption password.
(PKCS#12 is the default export format on Windows and it can also be created using the OpenSSL toolset).

3. Name the exported PKCS#12 file with the extension ".pfx" and place it in the KeyReporter Data Folder.

4. Open the "kr.conf" file (in the KeyReporter Data Folder) with a simple text editor and find the line following the "certname" key.  By default, the value of this string is set to the value "keyreporter:Sassafras@kr.pfx".

5. Because your certificate encryption password is stored as plain text in the kr.conf file, it is wise to set permissions on this file so that only authorized accounts can read it - restrict read permissions for the kr.conf file and the .pfx file.

6. Stop and start the KeyReporter process, using the appropriate method for the host OS platform.

Guest access

To enable public "Guest" viewing of reports saved in the public archive, you must assign a "KeyReporter Guest" account password:

1. If you have https turned on, use a browser to go to the Config page using https and enter a password in the "Guest Account" area, then click Apply. Alternatively, open the "kr.conf" file (in the KeyReporter Data Folder) with a simple text editor and replace the dummy string, "GuestPasswordGoesHere" with your choice of password to be assigned to the "KeyReporter Guest" account. The colon character (at the end of "KeyReporter Guest:") and the angle bracket (at the beginning of "</string>" ) must remain as the immediate characters surrounding your password string - and remember not to use the forbidden characters mentioned above.

2. In KeyConfigure, use the "KeyConfigure Accounts ..." menu item (from the Admin Menu) to select the "KeyReporter Guest" account from the drop-down menu. Use the "Edit..." button to enter the password - it must exactly match the value assigned in step 1 above (but without the delimeter characters, angle bracket and colon). Note: by default, the KeyReporter Guest account is already set up as a "Report Only" account with privileges appropriate for read-only access to web reports saved for public access.

If KeyReporter is running when you edit "kr.conf", you will have to stop and restart KeyReporter after you have finished editing.

Just like KeyReporter's ability to grant unauthenticated access to public reports, its ability to schedule reports without a user login depends on a configured password. To enable KeyReporter to run scheduled reports, you must assign a "KeyReporter Schedule" account password:

1. If you have https turned on, use a browser to go to the Config page using https and enter a password in the "Schedule Account" area, then click Apply. Alternatively, open the "kr.conf" file (in the KeyReporter Data Folder) with a simple text editor and replace the dummy string, "SchedulePasswordGoesHere" with your choice of password to be assigned to the "KeyReporter Schedule" account. The colon character (at the end of "KeyReporter Schedule:") and the angle bracket (at the beginning of "</string>" ) must remain as the immediate characters surrounding your password string - and remember not to use the forbidden characters mentioned above.

2. In KeyConfigure, use the "KeyConfigure Accounts ..." menu item to select the "KeyReporter Schedule" account from the drop-down menu. Use the "Edit..." button to match the "KeyReporter Schedule" account password assigned in the kr.conf file. Note: by default, the KeyReporter Schedule account is already set up as a "Report Only" account with privileges appropriate for running reports at scheduled times.

If KeyReporter is running when you edit "kr.conf", you will have to stop and restart KeyReporter after you have finished editing.

Unlike the special accounts, "KeyReporter Guest" and "KeyReporter Schedule" (which cannot be explicitly logged into), other accounts used by KeyReporter will always require a password to be entered at every login using the login page. Note: all K2 account names, passwords, and privileges are stored in KeyServer's "Admin Permissions" file which is managed using KeyConfigure.

Templates, Reports, & Schedules

Like the KeyServer process, the KeyReporter process keeps all of it supporting components and data files in a single location, the "KeyReporter Data Folder". The Report Modules sub-folder actually contains the same modules that are installed by the Admin installer for use by KeyConfigure. When you create a report Template, it uses one of these modules as the basis for the layout - the Template stores various data parameters and restrictions along with the module name.

Report Templates, Schedules (for automatic execution of a template), and completed Reports are stored in the various "archive" sub-folders. You use a web browser to create new templates, schedules, and reports and to recall them from the archives.

Both KeyReporter and KeyConfigure use the same proprietary format to store completed reports with file extension ".ksr". These files are readable either by KeyReporter (for serving out to a connected web browser) or by KeyConfigure (for display in a Report window).

The list of KeyReporter's completed reports is viewable as the "Archive" page using a web browser. This list is also directly viewable in KeyConfigure using the "KeyReporter" menu item from the window menu. Just as a browser can view a selected report, KeyConfigure can select the report and display it for viewing in one of its report windows. Within KeyConfigure, line items in a report window are fully interactive with the rest of the KeyConfigure (supporting click for detail, drag & drop, etc) even when the ksr is not locally stored.

Report Builder

The Report Builder page is used to create new reports and templates (including scheduled templates).

The Builder page is not available for guest access. Because the KeyReporter Guest account has "Report -only" permissions, guests can "run" a report based on a guest accessible Template or "view" reports saved for guest access but a guest can't "build" a new Template nor define a new report. Even if you change the account privileges for the guest account in KeyConfigure, you will not be able to build reports when logged in to KeyReporter as a guest.

The tabs on the left of the builder form flip between "Create a Report" and "Create a Template". Fields in the form let you choose a report module and then specify appropriate parameters such as a time period. The various report module choices are grouped according to type: List Reports, Login Reports, Usage Reports, etc. The List Reports correspond to configuration windows in KeyConfigure - e.g the Computers window, Programs window, and Licenses window.

Just like in KeyConfigure, a general (COMP x lic) report can be "restricted to one..." computer instead of including all Computers. Click on the "restrict to one ..." link in the form to bring up List (COMP) where you double-click to choose the one computer restriction.

Report Archive & Home page

After running a report, you have the option of leaving the completed report in the archive (the default action), discarding it, printing it, etc.

When first navigating to the Archive page, the default Display only shows items created in the last 60 days. The "Display" pop down menus let you restrict your view to recent items, specific report types, templates, or templates with schedule.

When you select a specific item from the archive list, the "Edit" form at the top of the page will display its attributes. This allows you to see how the report or template is defined and to change some attributes as appropriate - use the "Commit" button to apply an edit.

Various actions appropriate to the selected item are available from the button bar below the edit form (e.g. Download, Build, Discard, etc.). The "Build" action takes you to the Report Builder page with its report builder form filled in by the selected item. This serves as a convenient starting point for building a similar report or template.

When a selected archive item is a Template (with or without Schedule) rather than a completed Report, the "View" action changes to "View Thread". Click on this button to bring up a window listing all the completed reports that are based on the selected template but were run at different times.

Only Templates (with or without Schedule) are eligible to be listed on the "home" page where they appear as "Quick Links". All completed reports that share the same template (e.g. the same report module along with same time range selector and restriction parameters) will be associated together under the Quick Link just like "View Thread" from the archive page.

In order to create a Quick Link for navigation to a specific, completed report you must first create a template:

1. Select the report in the archive so its Template (report module plus parameters) are filled into the form at the top of the page.

2. Click on the "Build" button (below the form - not the Builder link at the top of the page!). This will extract the Template from the completed report and bring it over to the Builder page with the "Create a Report" tab (on the left) enabled.

3. Switch to the "Create a Template" tab and then enable the "on home page" checkbox. The builder may choose a default schedule based on its guess of how to mimic the intent of the base report - you can turn off scheduling or change the frequency.

4. Enable the "On Home Page" checkbox. Decide whether to allow Guest access. Also decide on whether to Replace Previous Runs when the template is used to create a new report. Click the "Create" button.

Since all reports based on this newly saved Template are associated in its "thread", the completed report you started with, and possibly other similar reports, will now be reachable from the Quick Link on the home page (or from the Archive page using View Thread).

When you save a Template as a Quick link for public guest access on the public home page, the only completed reports viewable in its thread will be those that were created with public guest access. This may lead to the surprising result that following the steps above and saving with Guest access in step 4 may produce a public Quick link that will not bring up the very report that it was based on (because the base report is not public).

Online Reports

The Report Builder interface in KeyReporter includes a section called “Online Reports”. These reports are different from others in a few ways. Essentially, they are simpler and best suited for small, fast queries. They cannot be saved as ksrs, and cannot be scheduled. They simply perform a query and turn it into a temporary html page. Therefore, these reports are well suited to show online status information.

For example, the “Division Activity Report” shows how many computers in each Division currently have a logged in user. This report may provide a useful way for students to query for computer availability in labs - just Create a report Template from this Online Report and save it for Guest access on Home page.

Each Online Report is defined by a simple text file which can be easily customized to meet your specific needs. For more information, see the Online Reports documentation.

For Macintosh, there is a dashboard widget, KeyMonitor, which lets you display basic KeyServer status information. The implementation is similar to a KeyReporter online report, but in this case the dashboard widget is taking the place of a web browser for the purpose of displaying the information in a floating widget window. KeyMonitor can be found in the software image under “/Installers/Macintosh Installers/Misc/” (it is also included as part of the Admin install in the Misc folder).

Related Topics