TN 8080: KeyReporter standalone installations

in version 7.2 and higher, KeyReporter is installed along with KeyServer. This stand alone configuration is considered legacy and is not encouraged.

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 UI based configuration.

Standalone Web Service

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.

Within KeyReporter, you won't be able to make new folders for reports
In KeyConfigure, you won't be able to access the Reports window
In the KeyConfigure Report Builder you won't be able to make schedules or on-demand templates
You will be unable to configure or start and stop KeyReporter from the Config options in KeyConfigure. Those settings will control the Web Service instance on the KeyServer system, not the stand alone install of KeyReporter.
Increased complexities of network configuration can present challenges. Support may be limited depending on your environment.

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 (ksp-reporter-i386.exe), Mac OS X (ksp-reporter.pkg), and Linux (K2ReporterXXXX.rpm or K2ReporterXXXX.deb) in the Misc folders of the full image archive. Using the standalone installer allows KeyReporter to run on a different computer from KeyServer. You can have any number of KeyReporters point to the KeyServer, including the default included KeyReporter installed with KeyServer. While all data is the same, the configuration of each KeyReporter can be entirely different including color scheme, dashboards, and Map configurations. Accounts, permissions, and other root configuration is dictated by the 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 in your setup of KeyServer using KeyConfigure).

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.

Example Installation

To more fully illustrate the process of installing a stand along KeyReporter, imagine we want to install on a Linux based system. The following steps would be a basic outline of the activity:

Download the image archive zip file:

wget https://www.sassafras.com/software/release/KSP-v77.zip

Unzip the archive and cd into Installers/Linux Installers/Misc/Reporter
Run the installer with something like:
```
sudo rpm -i KeyReporter-xxxxx.rpm
```
(see Linux Client Deployment for linux install tips)
Note: If you're moving an instance of KeyReporter that has been in production, you'll want to copy the KeyReporter Data Folder from the existing server to this new server.
On Windows this would be in C:\Program Files\Sassafras K2\Server\KeyServer Data Folder\Helper Data\KeyReporter Data Folder
On Mac this would be in /Library/KeyServer/KeyServer Data Folder/Helper Data/KeyReporter Data Folder
Go to the data folder and edit the config file (use your favorite editor, vi is used here by example):
```
cd /user/local/k2/KeyReporter Data Folder
sudo vi kr.conf
```

Change the KeyServer hostname as needed

	<key>keyserver</key>
	<string>fqdn.of.main.server</string>

Set the Guest and Scheduler passwords as set on those accounts in KeyConfigure (see details below)
Add configuration for the http and https ports you want to use into kr.conf file:
```
	<key>port</key>
	<string>80</string>

	<key>authport</key>
	<string>443</string>
```
See Other Settings below for more options you may want to add.
Save your changes and exit the file
Ensure firewall ports have been opened on the network and on the local system firewall as needed.
TCP Ports 80 and 443 by default would need to be open to KeyReporter from where ever you want to allow access. If you use alternate web ports adjust as needed.
TCP Port 19283 needs to be open on the KeyServer allowed from the KeyReporter.
Our installers attempt to open local ports, but if anything goes wrong on Redhat or CentOS you may need to open the local firewall with something like:
```
sudo firewall-cmd --add-service=http --permanent
sudo firewall-cmd --add-service=https --permanent
sudo firewall-cmd --reload
sudo firewall-cmd --list-services
```
You should see http and https listed in the output of the final command.
Note also that in order for the service to display geographic maps it must be able to contact openstreetmap.org. In order to show icons on the Software page, it must be able to reach prs.sassafras.com.

Start the KeyReporter service:

sudo systemctl start KeyReporter

sudo service KeyReporter start

Run netstat to ensure the service is running on the desired ports:

netstat -nlpt
	
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name                    
tcp        0      0 0.0.0.0:443             0.0.0.0:*               LISTEN      -                                   
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      -

The process would be very similar on Windows. Again the installer should open the needed firewall ports, the service can easily be managed from Windows Services, and the kr.conf file structure is the same.

Guest access and Scheduler

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

Should these entries be missing, they should have looked like this:

	<key>gaccount</key>
	<string>KeyReporter Guest:GuestPasswordGoesHere</string>

	<key>saccount</key>
	<string>KeyReporter Schedule: SchedulePasswordGoesHere </string>

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 Sassafras Server account names, passwords, and privileges are stored in KeyServer's "Admin Permissions" file which is managed using KeyConfigure.

Other Settings

Because you can not manage settings of the stand alone KeyReporter in the Config settings in KeyConfigure, you will need to manually manage them in the kr.conf file. Significant keys you should consider are as follows:

Specify the SSL certificate information. Assuming you put the certificate in the Windows certificates store, and KeyReporter is running under the local system account default, you can use the syntax below. Otherwise you'll need to specify the pfx file password and name as outlined in Enabling SSL.

	<key>certname</key>
	<string>*@*</string>

To force all traffic to HTTPS for security (avoid auth in clear):

	<key>forcehttps</key>
	<integer>1</integer>

Set the origins to ensure clean routing, especially when there is any DNS complexity. Note that port is optional if you changed the default ports as detailed above.

	<key>origin</key>
	<string>http://FQDN.of.server[:port]</string>

	<key>sslorigin</key>
	<string>https://FQDN.of.server[:port]</string>

Should you need to leverage a Proxy (not recommended) you can use:

	<key>proxy</key> 
	<string>proxy.yourorg.com[:port]</string>