Installing a Public Slicebox

A central feature of slicebox is the possibility to send and receive medical image data with structured handling of patient health information. Slicebox makes it possible to define one or more connections between instances. For each such connection, one instance acts as a public host and one as a private host. The private host initiates all communication between instances. Sending an image from a private to a public instance is straight forward - the data is simply pushed to the public instance. The opposite - sending an image from a public instance to a private - is implemented using a polling scheme in the private instance, which regularly asks the public instance if there are new images to fetch. This makes two-way communication possible between an instance behind a firewall (as found in most hospitals) and an outside collaborator. It also means that at least one instance must be accessible to the other in each connected pair of instances (see this howto for information on how to achieve communication between private instances.). This page describes how to setup such a public instance as a background service on Windows and Linux platforms and describes how to implement encryption using TLS. Note that if neither encryption nor running slicebox as a service is of interest, there are no differences between public and private instances in terms of installation.

Windows - running Slicebox as a scheduled task

Download and install the universal zip archive as described in Installing a Private Slicebox. Slicebox does not (yet) provide an installer for Windows which configures slicebox to run as a Windows service, but a similar behavior can be achieved using "Scheduled Tasks" in Windows.

• Open the Windows Task Scheduler
• From the menu, select Action -> Create Task...
• In the 'General' tab, name the task 'slicebox' and select 'Run whether user is logged on or not'
• In the 'Triggers' tab, create a new trigger which begins 'At startup'
• In the 'Actions' tab, create a new action of the 'Start a program' type pointing to the bin/slicebox.bat startup script in the slicebox installation directory
• Review other task settings and see if any apply to your installation

There should now be a slicebox task in the list of active tasks. Restart the computer, or start it directly from the list of scheduled tasks

Linux (Debian) - installation and configuration

We provide a .deb package for installing slicebox, available on Bintray. This installer sets up slicebox to run as a service. Install the .deb package using the command

sudo dpkg -i <package name>.deb

Uninstall slicebox and remove all files including configuration with the command

sudo apt-get purge slicebox

The following file structure is used:

Folder	User	Description
/usr/share/slicebox	root	Installation directory
/etc/default/slicebox.conf	root	Config file for environment variables and other settings applied before the application starts
/etc/slicebox	root	Sym-link to slicebox configuration folder
/var/log/slicebox	slicebox	Location of slicebox log files
/var/run/slicebox	slicebox	Currently not used

The service can be controlled using commands such as sudo restart slicebox, sudo stop slicebox and sudo status slicebox.

During the installation a user and group named slicebox is created, as indicated in the table above. The service is run using this user, which means that files created by slicebox (such as the database files and stored DICOM files) must reside in a directory in which the slicebox user has the necessary permissions. Upon installation, the default settings in /etc/slicebox/slicebox.conf point to the installation directory itself, which is owned by root. This means that slicebox will not run correctly (there will be a log error message indicating this). We suggest the following changes:

• Create a directory /var/slicebox owned by the slicebox user and group.
• Change the following settings in the config file /etc/slicebox/slicebox.conf:
  • slicebox.dicom-files.path = "/var/slicebox/dicom-files"
  • slicebox.database.path = "/var/slicebox/slicebox"
• Make other applicable changes to the configuration. You probably wish to override slicebox.host, slicebox.port, slicebox.superuser.user and slicebox.superuser.password.
• Restart slicebox using sudo restart slicebox
• The service should now be available at your specified host name and port number. Check the log to make sure the service is running as intended.

Running slicebox behind a reverse proxy

• Hospitals often restrict internet access to a limited set of ports, usually ports 80 and 443 (for SSL). Slicebox instances that should communicate with hospital instances may therefore be required to run on either of these ports. This is difficult to accomplish on Linux servers as users other than root are not permitted to open ports below 1024. One possibility is to run slicebox on a high port number such as 5000, and set up a reverse proxy using e.g. Apache or Nginx which redirects incoming traffic to your site example.com:80 to slicebox running on localhost:5000. When running slicebox behind a reverse proxy the service is running on a local hostname (typically localhost:5000) while it is accessed via a public hostname. The public hostname and port are specified under the configuration path slicebox.public in slicebox.conf. The resulting example configuration is

slicebox {

	host = "localhost" // local hostname
	port = 5000        // local port

	ssl {
		ssl-encryption = off

		keystore {
			path = "slicebox.jks"
			password = "slicebox"
		}
	}

	public {
		host = "slicebox.se" // public hostname
		port = 80            // public port
		with-ssl = false
	}

	dicom-files {
		path = "/var/slicebox"
	}

	database {
		path = "/var/slicebox/slicebox"
	}
	  
	superuser {
		user = "admin"
		password = "secret"
	}
}

Encryption using SSL/TLS

