Set Up a Help Desk System using OTRS on Ubuntu 20.04

This tutorial will walk you through the steps to set up a help desk system using free and open-source software on a Ubuntu 20.04. This will help you to receive and process requests from your users and customers using both the web interface and email.

Open source ticket request system (OTRS) also known a help desk and IT service management system. This software is programmed in Perl, supports a variety of databases including (MySQL/MariaDB, PostgreSQL, Oracle, etc.), and can integrate with any authentication mechanism such as LDAP, Active directory, freeIPA for centralized authentication.

Prerequisites

To follow this guide, you will need one (physical or virtual) machine installed with Ubuntu 20.04 having a non-root user with sudo privileges.

Install Apache

You can install the Apache webserver with below command:

sudo apt -y install apache2 apache2-ssl-dev apache2-dev

Install Perl Modules

Because OTRS is written in Perl, it uses a number of Perl modules. Some modules are only needed for optional functionality, such as communication with other databases or handling mail with specific character sets; others are necessary for the program to work.

To install the missing modules, type or copy the following command and paste it on your Ubuntu terminal to install:

sudo apt -y install libapache2-mod-perl2 libdbd-mysql-perl libtimedate-perl libnet-dns-perl libnet-ldap-perl libio-socket-ssl-perl libpdf-api2-perl libsoap-lite-perl libtext-csv-xs-perl libjson-xs-perl libapache-dbi-perl libxml-libxml-perl libxml-libxslt-perl libyaml-perl libarchive-zip-perl libcrypt-eksblowfish-perl libencode-hanextra-perl libmail-imapclient-perl libtemplate-perl libdatetime-perl libcrypt-ssleay-perl libdbd-odbc-perl libdbd-pg-perl libauthen-ntlm-perl libmoo-perl zip unzip

Install MariaDB

You can install MariaDB using the below command:

sudo apt -y install mariadb-server mariadb-client

Secure MariaDB

When the installation is complete, run a simple security script that comes pre-installed with MariaDB which will remove some dangerous defaults and lock down access to your database system. Start the interactive script by running:

sudo mysql_secure_installation

You will see the following prompts on your terminal:

NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
      SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!

In order to log into MariaDB to secure it, we'll need the current
password for the root user.  If you've just installed MariaDB, and
you haven't set the root password yet, the password will be blank,
so you should just press enter here.

Enter current password for root (enter for none):
OK, successfully used password, moving on...

Setting the root password ensures that nobody can log into the MariaDB
root user without the proper authorisation.

Set root password? [Y/n] y
New password:
Re-enter new password:
Password updated successfully!
Reloading privilege tables..
 ... Success!


By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

Download OTRS

OTRS is available in Ubuntu's package manager, but the official documentation suggests installing the most latest release from the source.

Download the source archive with the wget command. For this guide, we will download current release 6.0.24; you can find the latest available version on the OTRS download page.

cd ~
wget https://ftp.otrs.org/pub/otrs/otrs-6.0.28.zip

sudo unzip -d /opt otrs-6.0.28.zip
sudo mv /opt/otrs-6.0.28/ /opt/otrs

Now that you have OTRS and its dependencies installed on your server, you can configure OTRS to use Apache as the web server and MariaDB as the database.

Configure OTRS

You will need to create a user called "otrs" to run the otrs function using the below command:

sudo useradd -r -U -d /opt/otrs -c 'OTRS user' otrs -s /bin/bash

OTRS comes with a default config file /opt/otrs/Kernel/Config.pm.dist, you can activate this by copying it without the .dist filename extension:

sudo cp /opt/otrs/Kernel/Config.pm.dist /opt/otrs/Kernel/Config.pm

Now run the otrs.SetPermissions.pl script. It will detect the correct user and group settings and set the file and directory permissions for OTRS.

sudo /opt/otrs/bin/otrs.SetPermissions.pl

Next, activate the Apache configuration file and make sure it is loaded after all other configurations. To do this, make a symbolic link with the zzz_ prefix:

