SensusRF Collection Mobile – server administration manual

Installation manual

Prerequisites

1. You have to have administrator (Windows) or root (Linux/Unix) rights on the target machine.
2. You have to own the valid certificate for the domain that will be used for running SensusServer web
application. This certificate has to be stored in the one of the following formats: JKS, PKCS11 or PKCS12.
Self-signed certificate will not work correctly. The certificate has to be signed by some public certification
authority.
3. There has to be installed JRE 8 or above on the target machine.

Installation procedure

1. Unpack all files from the archive SensusServer.zip to some destination folder on the target machine, e.g.:
[installation_directory]/sensus.

2. Edit the configuration file server.xml of the server in [installation_directory]/conf/server.xml:

a. Replace the "%%PORT%%" string in the two sections "Connector" by the TCP port that will be used for
the HTTPS server. The recommended port is 443 as it is the default HTTPS port. E.g.: replace the string
'<Connector port="%%PORT%%"' with '<Connector port="443"' and string 'redirectPort="%%PORT%
%"' with 'redirectPort="443"'

b. Replace the "%%SSL_CERT_PATH%%" string in the section "Connector" by the path to your keystore
with the certificate for your domain. The keystore has to be in JKS, PKCS11 or PKCS12 format. The
certificate has to be issued for the domain that will be used for the running your SensusServer application.
E.g.: replace the string 'keystoreFile="%%SSL_CERT_PATH%%"' with
'keystoreFile="/path/to/certificate.jks"'.

Note: keystore must contain whole chain to the root certification authority.

c. Replace the "%%SSL_CERT_PASSWORD%%" string in the section "Connector" by the password to the
given keystore. E.g.: replace the string 'keystorePass="%%SSL_CERT_PASSWORD%%"' with
'keystorePass="YourKeystorePassword"'.

3. Edit the configuration file sensus.properties of the SensusServer application in

[installation_directory]/lib/config/sensus.properties:

a. Replace the "%%DB_PATH%%" string by the path to the SQLite database. If the database file doesn't
exist yet, it will be created when the server starts up for the first time. When the database is created, the
default administration user is created. The name of this user is "admin" and it has no password assigned by
the default (password is blank). E.g.: replace the line 'sqlite.path=%%DB_PATH%%' by the line
'sqlite.path=/root/sensus_cm.db'.

b. Replace the "%%AES_KEYSTORE_LOCATION%%" string by the path to the keystore. The keystore
has to be of "JCEKS" type. The keystore has to contain 128-bit AES key with alias "db_key". Password of
the keystore and the key has to be identical. Replace the "%%AES_KEYSTORE_PASSWORD%%" sting
by password to the keystore.

c. Replace the “%%MAIL_PROTOCOL%%” string for protocol used by your email server (mostly
smtp/smtps).
The %%MAIL_HOST%% replace with host address to your email server.
The %%MAIL_PORT%% replace with port of your email server (default 25/465)
The %%MAIL_USERNAME%% can be left empty if no authentication is used. Otherwise replace the
string with your username and the %%MAIL_PASSWORD%% with password to this username.
The %%MAIL_USE_SSL%% replace with true or false if your server is using SSL or not.
 The %%MAIL_ALIAS%% can be left empty to use username by default or replace the string with your
own alias name (some servers may require that alias is same as username)

Note: Please check if the sent emails are received correctly. If not, please check the headers in the sent
email's source for the authentication results – the MX record should be correct and the dkim/spf/dmarc
should pass. If authentication does not pass please check the host name of the FROM email address. If it is
not correct please provide correct host name in the %%MAIL_USERNAME%% field or provide an valid
email address in the %%MAIL_ALIAS%% field.

There is possibility to set both above properties via environment variables:

"AES_KEYSTORE_LOCATION" and "AES_KEYSTORE_PASSWORD". The advantage of
environment variables it that password is not in open form anywhere on disk.

If keystore doesn't exist in specified location on disk application tries to create it. If location is not
specified application tries create it in directory where database file is stored. In case of auto creation by
application default name for keystore is "aes-keystore.jck" and password is "sensus123".

Keystore manual: http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