Slicebox supports encryption of all traffic to and from the server using standard SSL (SSL is also known as TLS, think URLs with https:// rather than http://). When running and accessing slicebox on a small internal network with trusted users it may be considered ok not to use SSL; see the section below on security and what sensitive information is communicated over the network. When setting up slicebox on a public server which is to be accessed over the Internet, using SSL is strongly encouraged. SSL can be enabled in slicebox using the setting slicebox.ssl.ssl-encryption = on. If slicebox is placed behind a reverse proxy, SSL can be enabled there instead (see the documentation of your particular reverse proxy). In that case, set slicebox.ssl.ssl-encryption = off and slicebox.public.with-ssl = true.

In order for SSL to function, you need an SSL certificate. There is a range of trusted companies (certificate authorities) providing time-limited such certificates for a fee (see e.g. www.ssls.com). Slicebox loads SSL certificates from a Java Keystore (a .jks file) specified by the settings in slicebox.ssl.keystore. Here is a short description of how to create a keystore file from scratch.

Keystores can be created and manipulated using the keytool command-line utility which is shipped with every Java installation (both JREs and JDKs). It is located in the $JAVA_HOME/bin folder. In the following, we assume that this folder is on your path such that the keytool command can be used from any location. We also assume that the domain running slicebox is slicebox.se. Change this to your domain.

1. keytool -genkey -alias slicebox -keyalg RSA -keysize 2048 -keystore slicebox.se.jks Creates a new keystore containing your secret private key. You will be required to answer a series of questions. The first question is "What is your first and last name?". This is not a question for YOUR name, but rather the name of the domain to register. In this case the answer is "slicebox.se". Answer the other questions as carefully as possible.
2. keytool -certreq -alias slicebox -keyalg RSA -file slicebox.se.csr -keystore slicebox.se.jks This will create a certificate signing request in the file slicebox.se.csr. This is a plaintext file containing a chunk of information about your site. When purchasing an SSL certificate, the certificate authority will ask for this information.
3. Complete the purchase (which includes a series of verification steps) and download the certificate bundle. The bundle contains the new certificate for your site and usually intermediate certificates and a root certificate. Install the certificates from the root down to your new certificate:
   1. keytool -import -trustcacerts -alias root -file <name of root certificate>.crt -keystore slicebox.se.jks This step may not be necessary as Java comes preinstalled with a range of root certificates contained in the keystore $JAVA_HOME/lib/security/cacerts. keytool with alert if this root certificate is already present and let you skip this step.
   2. keytool -import -trustcacerts -alias intermed -file <name of intermediate certificate>.crt -keystore slicebox.se.jks Installs the intermediate certificate(s).
   3. keytool -import -trustcacerts -alias slicebox -file slicebox.se.crt -keystore slicebox.se.jks Installs the certificate for your site.

Put the keystore file in e.g. the conf folder of the slicebox installation directory and edit the ssl section of slicebox.conf to

ssl {
	ssl-encryption = on
	keystore {
		path = "conf/slicebox.jks"
		password = "<the password you entered for the keystore>"
	}
}

It is also possible to use a self-signed certificate, which is what you have after completing step 1 above and skipping all other steps. Another option is to create a local root certificate authority for your internal network, and issue SSL certificated based on that. In either case, all slicebox clients must have this self-signed or local root certificate installed to allow accessing slicebox over https. By "clients", we refer to browsers accessing the slicebox user interface, or slicebox itself when it communicates with other slicebox instances.

• Browsers allow certificates to be installed. All browsers accessing the slicebox UI must install the certificate.
• When slicebox acts as a client, it uses the list of root certificates in $JAVA_HOME/lib/security/cacerts. The certificate of the remote box (or the local root certificate) must be added to this keystore using keytool using the command keytool -import -alias <domain> -keystore cacerts -file <name of certificate>.crt.

A Word on Security

Slicebox stores and communicates sensitive data. In particular, hospital installations will manage datasets containing patient information and when requesting and adding datasets, this information will be transported over the network.

• Make sure the DICOM directory slicebox.dicom-files.path where datasets are stored is not accessible to third party users
• Make sure the database slicebox.database.path is not accessible to third party users
• Make sure the configuration file slicebox.conf is not accessible to third party users. The superuser and keystore passwords are specified in cleartext in this file.
• Use SSL encryption. If not, datasets, usernames and passwords and other sensitive information can be intercepted without you noticing. If using SSL, be sure to protect the keystore.
• When sending and receiving images from a slicebox instance on the Internet, a third party may intercept transmissions. Always use SSL when communicating over the Internet.
• Usernames and passwords are sent in cleartext over the network when logging in; again, use SSL. Passwords are stored on the server as salted hashcodes. In other words, slicebox does not store cleartext passwords.