sudo ln -s /opt/otrs/scripts/apache2-httpd.include.conf /etc/apache2/sites-enabled/zzz_otrs.conf

OTRS requires a few Apache modules to be active for optimal operation. You can activate them via the tool a2enmod. Although some of these have already been enabled, it is a good idea to check them all:

sudo a2enmod perl
sudo a2enmod headers
sudo a2enmod deflate
sudo a2enmod filter

These modules enable Apache to work with Perl, control HTTP headers, compress server output, and configure output content filters.

Restart Apache webserver to apply new configurations:

sudo systemctl restart apache2

You will need to change some of the database configuration settings. Edit the MariaDB configuration file in your preferred text editor:

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add the following parameters within the [mysqld] section:

innodb_log_file_size = 512M
max_allowed_packet      = 64M

Save and close the file when you are finished.

Restart MariaDB to apply changes:

sudo systemctl restart mariadb

At this stage, run the below script to verify if you are missing any Perl modules required to run otrs:

sudo /opt/otrs/bin/otrs.CheckModules.pl

You will get the output similar to below which says all is well. If you see any missing module other than DBD::Oracle, you must install them before proceeding the next step.

We do not need DBD::Oracle module as we are running the MariaDB database, so you can safely ignore it and move to the next step.

Create a Database

You will need to create a database for OTRS like below:

sudo mysql -uroot -p

On MariaDB [(none)]>: prompt, type below, make sure you replace password with a strong password of your choice:

CREATE DATABASE otrs CHARACTER SET utf8;
create user 'otrs'@'localhost' identified by 'Password';
grant all privileges on otrs.* to 'otrs'@'localhost';
flush privileges;
exit

Restart MariaDB to apply changes:

sudo systemctl restart mariadb

Now edit /opt/otrs/Kernel/Config.pm file:

sudo nano /opt/otrs/Kernel/Config.pm

Replace the some-pass text with your otrs database user's password:

$Self->{DatabasePw} = 'Password';

Save and close the file when you are finished.

Access OTRS Web Installer

Open up your preferred web browser and navigate to http://your_server_ip/otrs/installer.pl, you will see a welcome screen like below.

Click Next

Accept License and Continue



Select MySQL then click Use an existing database for OTRS

Click Next

Provide database credentials you created in (create a database) step, click Check database settings

You will see a Database check successful like below.

Click Next

It will take a few moments to complete.

Click Next

Next, provide the following required system settings:

System FQDN
AdminEmail
Organization

Leave all other options at their default values:

Click Next.

Now you will land on the Mail Configuration page. In order to be able to send and receive emails using otrs, you have to configure a mail account. You can safely skip this section if you want to configure it later.

The OTRS installation is now complete; you will see a Finished page with a link to the admin panel after the Start page and the credentials of the OTRS superuser after that. Make sure you write down the generated password for the root@localhost user and the URL for the Start page.

The only thing left after a successful installation is to start the OTRS daemon and activate its cronjob.

Bring up the terminal you are using to access your Ubuntu 20.04 server. The OTRS daemon is responsible for handling any asynchronous and recurring tasks in OTRS.

You can start the otrs daemon like below:

sudo perl /opt/otrs/bin/otrs.SetPermissions.pl

sudo su - otrs -c "/opt/otrs/bin/otrs.Daemon.pl start"

You will see the following output:

Manage the OTRS daemon process.
Daemon started

There are two default cron files in the /opt/otrs/var/cron/ directory:

cd /opt/otrs/var/cron

These cron files are used to make sure that the OTRS daemon is running. Activate them by copying them without the .dist filename extension.

sudo cp aaa_base.dist aaa_base
sudo cp otrs_daemon.dist otrs_daemon

To schedule these cron jobs, use the script Cron.sh with the otrs user:

sudo perl /opt/otrs/bin/otrs.SetPermissions.pl

sudo su - otrs -c "/opt/otrs/bin/Cron.sh start"