4. On Linux/Unix system go to the "[installation_directory]/bin/" directory and run command "chmod +x *.sh".
This ensures that all scripts will have sufficient right to be run.

5. Run the server by the script startup(.bat|.sh) which is located in directory [installation_directory]/bin.

6. Try to connect and login to the server by the link https://your.domain/SensusServer (for default port 443) with
the default user "admin" without password.
Since email address of the admin is not set email authentication will be omitted. You will be asked to enter
email address where authentication codes will be sent. If you accidentally enter an inaccessible mail you can
change it only manually in database file.
Change the password of the user admin immediately after the first login.

7. The server can be turn off by the script [installation_directory]/bin/shutdown(.bat|.sh)

Maps configuration

All maps have to be located in the [installation_directory]/webapps/SensusServer/maps directory. The format of the
map is the GHZ archive e.g. Andorra.ghz. By default, there is only Andorra.ghz file after the first startup of the server.
To add more maps to the server, you have to create GHZ archive with the map and navigation data for the concrete
country, state or region, copy this archive to the maps folder and update sensus.properties file correctly. There is an
example procedure how to add the map of Slovakia:

1. Ask your SensusRF CM Server supplier (Sensus/SDE) for the Slovakia.ghz map package or make the map
package by yourself following these steps:
a. Download Slovakia.map file from the http://download.mapsforge.org/maps or
http://www.openandromaps.org/en/downloads/countrys-and-regions
b. Now we have a precompiled map, we also need additional information for navigation. These information
are generated from PBF file of the same area. These PBF files can be downloaded from website:
http://download.geofabrik.de. Please be careful to download the same area. There are different kind of
level of PBF files, like Europe then states, then cities, etc.
c. Next step is to generate the specific information from the PBF file that is then used by the Graphhopper
library (https://graphhopper.com/) for drawing of the path to meter in the Android application. For this we
use the graphhopper.sh script file, which is part of the Graphhopper project
(https://github.com/graphhopper/graphhopper, download stable release 0.4)
Run the command graphhopper.sh import <path to PBF file>. After a while a directory with the
generated files is created.
d. The last step is to provide the whole package in ghz format. This format is a standard zip file with map file
and the generated files. On Linux you can do this by using the following command: zip -r Slovakia.ghz * .
The name of the ".ghz" package and the ".map" file inside the package should be the same (e.g.
Slovakia.ghz - Slovakia.map). This ensures that the selection of the map on the Android device works
correctly.
2. Copy the created Slovakia.ghz file to the [installation_directory]/webapps/SensusServer/maps folder.
 3. Update the sensus.properties file. In the sensus.properties file there is a maps value, which is a comma
separated list in the format: [map_file_name.ghz:Map name] pairs. E.g. if you have only two files in the maps
folder (Andorra.ghz and Slovakia.ghz) your sensus.properties configuration file should contain line
"maps=[Andorra.ghz:Andorra],[Slovakia.ghz:Slovakia]"
4. Restart the SensusServer application, by turn off the server and start it again through scripts described before.
After the restart, the maps should be available to download in the SensusRF CM mobile application.

Manuals and Terms of Use setup

Users may view application manual and terms of use via links in page footer. Both manual and terms of use may be
localized. After installation and application start there will be [installation_directory]/webapps/SensusServer/ directory
created.
In order to make manual or terms of use accessible copy manuals to
[installation_directory]/webapps/SensusServer/localization/manuals or
[installation_directory]/webapps/SensusServer/localization/termsOfUse respectively. Both manuals and terms of use
have to be pdfs. File names have to be in shape [language tag].pdf e.g. en.pdf or en-US.pdf.

Log files

The server log files can help you to solve some basic issues. The server log files are located in the
"[installation_directory]/logs/" directory. The format of the log files is [catalina.DATE.log] e.g.: "catalina.2015-07-
02.log" and [localhost.DATE.log] e.g.: "localhost.2015-07-02.log". Every day the new pair of the log files is created.
The file [catalina.DATE.log] contains some basic messages like client requests or db accesses and the file
[localhost.DATE.log] contains the applications exceptions with the full stack traces.