icon-gettingStarted.png
Getting Started
Prerequisites for installing XNAT
Download XNAT
Step by Step Guide to Installing XNAT

Installing DicomServer


Custom Installation Options

Build From Source

Download XNAT in a Virtual Machine

[Edit Nav]


Note: DicomServer is no longer a separate entity in XNAT 1.5. These instructions are valid for XNAT 1.4 only.

DicomServer: An Introduction

DicomServer receives DICOM data using the standard DICOM networking protocol, then organizes those data for import into XNAT. If local network security policies permit, users can send data directly from the scanner console to XNAT via DicomServer; alternatively, DicomServer accepts data from any DICOM C-STORE client (SCU), e.g., a workstation or a utility such as OsiriX or DicomBrowser. This document describes version xnat-1.4 of DicomServer, for use with XNAT version 1.4.


Installing DicomServer

The DicomServer software requires separate installation from the rest of XNAT, and expects to find a fully installed, configured, and operational XNAT. Install, configure, and start the associated XNAT instance before starting to install DicomServer. It is best to perform all of the following DicomServer installation and configuration steps using the same user account that owns the XNAT installation.

Download

The current build is version 1.4.2b7 of 4/1/2011, available here. Additional information about this package, including links to the source code, is here.

Installation

Unpack the distribution. This should be done as the same user who owns the various XNAT directories: archive, prearchive, cache, etc. This should also be the same user who runs Tomcat, and thereby the XNAT webapp. We recommend that this XNAT-owning user not be the root user.

xnat@myhost$ tar zvxf DicomServer-xnat-1.4-r702.tgz

This step creates a DicomServer-xnat-1.4 directory, which contains a few subdirectories, notably including bin/ (containing scripts) and etc/ (containing configuration files).

Configuring DicomServer

Two files must be edited to configure DicomServer: arc_dcmstore, the startup script; and DicomServer.xml, the properties configuration file. Detailed configuration instructions are provided in the Appendix, but most installations will look like one of the following examples.

Example: Simple installation

Assume that:

  • DicomServer is installed in /opt/xnat/DicomServer-1.4/
  • the XNAT cache directory (configured through the Default Settings link in the webapp) is /opt/xnat/cache
  • Tomcat/XNAT and DicomServer run on the same machine, my.xnat.org
  • Tomcat runs on port 8080 and the XNAT webapp is named xnat, so that the full URL for the XNAT main page is http://my.xnat.org:8080/xnat
  • The XNAT administrative account is admin, with password adminpw
  • DicomServer will use port 8104 and AE title MYXNAT for DICOM network services, and port 8180 for web services.

Startup script

The "Configuration items" part of the startup script arc-dcmstore should look like this:

######################
# Configuration items
######################
 
# DicomServer root
DICOMSERVER=/opt/xnat/DicomServer-1.4
 
# Path of "lib" directory, where jars can be found
LIBDIR=${DICOMSERVER}/lib
 
# Path of properties file containing configuration information
propsfile=${DICOMSERVER}/etc/DicomServer.xml
 
# process ID file, used to find the active server
pidfile=${DICOMSERVER}/etc/DicomServer.pid
 
DICOM_AE_NAME=MYXNAT
DICOM_PORT=8104

Configuration properties

For this simple example, the configuration properties file DicomServer.xml should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>
 Simple DicomServer configuration
</comment>
 
<entry key="arcspec">/opt/xnat/cache/archive_specification.xml</entry>
<entry key="xnat_url">http://my.xnat.org:8080/xnat</entry>
<entry key="user">admin</entry>
<entry key="password">adminpw</entry>
 
<entry key="http_port">8180</entry>
 
<entry key="log4j.rootLogger">WARN,R</entry>
 