Next, we will log in to the otrs administrator web interface by navigating to http://your_server_ip/otrs/index.pl and perform the below tasks.

Secure OTRS

Now that you have a fully functional OTRS, but it's not secure to use the superuser account. We'll create a new agent. In OTRS, agents are users who have rights to the various functions of the system. In this example, we will use a single agent who has access to all functions of the system.

To get started, log in as the  root@localhost, and enter the password you copied from the web installer step, click Login.

You will see the main dashboard. It contains several widgets which show different information about tickets, statistics, news, etc. You can freely rearrange them by dragging or switch their visibility in settings.

First, we will create a new agent.

To do this, follow the link by clicking on the red message at the top of the screen that reads Don't use the Superuser account to work with OTRS 6! Create new Agents and work with these accounts instead. This will bring you to the Agent Management screen.

Click the Add agent button. This will bring you to the Add Agent screen. Most of the default options are fine. Fill in the first name, last name, username, password, and email fields. Record the username and password for future login. Submit the form by clicking the Save button.

Next, change the group relations for the new agent. Because your agent will also be the administrator, you can give it a full read and write access to all groups. To do this, click the checkbox next to RW all the way on the right, under Change Group Relations for Agent.



Finally, click Save and finish.

Now, log out and log back in again using the newly created account. You can find the Logout link by clicking on the avatar picture in the top left corner.



Once you have logged back in, you can customize your agent's preferences by clicking on Personal preferences in the avatar menu. There you can change your password, choose the interface language, configure setup notifications and favorite queues, change interface skins, etc.

Once you have logged in as your new agent and configured the account to your liking, the next step is to configure the inbound mail options to generate tickets from incoming emails.

Configure OTRS Inbound Mail

Customers have two ways to forward new tickets to OTRS: via the customer front-end or by sending an email. In order to receive customer's messages, you need to set up a POP or IMAP account. We will use a Gmail account as an example for OTRS configuration.

Navigate to the Admin tab by clicking on Admin in the top menu. Then find the PostMaster Mail Accounts option and click on it. Press the Add Mail Account button to set up a new mailbox.



On the Add Mail Account screen, select IMAPS for Type. For Username, type in your email address, and Password. Leave all other options as default. Click Save.

Next, send a test email from an external email account to your dedicated OTRS email account. The mail will be fetched every 10 minutes by the OTRS daemon, but you can force receipt by clicking the Fetch mail link.

As a result, you will see a new ticket.



Now you are ready to accept tickets from customers via email. Next, you will go through the process of creating a ticket through the customer front-end.

Configure OTRS Customer Interface

The second way for a customer to create a ticket is through the OTRS front-end. In this step, you will walk through this process to make sure this ticket creation method is set up.

The customer front-end is located at http://your_server_ip/otrs/customer.pl. Navigate to it in a web browser. You can create a customer account there and submit a ticket using the GUI.

Use the Sign up now link to open the registration form and fill out the below form and press the Create button.




You will see a message like this:

New account created. Sent login information to username@youremail.com. Please check your email.

Check your inbox for the message from the OTRS. You will see a message with the new account credentials:

Hi example,

You or someone impersonating you has created a new OTRS account for
you.

Full name: example
User name: example@youremail.com
Password : user_password

You can log in via the following URL. We encourage you to change your password via the Preferences button after logging in.

http://your_server_ip/otrs/customer.pl

Now, use the provided credentials to access the customer front-end and create another ticket. All new tickets created using the customer front-end will immediately appear on the agent's dashboard:

On the agent dashboard, you can see the information on all current tickets: their status (new, opened, escalated, etc.), their age (the time elapsed from the moment when the ticket was received), and subject.

You can click on the ticket number (in the TICKET# column) to view its details. The agent can also take action on the ticket here, like changing its priority or state, moving it to another queue, closing it, or adding a note.

You have now successfully set up your OTRS account.

Wrapping up

In this guide, you have installed and configured OTRS and created test help desk tickets. Now you can accept and process requests from your users and customers using both the web interface and email.