TN 8080: KeyReporter standalone installations

in version 7.2 and higher, KeyReporter is installed along with KeyServer. Configuration is greatly simplified when running alongside KeyServer, but here we describe manual configuration of a standalone KeyReporter.

2014.03.27

All of the configuration described in this technote ONLY applies when KeyReporter is installed as a standalone process. When KeyReporter is enabled as part of the KeyServer install, all of this configuration is automated by KeyConfigure wizards and UI based configuration. The only thing you may want to do with a standard KeyReporter install is provide your own certificate for https, which is described further down in this technote.

Limitations of standalone KeyReporter

Generally speaking, running KeyReporter in a standalone installation does not affect the web UI very much, but it does mean that KeyConfigure cannot interact with KeyReporter.

Installation & Configuration

KeyReporter can be hosted on a choice of platforms just like KeyServer (and KeyShadow). The KeyReporter component (kr or kr.exe) runs as a background process with no user interface. It uses the report modules and data files contained in its "KeyReporter Data Folder". KeyReporter has the most functionality when sublaunched by KeyServer, but stand alone KeyReporter installers are also available for Windows (K2Reporter.exe), Mac OS X (K2Reporter.pkg), and Linux (K2Reporter.....rpm). Using the standalone installer allows KeyReporter to run on a different computer from KeyServer.

When KeyReporter is enabled through KeyConfigure, configuration is completed by a wizard. When KeyReporter is installed as a standalone, you must configure the KeyServer address so that KeyReporter can logon. 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 "keyserver" which assumes that you will have a DNS entry with this name. If this assumption is not true you will need to edit the file.

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. If two processes are configured to use the same port, only one will be successful at next boot – so to avoid conflict, the kr.conf file must be edited as described below. Regardless of what port is used, you may have to check firewall settings and configure as necessary to allow incoming traffic.

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 you do not have a DNS entry for "keyserver" that points to the computer hosting your KeyServer, then the default target address, "keyserver", for the "server" key must be changed in kr.conf to the actual ip address (or DNS name) of the KeyServer host. The url specified in a browser to access KeyReporter will of course need to be for the KeyReporter computer, not the KeyServer computer. 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 address of the server, or the port which KeyReporter uses), 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).

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.

KeyReporter can publish reports for public "Guest" viewing with no login password required - but this behavior is disabled by default. 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 can be used when you want to switch views to a more privileged account. A section below explains how to configure the KeyServer's Guest account.

Optional Secure Connections (SSL)

By default, KeyReporter is configured to serve pages using http connections from 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 (accessed via https) instead of (or in addition to) the un-encrypted web service (accessed via http).  The SSL option secures all data transmitted between KeyReporter and browser and the browser login process will no longer require JavaScript, making logins somewhat quicker. Connecting to KeyReporter with SSL also allows the administrator to manage additional configuration options that are not allowed when using a standard http connection.

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.

The steps below describe the typical setup applicable when there is no process already running on port 443 (e.g.no web mail or other a secure web service) – but you can specify a custom port, if necessary.

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".

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

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 (however, you will probably see some warning since the default certificate is self-signed). 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".

  i) change the first field, "keyreporter" to the certificate name that you created while exporting above.
 ii) change middle field, "Sassafras", to match the encryption password you created above.
iii) change the last field, "kr.pfx", to match the exact file name of the exported PKCS#12 file.

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. In KeyConfigure, open the "Admin Access ..." window (from the Windows Menu) and double-click on the Account item named "KeyReporter Guest". Specify a password for this account ( the characters    %  &  :  =  /  +  #  ?  @   are not allowed). Note: by default, the KeyReporter Guest account is already set up with the "Report-only" role so it will have read-only access to web reports that are saved for public access.

2. Connect to KeyReporter with a browser and login using the admin account and password. Click on the Configuration link. If https is already enabled, you will see the configuration page where you must enter the "KeyReporter Guest" account password, just created above. If https is not enabled, you can enable it as described in a previous section. 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. [Note: the colon character (at the end of "KeyReporter Guest:") must immediately precede your password string and the angle bracket (at the beginning of "</string>" ) must terminate your password string (with no extra space characters).] 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. In KeyConfigure, open the "Admin Access ..." window (from the Windows Menu) and double-click on the Account item named "KeyReporter Schedule". Specify a password for this account ( the characters    %  &  :  =  /  +  #  ?  @   are not allowed). Note: by default, the KeyReporter Schedule account is already set up with the "Proxy" and "Report-only" roles so KeyReporter can execute scheduled web reports based on templates.

2. Connect to KeyReporter with a browser and login using the admin account and password. Click on the Configuration link. If https is already enabled, you will see the configuration page where you must enter the "KeyReporter Schedule" account password, just created above. If https is not enabled, you can enable it as described in a previous section. 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. [Note: the colon character (at the end of "KeyReporter Schedule:") must immediately precede your password string and the angle bracket (at the beginning of "</string>" ) must terminate your password string (with no extra space characters).] 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.