<entry key="log4j.appender.R">org.apache.log4j.RollingFileAppender</entry>
<entry key="log4j.appender.R.File">/opt/xnat/DicomServer-1.4/log/DicomServer.log</entry>
<entry key="log4j.appender.R.MaxFileSize">100KB</entry>
<entry key="log4j.appender.R.MaxBackupIndex">4</entry>
<entry key="log4j.appender.R.layout">org.apache.log4j.PatternLayout</entry>
<entry key="log4j.appender.R.layout.ConversionPattern"&gt%d %5p [%t] %c - %m%n</entry>
 
<entry key="log4j.appender.RECEIVED">org.apache.log4j.DailyRollingFileAppender</entry>
<entry key="log4j.appender.RECEIVED.File">/var/log/DicomServer-received.log</entry>
<entry key="log4j.appender.RECEIVED.DatePattern">'.'yyyy-MM-dd</entry>
<entry key="log4j.appender.RECEIVED.layout">org.apache.log4j.PatternLayout</entry>
<entry key="log4j.appender.RECEIVED.layout.ConversionPattern">%d %m%n</entry>
 
<entry key="log4j.logger.org.nrg">INFO</entry>
</properties>

This configuration includes instructions to the log4j logging system, so that log messages are written to /opt/xnat/DicomServer-1.4/log/DicomServer.log. When the size of that file reaches 100 KB, its contents are moved to the file DicomServer.log.1 and additional log messages are written to the newly empty DicomServer.log. If DicomServer.log.1 already exists, its contents are in turn copied to DicomServer.log.2, and so on, except that if DicomServer.log.4 exists, its contents are simply deleted.

Also, in this configuration, each DICOM data object received is logged in the file /var/log/DicomServer-received.log. Receipt logs for previous days are saved in files DicomServer-received.log.yyyy-MM-dd; for example, DicomServer-received.log.2011-01-12 contains receipt logs for January 12, 2011.

For information on customizing the logging behavior, consult the log4j documentation.

Configuring the upload applet

The XNAT upload applet needs to communicate with DicomServer both via standard DICOM services and via an HTTP-based web service in order to upload DICOM data. The upload applet is configured on the XNAT Default Settings page, in the DICOM Server Configuration section. For this example, the settings would be:

DICOM host
my.xnat.org
DICOM port
8104
DICOM AE Title
MYXNAT
DICOM Server HTTP URL
http://my.xnat.org:8180/session

Example: Port mapping

The simple example above provides DICOM network operations on TCP port 8104. The standard, well-known port number for DICOM is 104, and it may be advantageous in some circumstances to use the well-known port. On Unix-flavored systems, this port is privileged, i.e., only processes owned by root can open that port. However, we recommend that the DicomServer process be run as a non-root user.

In order to provide DICOM services on port 104, configure DicomServer to use a non-privileged port (e.g., 8104), and use port forwarding to reroute traffic to port 104 to the underlying service on port 8104.

Using iptables

Some Unix variants, including Linux and Solaris, use iptables to perform port forwarding. The following commands, which must be executed as root, set up a forwarding so that connections to port 104 are directed instead to non-privileged port 8104:

root@myhost$ /sbin/iptables -A FORWARD -p tcp --destination-port 104 -j ACCEPT root@myhost$ /sbin/iptables -t nat -A PREROUTING -j REDIRECT -p tcp --destination-port 104 --to-port 8104 root@myhost$ /sbin/service iptables save

Configuring DicomServer in this situation is nearly identical to the simple case: in particular, the http_port entry in DicomServer.xml should still be set to 8104. The only difference comes in configuring the upload applet. The DICOM Server Configuration parameters on the XNAT Default Settings page should be:

DICOM host
my.xnat.org
DICOM port
104
DICOM AE Title
MYXNAT
DICOM Server HTTP URL
http://my.xnat.org:8180/session

Example: Reverse proxy

An XNAT instance that allows access from outside a trusted network may have stricter security requirements than an intranet-only server. When access from public networks is required, a reverse proxy server can perform several useful services, such as SSL encryption, load balancing, and port mapping.

