dcmrelay - Installation instructions

Release version 0.5, June 2010

This simple tutorial is intended to help in the installation and configuration of all the tools necessary to execute dcmrelay set of scripts that receive and relay dicom 3.0 medical images.

Step 1: Create local user

First you need to create a local user onto we will install all configuration files of the package:

$ su -

Create the new user. We wanted to name it 'dicom', but it could be changed to whatever you want, regarding that you change it in all the files it is referenced

# useradd -m dicom

Set a new password for the user dicom.

# passwd dicom

You can now logout from user root and login as user dicom.

From now on, we will assume you are the dicom user in his home directory:

~dicom >

Step 2: Install the dcmrelay set of scripts

Copy the dicom relay package dcm-relay-vx.x.tgz from the project web page to the dicom user home directory. Uncompress file dcm-relay-vx.x.tgz in dicom home directory.

$ tar -zxvf dcmrelay-vx.x.tgz

Alternatively, you may want to use the svn repository with the latest code, use the command:

$ svn co https://dcmrelay.svn.sourceforge.net/svnroot/dcmrelay/trunk dcmrelay

A directory dcmrelay should be created. You should have something like:

  • log
  • outbox
  • software
  • GPL
  • TODO
  • config.ini
  • dcmreceive
  • dcmrelay
  • mailsummary

If the directories log or outbox are not present, create them with

$ mkdir log

$ mkdir outbox

Step 3: Install OFFIS Dicom Toolkit (DCMTK)

The DCMTK offers many applications to use with medical images. This package is available at http://dicom.offis.de/dcmtk.php.en To install this package:

ftp://dicom.offis.de/pub/dicom/offis/software/dcmtk/dcmtk354/dcmtk- 3.5.4.tar.gz

Other method: If you don't have wget, you can download the files with ftp:

$ ftp dicom.offis.de

Connected to nero.offis.de.

220 Welcome to the FTP Server of the OFFIS Healthcare Information and Communication Systems Group.

Name (dicom.offis.de:user):

Type a 'anonymous' and your email address as password

FTP> binary

FTP> get /pub/dicom/offis/software/dcmtk/dcmtk354/dcmtk-3.5.4.tar.gz

FTP> bye

Unpack the OFFIS Dicom toolkit

$ tar -zxvf dcmtk-3.5.4.tar.gz

$ cd dcmtk-3.5.4

$ ./configure

$ make

$ su

# make install

Step 4: Customize dcmrelay

Now you can modify/edit necessary files to customize your configuration. config.ini is the configuration file. You should adapt it to your needs.

$ vi config.ini

In case you want to anonymize all images before they are relayed, set the following variable to 'YES'. This means that Patient name (0010,0010) in all dicom files will be replaced by a prefix, followed by the patient ID that comes in Dicom element (0010,0020). If Patient ID is '12345' and prefix is 'MYHOSPITAL', the anonymization process will replace the Patient Name element (0010,0010) with the value MYHOSPITAL12345.

If you choos to anonymize, please set the prefix that will replace the Patient Name.

Default anonymization is 'NO'.



Change the AE Title and port of your local Dicom relay utility. This information will be used when dicom relay send his identification to the remote destination.


The variable below will define the port where our dcmreceive process will listen for incoming Dicom images.


Define the possible remote destinations using the variables DESTx. You can have any number of these. The information should be enclosed in quotes and each field separated by a single space. Values are the 'IP address', 'port number', 'AE title' and 'destination name'. Each value cannot contain spaces.

DEST1="111.222.333.444 5010 DCM_DEST1_AET DEST1"

Usually you only need one destination, but if you send images to different locations in different periods of the day, you will need more. You would also need these variables to define a secondary image destination. You can use DEST1, DEST2, DEST3, … but not DEST0, as it is used for testing purposes.

The following variables define the destinations you want for different times of the day. You may want to send images to one destination during the morning, but to a different one in the afternoons. This is useful for teleradiology purposes. As default, PERIOD1 between from 08H00->19H59, PERIOD2 from 20H00->23H59, and PERIOD3 from 00H00->07H59.




You can also setup a second destination (optional) to also send the same images. Please note that in case of an error sending a file any of the destinations will result in dcmrelay sending again the same file to ALL destinations.

If you need a secondary destination in a certain period of the day, please uncomment the corresponding line, as in the example bellow.


You can repeat the same configuration for the other two defined periods. Variables that set destination for the period between midnight and 08h00 (PERIOD3) are PERIOD3_START, PERIOD3_END, PERIOD3_PRIDEST and PERIOD3_SECDEST (optional).

Every time images are relayed, someone can be notified by email. Choose 'YES' in the following variable if you want ot send notification emails.


Besides the mailbox, you can set the subject and header of the notification messages defining the variables bellow.

# This recipient will receive every relay notification


# This is the mail subject

SUBJECT="Images sent to teleradiology"

# Your company information

HEADER_MAIL="Hospital informatics division - informatics@myhospital.com"

Besides the notification emails, you can also send a summary report every month. Set here the destination mailbox.

# This recipient will receive summary reports every month


Save and exit from 'config.ini'

There are other configuration variables. These are less frequently changed:

The base directory is the directory where dcmrelay is installed. Probably you won't need to change this setting. Besides BASEDIR, there are also some more variables that define the outbox and log directories.


The location of the OFFIS Dicom toolkit. If you performed a default dcmtk installation, you do not need to change this variable. Otherwise you should make sure that OFFIS dicom tools binaries are installed in the directory pointed by DCMTK_DIR.


Step 5: Setup dcmreceive daemon

The file dcmreceive should be copied to /etc/init.d/, to start and stop the dcmreceive service at every system boot. For OpenSuSE, RedHat or Fedora Core (or any resemblance)

$ su

# cp ~dicom/dcmrelay/dcmreceive /etc/init.d/dcmreceive

# chmod 755 /etc/init.d/dcmreceive

# chkconfig --add dcmreceive

# chkconfig --level 345 on dcmreceive

For Debian Linux (or any resemblance)

$ su

# cp ~dicom/dcmrelay/dcmreceive /etc/init.d/dcmreceive

# chmod 755 /etc/init.d/dcmreceive

# ln -s /etc/init.d/dcmreceive /etc/rc3.d/S90dcmreceive

# ln -s /etc/init.d/dcmreceive /etc/rc1.d/K31dcmreceive

Now, its necessary to start the service.

$ su -

# /etc/init.d/dcmreceive start

You can now check the logfile at

$cat ~dicom/dcmrelay/log/dcmreceive.txt

If you want, you can test if the service is running:

# /etc/init.d/dcmreceive status

Step 6: Install the cron job

You need to create a cron to use the dcmrelay. This cron must be defined for the user dicom and you can modify or edit the cron to run when you want. Logon as user dicom, or change to user dicom, and issue

$ crontab -e

Insert these two lines

*/10 * * * * /home/dicom/dcmrelay/dcmrelay >> /home/dicom/dcmrelay/log/dcmrelay.txt

1 1 1 * 6 /home/dicom/dcmrelay/mailsummary >> /home/dicom/dcmrelay/log/dcmsummary.txt

This will set the relay service to be run every 10 minutes. It has proven to be a good setting. The relay will stop itself, if it notices any file receiveing in the last minutes. This is to assure that it will send a complete set of images to the destination Dicom peer.

In the example above, a monthly email report mailsummary runs at 01H01 AM every month.

Step 7: Have a nice cup of coffee

That's all folks!


If you find bugs or other problems with this software we would appreciate hearing about them. Please send an email to:


Please try to describe the problem in detail and if possible give a suggested fix.

  SourceForge Logo