For this example, assume that:

  1. DicomServer is installed in /opt/xnat/DicomServer-1.4/
  2. The XNAT cache directory is /opt/xnat/cache
  3. Tomcat/XNAT and DicomServer run on the same machine, my-hidden-host.local
  4. Tomcat runs on port 8080 and the XNAT webapp is named xnat, so that the full URL for the XNAT main page from behind the reverse proxy server is http://my-hidden-host.local:8080/xnat
  5. The XNAT administrative account is admin, with password adminpw
  6. DicomServer will locally use port 8104 and AE title MYXNAT for DICOM network services, and port 8180 for web services.
  7. The reverse proxy server is configured to perform SSL encryption for the XNAT webapp, so that the URL https://my.xnat.org provides secured access to the internal URL http://my-hidden-host.local:8080/xnat
  8. The reverse proxy server is configured to redirect traffic from external port 104 to port 8104 of my-hidden-host.local
  9. The reverse proxy server is configured to perform SSL encryption for the DicomServer web service, so that the URL https://my.xnat.org:8443/session provides secured access to the internal URL http://my-hidden-host.local:8180/session

Startup script

The startup script arc-dcmstore is identical in this case to the startup-simple/simple configuration above.

Configuration properties

With a reverse proxy server as described, the configuration properties file DicomServer.xml should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>
 DicomServer configuration using reverse proxy server
</comment>
 
<entry key="arcspec">/opt/xnat/cache/archive_specification.xml</entry>
<entry key="xnat_url">http://my-hidden-host.local:8080/xnat</entry>
<entry key="user">admin</entry>
<entry key="password">adminpw</entry>
 
<entry key="http_port">8180</entry>
<entry key="xnat_public_url">https://my.xnat.org</entry>
<entry key="scp_public_host">my.xnat.org</entry>
<entry key="scp_public_port">104</entry>
<entry key="sessions_url">https://my.xnat.org:8443/session</entry>
 
<entry key="log4j.rootLogger">WARN,R</entry>
 
<entry key="log4j.appender.R">org.apache.log4j.RollingFileAppender</entry>
<entry key="log4j.appender.R.File">/opt/xnat/DicomServer-1.4/log/DicomServer.log</entry>
<entry key="log4j.appender.R.MaxFileSize">100KB</entry>
<entry key="log4j.appender.R.MaxBackupIndex">4</entry>
<entry key="log4j.appender.R.layout">org.apache.log4j.PatternLayout</entry>
<entry key="log4j.appender.R.layout.ConversionPattern"&gt%d %5p [%t] %c - %m%n</entry>
 
<entry key="log4j.appender.RECEIVED">org.apache.log4j.DailyRollingFileAppender</entry>
<entry key="log4j.appender.RECEIVED.File">/var/log/DicomServer-received.log</entry>
<entry key="log4j.appender.RECEIVED.DatePattern">'.'yyyy-MM-dd</entry>
<entry key="log4j.appender.RECEIVED.layout">org.apache.log4j.PatternLayout</entry>
<entry key="log4j.appender.RECEIVED.layout.ConversionPattern">%d %m%n</entry>
 
<entry key="log4j.logger.org.nrg">INFO</entry>
</properties>

Configuring the upload applet

The upload applet, running on a client web browser, must contact DicomServer through the public services provided by the proxy server. The DICOM Server Configuration settings (on the XNAT Default Settings page) would be:

DICOM host
my.xnat.org
DICOM port
104
DICOM AE Title
MYXNAT
DICOM Server HTTP URL
https://my.xnat.org:8443/session

Running DicomServer

The script arc-dcmstore starts and stops a DicomServer. To start the server, do:
xnat@myhost$ arc-dcmstore start

To stop the server, do:
xnat@myhost$ arc-dcmstore stop

The arc-dcmstore script should be configured to your installation; in particular, most users will want to explicitly set the following variables inside the script:

Shell variable
Description
LIBDIR
Full pathname of the DicomServer lib/ directory
propsfile
Full pathname of the DicomServer configuration file
DICOM_AE_NAME
AE title for DICOM C-STORE operations
DICOM_PORT
TCP port for DICOM C-STORE operations

If your site will be receiving extremely large DICOM studies (e.g., >10,000 files), it may be necessary to increase the Java heap space. (How do you know that it's necessary? DicomServer throws OutOfMemoryErrors when it tries to build session documents.) The memory allocation limit can be changed using the -Xmx flag to the Java virtual machine; on the line in arc-dcmstore that reads:"$JAVA" -server -showversion ... , a memory allocation limit can be specified, e.g., "$JAVA" -server -Xmx1g -showversion ... increases the heap limit to 1 GB.

DicomServer and XNAT

When DicomServer receives the first DICOM file from a new study, it examines the metadata to determine which project the study belongs in, and what the session and subject labels should be. The following rules are applied in the given order; for each of the three identifiers (project, subject, session), the first rule that provides a valid label is the one used.

  1. In the first pass over the DICOM metadata, DicomServer looks for all relevant metadata in the Patient Comments attribute (0010,4000). On many scanners, this is a freeform field that technicians can populate at the console. On Siemens' Syngo system, for example, this attribute holds the contents of the "Additional Information" box below the patient information section (which contains name, date of birth, etc.)

The identifiers should be entered as follows:
Project: Project_ID; Subject: Subject_ID; Session: Session_ID

The assignments should be separated by semicolons (as above), by commas, or by whitespace. All other content is ignored. The label should contain only letters, digits, and the underscore character. Project_ID should be the abbreviated name for an existing project in the associated XNAT.

  1. The second pass applies all the rules from pass 1 above to the Study Comments attribute (0032,4000). This is a another freeform field; on the Siemens Syngo console, it is labeled "Study comments."

  1. If a custom project identification rule is specified in the DicomServer configuration file (using the project_spec entry), it is used to attempt to find a project identifer. The format for the project_spec configuration entry is described in the Appendix.

  1. Next, DicomServer looks for each identifier by using the content of individual DICOM fields:

DICOM tag
Attribute name
XNAT field
(0008,1030)
Study Description
Project ID
(0010,0010)
Patient Name
Subject ID
(0010,0020)
Patient ID
Session ID

  1. If no valid project label has yet been found, DicomServer makes one last attempt to identify the project, using the content of Accession Number (0008,0050).

If, after all of the steps above, no match is found for an identifier, that identifier is left unfilled in the generated session XML document. Significantly, if no project could be identified, the session will be placed in the Unidentified prearchive, which can be viewed and modified only by adminstrator accounts. If the project is assigned, the session will be placed in the appropriate project prearchive.

If the subject label derived from the DICOM metadata does not match the label for an existing subject in the project, then subject information will need to be added manually in the XNAT web application.

Autoarchiving


When DicomServer has received a complete imaging session, it either places that session into the prearchive for review or immediately adds the session to the XNAT archive. The action taken is determined by the project settings: in the "Define Prearchive Settings" section of the "Manage" tab of the XNAT project overview page, the project owner can configure whether received sessions are placed in the prearchive or immediately archived. This per-project default can be overriden for individual sessions by adding instructions to either Patient Comments (0010,4000) or Subject Comments (0032,4000): the text AA:true tells DicomServer to autoarchive the session while AA:false specifies that the session should be placed in the prearchive. (Like the project, subject, and session identifiers, the autoarchiving flag should be separated from any other text in the attribute by whitespace or a comma or semicolon.)

Note that regardless of the project autoarchive settings or any AA: instructions, if a DICOM study has already been archived in a project (i.e., if a session in the archive has the same Study Instance UID), DicomServer will always place any additional, duplicate sessions for that project in the prearchive instead of autoarchiving.

Troubleshooting notes


The most useful tool for diagnosing and fixing problems with DicomServer is the log file.

It is sometimes useful to examine DicomServer's list of received sessions; this list is available as the /session resource from the DicomServer web service. For example, in the simple configuration example described above, the DicomServer session record could be viewed at http://my.xnat.org:8180/session. Individual session records can in turn be retrieved via their URLs, which are of the form http://my.xnat.org:8180/session/projects/Project/studies/Study-Instance-UID. All state for an session can be cleared from a running DicomServer by issuing a DELETE HTTP request to the individual session record URL. When users are having trouble uploading a DICOM study, especially via the XNAT upload applet, it may help to find and delete the corresponding DicomServer session. (All session state is discarded when DicomServer exits, so it is often easier to simply restart the program.)

The preferred way to exit DicomServer is to use the command arc-dcmstore stop; however, sometimes this command quietly fails to kill the DicomServer process. If you are trying to run arc-dcmstore start to start a new DicomServer, and you see an error message indicating that a TCP port is already in use, most likely a DicomServer instance is already running. In this situation, you will need to find and kill the stray process. (Rebooting the machine may be an attractive alternative.)

Appendix: Configuration Reference

Many aspects of DicomServer's behavior can be configured in an XML properties file. A sample properties file is provided in the DicomServer distribution (etc/DicomServer.xml). The properties that can be set are described here:

Properties for communication between DicomServer and XNAT
Key
Description
Required?
arcspec
path to XNAT archive specification file, located in the XNAT
cache directory and named archive_specification.xml
yes
xnat_url
URL by which DicomServer can access XNAT
yes
user
Username of XNAT user with admin privileges
yes
password
Password for XNAT admin user
yes

Properties for communication between DicomServer and C-STORE and/or web services clients
Key
Description
Required?
http_port
TCP Port on which DicomServer listens for web services; if unset, DicomServer does not run web services
no
xnat_public_url
URL by which clients can access XNAT; if unset, defaults to value of xnat_url
no
scp_public_host
Hostname for clients to access C-STORE service; defaults to local hostname
no
scp_public_port
Port for clients to access C-STORE service; defaults to port number specified in arc_dcmstore script (or on command line)
no
sessions_url
URL for clients to access DicomServer web services. This will be the externally visible hostname and port specification, plus /session
no

Properties configuring internal functions of DicomServer
Key
Description
Required?
project_spec
Configurable pattern for identifying project of incoming DICOM objects
no
log4j.*
Apache LOG4J configuration parameters
no

The project_spec configuration entry allows the XNAT administrator to add one rule for determining the project to which incoming datasets belong. If this entry is present, the attribute content is expected to be of the form:

(gggg,eeee):pattern

where gggg and eeee are the four-hex-digit group and element indices, respectively, of the DICOM attribute to be examined for project information; and pattern is a regular expression, in the same format used by java.util.regex.Pattern. The pattern should contain at least one capturing group, which will be used to extract the prospective project name. If the pattern contains exactly one capturing group, or if the project name is expected to be found in the first capturing group of the pattern, then the format above will suffice. Otherwise, the alternate format

(gggg,eeee):pattern:capturing-group-index

should be used.

The sample configuration file provided with the DicomServer distribution includes a simple example for a project_spec entry: (0008,1030):Project:s\*(\w+) This specification creates a rule that looks at the content of the DICOM attribute Study Description (0008,1030). If the value of that attribute equals the text "Project:" optionally followed by zero or more whitespace characters, then one more more "word" characters (i.e., letters, digits, and/or the underscore character), then the rule pattern matches the attribute value and will be used to attempt to try to determine the project to which the data belongs. The parenthesis around the \w+ pattern define a capturing group, and the text matching that portion of the attribute value will be used as a prospective project abbrevation.

For example, if our XNAT contains the projects ProjectA, ProjectB, and ProjectC; DicomServer is configured with the above rule; and none of the files received contain project information in Patient Comments or Study Comments; then the following values for Study Description lead to these results:

Study Description value
Matches project_spec pattern?
Capturing group content
Assigned project
No Project: here
no
N/A
undefined
Project: Project^A
no
N/A
undefined
Project: foo
yes
foo
undefined (no project named foo)
Project: ProjectA
yes
ProjectA
ProjectA