Introduction

OTOBO is an open source ticket request system with many features to manage customer telephone calls and emails. It is distributed under the GNU General Public License (GPL) and is tested on various Linux platforms.

About This Manual

This manual is intended for use by system administrators. The chapters describe the installation and updating of the OTOBO software.

There is no graphical user interface for installation and updating. System administrators have to follow the steps described in the following chapters.

All console commands look like username> command-to-execute. Username indicates the user account of the operating system, which need to use to execute the command. If a command starts with root>, you have to execute the command as a user with root permissions. If a command starts with otobo>, you have to execute the command as the user created for OTOBO.

Warning

Do not select username> when you copy the command and paste it to the shell. Otherwise you will get an error.

We assume that OTOBO will be installed to the directory /opt/otobo. If you want to install OTOBO to a different location, then you have to change the path in the commands or create a symbolic link to this directory.

root> ln -s /path/to/otobo /opt/otobo

Hardware and Software Requirements

The OTOBO web application can be installed on Linux and other Unix derivatives, e.g., OpenBSD or FreeBSD. Running OTOBO on Microsoft Windows is not supported.

The web application uses a relational database as backend. So, to run OTOBO, you’ll need to run at least a web server and a database server. The web server and the database server may be installed either on the same or on different hosts.

Alternatively, OTOBO can also run under Docker. When running under Docker, the web and the database server are already included in the setup. Support for deployment with Kubernetes is under development.

The OTOBO web application requires Perl along with additional Perl modules from CPAN. The modules can be installed either with a Perl package manager or via the package manager of your operating system (rpm, yast, apt). There is a console command for checking the module dependencies:

sudo -u otobo /opt/otobo/bin/otobo.CheckModules.pl --inst

If some packages are missing, you can get an install command for your operating system by running the script with the --list option.

sudo -u otobo /opt/otobo/bin/otobo.CheckModules.pl --list | more

The listed commands should then be executed with root privileges.

The output of the module check script shows the installed packages and the version numbers. Missing modules are marked with a comment.

Required packages:
  o Archive::Tar.....................ok (v2.32)
  o Archive::Zip.....................ok (v1.67)
  o Const::Fast......................ok (v0.014)
  o Date::Format.....................ok (v2.24)
  o DateTime.........................ok (v1.51)
    o DateTime::TimeZone.............ok (v2.38)
  o Convert::BinHex..................ok (v1.125)
  o DBI..............................ok (v1.643)
  o Digest::SHA......................ok (v6.02)
  o File::chmod......................ok (v0.42)
  o List::AllUtils...................ok (v0.15)
  o LWP::UserAgent...................ok (v6.26)
  o Moo..............................ok (v2.003006)
  o namespace::autoclean.............ok (v0.29)
  o Net::DNS.........................ok (v1.22)
  o Net::SMTP::SSL...................ok (v1.04)
  o Path::Class......................ok (v0.37)
  o Sub::Exporter....................ok (v0.987)
  o Template::Toolkit................ok (undef)
  o Template::Stash::XS..............ok (undef)
  o Text::CSV........................ok (v1.95)
  o Text::Trim.......................ok (v1.04)
  o Time::HiRes......................ok (v1.9760)
  o Try::Tiny........................ok (v0.30)
  o URI..............................ok (v1.71)
  o XML::LibXML......................ok (v2.0207)
  o YAML::XS.........................ok (v0.81)
  o Unicode::Collate.................ok (v1.27)
  o CGI::PSGI........................ok (v0.15)
  o DBIx::Connector..................ok (v0.56)
  o Path::Class......................ok (v0.37)
  o Plack............................ok (v1.0047)
  o Plack::Middleware::ForceEnv......ok (v0.02)
  o Plack::Middleware::Header........ok (v0.04)
  o Plack::Middleware::Refresh.......ok (undef)
  o Plack::Middleware::ReverseProxy..ok (v0.16)
  o Plack::Middleware::Rewrite.......ok (v2.101)
  o SOAP::Transport::HTTP::Plack.....ok (v0.03)

Recommended features for setups using apache:
  o ModPerl::Util....................ok (v2.000011)

Database support (installing one is required):
  o DBD::mysql.......................ok (v4.050)

Various features for additional functionality:
  o Encode::HanExtra.................ok (v0.23)
  o Net::LDAP........................ok (v0.66)
  o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
  o XML::LibXSLT.....................ok (v1.99)
  o XML::Parser......................ok (v2.46)

Features enabling communication with a mail-server:
  o Net::SMTP........................ok (v3.11)
  o Mail::IMAPClient.................ok (v3.42)
  o Authen::SASL.....................ok (v2.16)
  o Authen::NTLM.....................ok (v1.09)
  o IO::Socket::SSL..................ok (v2.067)

Optional features which can increase performance:
  o JSON::XS.........................ok (v4.02)
  o Text::CSV_XS.....................ok (v1.41)

Required packages if you want to use PSGI/Plack (experimental and advanced):
  o Gazelle..........................ok (v0.49)
  o Linux::Inotify2..................ok (v2.2)
  o Plack::App::File.................ok (undef)

Hardware Requirements

Hardware requirements highly depend on the usage of OTOBO. OTOBO can be used to process a few tickets per month or to process hundreds of tickets per day. The storage requirement also depends on the number of tickets and size of attachments.

We recommend using a machine for testing purposes with at least:

small CPU

4 GB RAM

10 GB storage

We recommend using a machine for production purpose with at least:

3 GHz Xeon or comparable CPU

8 GB RAM (16 GB recommended)

40 GB storage

Note

Hardware requirements depend on the usage of OTOBO. Please contact your OTOBO consultant before deploying any hardware.

Software requirements

Perl

Perl 5.26.0 or higher

Perl packages listed by /opt/otobo/bin/otobo.CheckModules.pl --list console command

Web Server

Nginx HTTP Server Version 1.24 or higher

Databases

MariaDB 10.11 or higher (recommended)

MySQL 8.4 or higher

PostgreSQL 13 or higher

Oracle 19c or higher

Optional

Elasticsearch 7.x (fast search function for live previews)

Redis (caching)

Web browsers

Apple Safari

Google Chrome

Microsoft Edge

Mozilla Firefox

Any other modern web browser with JavaScript support

OTOBO Installation

This chapter describes the installation and basic configuration of the central OTOBO framework. Currently, the recommended installation method is using Docker and Docker Compose. However, it is also possible to install OTOBO manually on a standard Linux server directly. Please refer to any subsection for your preferred installation method.

Contents

OTOBO Installation Docker

Requirements

Installation

1. Clone the otobo-docker Repository

2. Create an Initial .env File

3. Configure the Password for the Database Admin User

4. Set up a Volume with SSL Configuration for the Nginx Webproxy (optional)

5. Start the Docker Containers with Docker Compose

6. Install and Start OTOBO

Additional Technical Information

List of Docker Containers

Overview over the Docker Volumes

Docker Environment Variables

Advanced Topics

Custom Configuration of the Nginx Webproxy

Single Sign-On Using the Kerberos Support in Nginx

Choosing non-standard Ports

Skip Startup of Specific Services

Prepare Offline Installation

Customizing OTOBO Docker Compose

Customizing the OTOBO Docker Image

Building Local Images

Automatic Installation

List of Useful Commands

Resources

OTOBO Installation on Ubuntu

Step 1: Unpack and Install OTOBO

Step 2: Install Additional Programs and Perl Modules

Step 3: Create the OTOBO User

Step 4: Activate the Default Configuration File

Step 5: Configure Systemd Services for OTOBO

Step 6: Configure the Nginx Web Server

Configure Nginx without SSL Support

Configure Nginx with SSL Support

Step 7: Set File Permissions

Step 8: Setup the Database

Step 9: Setup Elasticsearch

Step 10: Basic System Configuration

Step 11: First Login

Step 12: Start the OTOBO Daemon

Step 13: Setup Bash Auto-Completion (optional)

Step 14: Further Information

OTOBO Installation on RHEL

Preparation: Disable SELinux when it is Installed and Enabled

Step 1: Unpack and Install OTOBO

Step 2: Create the OTOBO User

Step 3: Install Additional Programs and Perl Modules

Option A: Install packages from CPAN

Option B: Deploy Pre-built Packages

Step 4: Activate the Default Configuration File

Step 5: Configure systemd Services for OTOBO

Step 6: Configure the Nginx Web Server

Configure Nginx without SSL Support

Configure Nginx with SSL Support

Step 7: Set File Permissions

Step 8: Setup the Database

Step 9: Setup Elasticsearch

Elasticsearch Module Installation

Elasticsearch Configuration

Step 10: Basic System Configuration

Step 11: First Login

Step 12: Start the OTOBO Daemon

Step 13: Setup Bash Auto-Completion (optional)

Step 14: Further Information

OTOBO Installation Docker

With the dockerized OTOBO deployment you can get your personal OTOBO instance up and running within minutes. All of OTOBO’s dependencies are already included in the provided collection of Docker images:

db: MariaDB is set up as the default database.

elastic: Elasticsearch is set up for the OTOBO power search.

redis: Redis is enabled for fast caching.

web: Gazelle is used as fast Perl webserver.

nginx: Nginx is used as optional reverse proxy for HTTPS support.

We think that this setup is the perfect environment for an OTOBO installation.

Requirements

The minimal versions of required software, that have been tested, are listed here:

Docker 19.03.13

Docker Compose v2

Git 2.17.1

For Ubuntu 24.04 LTS these commands install the required packages:

sudo apt update
sudo apt install docker.io docker-compose-v2 git

Installation

The following instructions assume that all requirements are met and you have a working Docker environment. We assume a user for with the required permissions for running Docker commands. If no dedicated user is setup, use sudo.

1. Clone the otobo-docker Repository

The Docker images will eventually be fetched from the repository https://hub.docker.com. But there are some setup and command files that need to be cloned from the otobo-docker Github repository. Make sure that you specify the tag that corresponds to the current patch level version of OTOBO. For example, when OTOBO 11.0.2 is the current version then please use the tag rel-11_0_2.

Note

For these instructions we chose /opt/otobo-docker as the working dir. You may choose this path freely, but may have to adjust commands in this manual accordingly.

cd /opt
git clone https://github.com/RotherOSS/otobo-docker.git --branch <TAG>
cd otobo-docker    # change into the git
ls                 # just a sanity check, for example the file README.md should exist

2. Create an Initial .env File

The Docker Compose configuration file .env is your primary interface for managing your installation of OTOBO. This file must first be created and then be adapted by yourself. In order to simplify the task, several example files are provided that may be used as starting point. Which sample file it the best fit depends on your use case. In most cases the decision is between .docker_compose_env_http and .docker_compose_env_https, depending on whether TLS must be supported or not. The other files are for more specialized use cases.

.docker_compose_env_http

The OTOBO web app provides HTTP.

.docker_compose_env_https

The OTOBO web app provides HTTPS by running Nginx as a reverse proxy webserver.

.docker_compose_env_https_custom_nginx

Like *.docker_compose_env_https but with support for a custom Nginx configuration.

.docker_compose_env_https_kerberos

Like .docker_compose_env_https but with sample setup for single sign on. Note that Kerberos support is still experimental.

.docker_compose_env_http_selenium and .docker_compose_env_https_selenium

These are used only for development when Selenium testing is activated.

Note

Use ls -a for listing the hidden sample files.

By default OTOBO is served on the standard ports, 443 for HTTPS and 80 for HTTP. When HTTPS is activated then the OTOBO web application actually still runs with HTTP. HTTPS support is achieved by an additional reverse proxy, which is implemented as a Nginx service.

For the following commands we assume that HTTPS should be supported.

cd /opt/otobo-docker
cp -p .docker_compose_env_https .env # or .docker_compose_env_http for HTTP

3. Configure the Password for the Database Admin User

Change the following setting inside your .env file:

OTOBO_DB_ROOT_PASSWORD=<your_secret_password>

The password for the database admin user may be chosen freely. The database admin user is needed to create the database user otobo and the database schema otobo. OTOBO will actually use the dedicated database user otobo.

4. Set up a Volume with SSL Configuration for the Nginx Webproxy (optional)

This step may be skipped when OTOBO should be available only via HTTP. Nginx needs for SSL encryption a certificate and a private key.

Note

To specify a CA chain with a certificate in Nginx, it is necessary to copy the CA chain file with the actual certificate into a file.

The certificate and the private key are stored in a volume, so that they can be used by Nginx later on. In any case the volume needs to be generated manually, and we need to copy the certificate and key to the volume:

docker volume create otobo_nginx_ssl
otobo_nginx_ssl_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl)
echo $otobo_nginx_ssl_mp  # just a sanity check
cp /PathToYourSSLCert/ssl-cert.crt /PathToYourSSLCert/ssl-key.key $otobo_nginx_ssl_mp

The names of the copied files need to be set in our newly created .env file, e.g., OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/ssl-cert.crt and OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/ssl-key.key Please adapt only the name of the files as the path /etc/nginx/ssl/ is hard coded in the Docker image.

5. Start the Docker Containers with Docker Compose

Now we start the Docker containers using docker compose. By default the Docker images will be fetched from https://hub.docker.com/u/rotheross.

docker compose up --detach

To verify that the six required services (five in the case of HTTP only) are actually running, type:

docker compose ps
docker volume ls

6. Install and Start OTOBO

Run the OTOBO installer at http://yourIPorFQDN/otobo/installer.pl.

Note

Please configure OTOBO inside the installer with a new MySQL database. As MySQL database root password please use the password you configured in the variable OTOBO_DB_ROOT_PASSWORD of your .env file. Please leave the value db for the MySQL hostname untouched.

Have fun with OTOBO!

Note

To change to the OTOBO directory, inside the running container, to work on command line as usual, you can use the following Docker command: docker compose exec web bash.

Additional Technical Information

This section gives some more technical insight into what is happening under the hood.

List of Docker Containers

Container otobo-web-1

OTOBO webserver on internal port 5000.

Container otobo-daemon-1

OTOBO daemon. The OTOBO daemon is started and periodically checked.

Container otobo-db-1

Run the database MariaDB on internal port 3306.

Container otobo-elastic-1

Elasticsearch on the internal ports 9200 and 9300.

Container otobo-redis-1

Run Redis as caching service.

Optional container otobo-nginx-1

Run nginx as reverse proxy for providing HTTPS support.

Overview over the Docker Volumes

The Docker volumes are created on the host for persistent data. These allow starting and stopping the services without losing data. Keep in mind that containers are temporary and only data in the volumes is permanent.

otobo_opt_otobo

contains /opt/otobo in the container web and daemon.

otobo_mariadb_data

contains /var/lib/mysql in the container db.

otobo_elasticsearch_data

contains /usr/share/elasticsearch/data in the container elastic.

otobo_redis_data

contains data for the container redis.

otobo_nginx_ssl

contains the TLS files, certificate and private key, must be initialized manually.

Docker Environment Variables

In the instructions we did only minimal configuration. But the file .env allows to set more variables. Here is a short list of the most important environment variables. Note that more environment variables are supported by the base images.

MariaDB settings

OTOBO_DB_ROOT_PASSWORD

The root password for MariaDB. This setting is required for running the service db.

Elasticsearch settings

Elasticsearch needs some settings for productive environments. Please read https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites for detailed information.

OTOBO_Elasticsearch_ES_JAVA_OPTS

Example setting: TOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m Please adjust this value for production environments to a value up to 4g.

Webserver settings

OTOBO_WEB_HTTP_PORT

Set in case the HTTP port should deviate from the standard port 80. When HTTPS is enabled, the HTTP port will redirect to HTTPS.

Nginx webproxy settings

These setting are used when HTTPS is enabled.

OTOBO_WEB_HTTP_PORT

Set in case the HTTP port should deviate from the standard port 80. Will redirect to HTTPS.

OTOBO_WEB_HTTPS_PORT

Set in case the HTTPS port should deviate from the standard port 443.

OTOBO_NGINX_SSL_CERTIFICATE

SSL cert for the nginx webproxy. Example: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt

OTOBO_NGINX_SSL_CERTIFICATE_KEY

SSL key for the nginx webproxy. Example: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Nginx webproxy settings for Kerberos

This settings are used by Nginx when Kerberos is used for single sign on.

OTOBO_NGINX_KERBEROS_KEYTAB

Kerberos keytab file. The default is /etc/krb5.keytab.

OTOBO_NGINX_KERBEROS_CONFIG

Kerberos config file. The default is /etc/krb5.conf, usually generated from krb5.conf.template.

OTOBO_NGINX_KERBEROS_SERVICE_NAME

Kerberos Service Name. It is not clear where this setting is actually used anywhere.

OTOBO_NGINX_KERBEROS_REALM

Kerberos REALM. Used in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_KDC

Kerberos kdc / AD Controller. Used in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_ADMIN_SERVER

Kerberos Admin Server. Used in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN

Kerberos Default Domain. Used in /etc/krb5.conf.

NGINX_ENVSUBST_TEMPLATE_DIR

Provide a custom Nginx config template dir. Gives extra flexibility.

Docker Compose settings

These settings are used by Docker Compose directly.

COMPOSE_PROJECT_NAME

The project name is used as the prefix for the volumes and containers. By default this prefix is set to otobo, resulting in container names like otobo-web-1 and otobo-db-1. Change this name when you want to run more then one instance of OTOBO on the same server.

COMPOSE_PATH_SEPARATOR

Separator for the value of COMPOSE_FILE

COMPOSE_FILE

Use docker-compose/otobo-base.yml as the base and add the wanted extension files. E.g., docker-compose/otobo-override-http.yml or docker-compose/otobo-override-https.yml.

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, …

Used for specifying alternative Docker images. Useful for testing local builds or for using updated versions of the images.

Advanced Topics

Custom Configuration of the Nginx Webproxy

The container otobo-nginx-1 provides HTTPS support by running Nginx as a reverse proxy. The Docker image that runs in the container is composed of the official Nginx Docker image, https://hub.docker.com/_/nginx, along with a OTOBO specific configuration of Nginx.

The default OTOBO specific configuration can be found within the Docker image at /etc/nginx/template/otobo_nginx.conf.template. Actually, this is only a template for the final configuration. There is a process, provided by the Nginx base image, that replaces the macros in the template with the corresponding environment variable. This process runs when the container starts up. In the default template file, the following macros are used:

OTOBO_NGINX_SSL_CERTIFICATE

For configuring SSL.

OTOBO_NGINX_SSL_CERTIFICATE_KEY

For configuring SSL.

OTOBO_NGINX_WEB_HOST

The internally used HTTP host.

OTOBO_NGINX_WEB_PORT

The internally used HTTP port.

See step 4. for how this configuration possibility was used for setting up the SSL certificate.

When the standard macros are not sufficient, then the customization can go further. This can be achieved by replacing the default config template with a customized version. It is best practice to not simple change the configuration in the running container. Instead we first create a persistent volume that contains the custom config. Then we tell the otobo-nginx-1 to mount the new volume and to use the customized configuration.

First comes generation of the new volume. In these sample commands, we use the existing template as a starting point.

# stop the possibly running containers
cd /opt/otobo-docker
docker compose down

# create a volume that is initially not connected to otobo-nginx-1
docker volume create otobo_nginx_custom_config

# find out where the new volume is located on the Docker host
otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
echo $otobo_nginx_custom_config_mp  # just a sanity check
ls $otobo_nginx_custom_config_mp    # another sanity check

# copy the default config into the new volume
docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest-11_0
docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx.conf.template $otobo_nginx_custom_config_mp # might need 'sudo'
ls -l $otobo_nginx_custom_config_mp/otobo_nginx.conf.template # just checking, might need 'sudo'
docker rm tmp-nginx-container

# adapt the file $otobo_nginx_custom_config_mp/otobo_nginx.conf.template to your needs
vim $otobo_nginx_custom_config_mp/otobo_nginx.conf.template

After setting up the volume, the adapted configuration must be activated. The new volume is set up in docker-compose/otobo-nginx-custom-config.yml. Therefore, this file must be added to COMPOSE_FILE. Then Nginx must be directed to use the new configuration. This is done by setting NGINX_ENVSUBST_TEMPLATE_DIR in the environment. In order to achieve this, uncomment or add the following lines in your .env file:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml:docker-compose/otobo-nginx-custom-config.yml
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom

The changed Docker Compose configuration can be inspected with:

docker compose config | more

Finally, the containers can be started again:

docker compose up --detach

See also the section “Using environment variables in Nginx configuration (new in 1.19)” in https://hub.docker.com/_/nginx.

Single Sign-On Using the Kerberos Support in Nginx

Short Description

For enabling authentication with Kerberos please base you .env file on the sample file .docker_compose_env_https_kerberos. This activates the special configuration in docker-compose/otobo-override-https-kerberos.yml. This Docker compose configuration file selects a Nginx image that supports Kerberos. It also passes some Kerberos specific settings as environment values to the running Nginx container. These settings are listed above.

As usual, the values for these setting can be specified in the .env file. Most of these setting will be used as replacement values for the template https://github.com/RotherOSS/otobo/blob/rel-11_0/scripts/nginx/kerberos/templates/krb5.conf.template . The replacement takes place during the startup of the container. In the running container the adapted configuration will be available in /etc/krb5.conf.

Providing an user specific /etc/krb5.conf file is still possible. This can be done by mounting a volume that overrides /etc/krb5.conf in the container. This can be achieved by setting OTOBO_NGINX_KERBEROS_CONFIG in the .env file and by activating the mount directive in docker-compose/otobo-override-https-kerberos.yml.

/etc/krb5.keytab is always installation specific and must therefore always be mounted from the host system.

Kerberos SSO Installation Tutorial

Kerberos Single Sign On

Choosing non-standard Ports

Per default the ports 443 and 80 serve HTTPS and HTTP respectively. There can be cases where one or both of these ports are already used by other services. In these cases the default ports can be overridden by specifying OTOBO_WEB_HTTP_PORT and OTOBO_WEB_HTTPS_PORT in the .env file.

Skip Startup of Specific Services

The current Docker compose setup start five, six when HTTPS is activated, services. But there are valid use cases where one or more of these services are not needed. The prime example is when the database should not run as a Docker service, but as an external database. Unfortunately there is no dedicated Docker compose option for skipping specific services. But the option --scale can be abused for this purpose. So for an installation with an external database the following command can be used:

docker compose up --detach --scale db=0

Of course the same goal can also be achieved by editing the file docker-compose/otobo-base.yml and removing the relevant service definitions.

Prepare Offline Installation

Please download the latest version of otobo-docker on a system that has internet access and where docker is installed. Then navigate to the following folder otobo-docker/docker-compose.

cd otobo-docker/docker-compose

Now you can run the following command to download all Docker images from a specific file, in my example I use the otobo-base.yml.

for i in $(cat otobo-base.yml| grep image:| cut -d":" -f3,4 | sed -e "s/-//1" -e"s/\}//g"); do docker pull $i; docker save $i -o $(echo $i|sed "s/\//-/g").docker; done

After that, the images (.docker) are located in the docker-compose folder and can be uploaded to the target system via, e.g, SCP.

On the offline target system, go to the folder where the docker images are stored. And enter the following command to import them one by one. In the following example the Mariadb image is imported:

docker load --input mariadb:10.5.docker

Customizing OTOBO Docker Compose

Instead of editing the files under docker-compose/* and risking to overwrite your own options with the next update of the otobo-docker folder, it is advisable to create an extra YAML file where the specific services are overwritten with additional options.

A common example would be to make the database container accessible from the outside via port 3306. For this you could create an extra docker compose file that looks like:

$ cat custom_db.yml
services:
  db:
    ports:
      - "0.0.0.0:3306:3306"

Now we have to tell Docker Compose to include our new file. For this you have to add your YAML file to the COMPOSE_FILE variable in the .env file, for example:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-http.yml:custom_db.yml

Now we can use docker compose to recreate our container

docker compose stop # if otobo is running
docker compose up -d

With this procedure you can customize any service or volumes.

Customizing the OTOBO Docker Image

Customization can be done in the external volume otobo_opt_otobo which corresponds to the directory /opt/otobo in the Docker image. This works, e.g., for local Perl modules which can be installed into /opt/otobo/local. Here is an example that installs the not very useful CPAN module Acme::123.

docker compose exec web cpanm -l local Acme::123
#  --> Working on Acme::123
#  Fetching http://www.cpan.org/authors/id/N/NA/NATHANM/Acme-123-0.04.zip ... OK
#  Configuring Acme-123-0.04 ... OK
#  Building and testing Acme-123-0.04 ... OK
#  Successfully installed Acme-123-0.04
#  1 distribution installed

The nice thing of this approach is that the Docker image itself does not have to be modified.

Installing extra Debian packages is a little bit trickier. One approach is to create a custom Dockerfile and use the OTOBO image as the base image. Another approach is to create a modified image directly from a running container. This can be done with the command docker commit, https://docs.docker.com/engine/reference/commandline/commit/. A nice write-up of that process is available at https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.

But for the latter approach there are two hurdles to overcome. First, the image otobo runs per default as the user otobo with the UID 1000. The problem is that the user otobo is not allowed to install system packages. Thus, the first part of the solution is to pass the option --user root when running the image. However the second hurdle is that the default entrypoint script /opt/otobo_install/entrypoint.sh exits immediately when it is called as root. The reasoning behind that design decision is that running inadvertently as root should be discouraged. So, the second part of the solution is to specify a different entrypoint script that does not care who the caller is. This leaves us with following example commands, where we add fortune cookies to OTOBO:

Pull a tagged OTOBO image, if we don’t have it yet, and check whether the image already provides fortune cookies:

docker run rotheross/otobo:rel-11_0_2 /usr/games/fortune
/opt/otobo_install/entrypoint.sh: line 57: /usr/games/fortune: No such file or directory

Add fortune cookies to a named container running the original OTOBO image. This is done in an interactive session as the user root:

docker run -it --user root --entrypoint /bin/bash --name otobo_orig rotheross/otobo:rel-11_0_2 bash -lc "apt update && apt install fortunes"
docker ps -a | head

Create an image from the stopped container and give it a name. Take into account that the default user and entrypoint script must be restored:

docker commit -c 'USER otobo'  -c 'ENTRYPOINT ["/opt/otobo_install/entrypoint.sh"]' otobo_orig otobo_with_fortune_cookies

Finally we can doublecheck:

docker run otobo_with_fortune_cookies /usr/games/fortune
# A platitude is simply a truth repeated till people get tired of hearing it.
#               -- Stanley Baldwin

The modified image can be specified in your .env file and then be used for fun and profit.

Building Local Images

Note

Building Docker images locally is usually only needed during development. Other use cases are when more current base images should be used for an installation or when extra functionality must be added to the images.

The Docker files needed for creating Docker images locally are part of the git repository https://github.com/RotherOSS/otobo:

otobo.web.dockerfile

otobo.nginx.dockerfile

otobo.elasticsearch.dockerfile

The script for the actual creation of the images is bin/docker/build_docker_images.sh.

cd /opt
git clone https://github.com/RotherOSS/otobo.git
cd otobo
# checkout the wanted branch, e.g, git checkout rel-11_0
# modify the docker files if necessary
bin/docker/build_docker_images.sh
docker image ls

The locally built Docker images are tagged as local-<OTOBO_VERSION> using the version set up the file RELEASE.

After building the local images, one can return to the docker-compose directory. The local images are declared by setting OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX in the .env file.

Automatic Installation

Instead of going through http://yourIPorFQDN/otobo/installer.pl, one can take a short cut. This is useful for running the test suite on a fresh installation.

Warning

docker compose down -v will remove all previous setup and data.

docker compose down -v
docker compose up --detach
docker compose stop daemon
docker compose exec web bash -c \
  "rm -f Kernel/Config/Files/ZZZAAuto.pm ; bin/docker/quick_setup.pl --db-password otobo_root"
docker compose exec web bash -c \
 "bin/docker/run_test_suite.sh"
# .......
docker compose start daemon

List of Useful Commands

Docker

docker system prune -a system clean-up (removes all unused images, containers, volumes, networks)

docker version show version

docker build --tag otobo --file=otobo.web.Dockerfile . build an image

docker run --publish 80:5000 otobo run the new image

docker run -it -v opt_otobo:/opt/otobo otobo bash log into the new image

docker run -it -v opt_otobo:/opt/otobo --entrypoint bash otobo try that in case entrypoint.sh is broken

docker ps show running images

docker images show available images

docker volume ls list volumes

docker volume inspect otobo_opt_otobo inspect a volume

docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl get volume mountpoint

docker volume rm tmp_volume remove a volume

docker inspect <container> inspect a container

docker save --output otobo.tar otobo:latest-11_0 && tar -tvf otobo.tar list files in an image

docker exec -it nginx-server nginx -s reload reload nginx

Docker Compose

docker compose config check and show the configuration

docker compose ps show the running containers

docker compose exec nginx nginx -s reload reload nginx

Resources

Finally, here is a highly subjective collection of links.

General info and tutorials

Perl Maven: Getting Started with Perl on Docker

Dockerfile best practices

Environment

Tips and hints

Clean up unused images

Docker Host IP

Self signed certificate

Troubleshooting

Docker cache invalidation

Using tcpdump

Inspect failed builds

OTOBO Installation on Ubuntu

This chapter describes the installation and basic configuration of OTOBO 11.1 on Ubuntu.

Note

Currently only Ubuntu 24.04 (noble) has been tested and verified. However, the configuration may also work on other versions.

Follow the detailed steps in this chapter to install OTOBO on your Ubuntu server. You can then use its web interface to login and administer the system.

Note

We recommend Docker and Docker Compose for the installation of OTOBO. By using the provided Docker images, all recommended dependencies, Perl packages and services like the database or Elasticsearch, are installed, kurated and configured automatically. Updates are thus greatly simplified and the performance may improve. You can find the instructions for Docker-based installation at: https://doc.otobo.org/manual/installation/11.1/en/content/installation/installation-docker.html .

Step 1: Unpack and Install OTOBO

Download the latest OTOBO release from https://ftp.otobo.org/pub/otobo/. Unpack the source archive (for example, using tar) into the directory /opt/otobo-install:

sudo mkdir /opt/otobo-install && sudo mkdir /opt/otobo                 # Create a temporary install directory
cd /opt/otobo-install                                                  # Change into the update directory
sudo wget https://ftp.otobo.org/pub/otobo/otobo-11.1.0-beta1.tar.gz    # Download the latest OTOBO 11 release
sudo tar -xzf otobo-11.1.0-beta1.tar.gz                                # Unzip OTOBO
sudo cp -r otobo-11.1.*/* /opt/otobo                                   # Copy the new otobo directory to /opt/otobo

Step 2: Install Additional Programs and Perl Modules

Use the following script to get an overview of all installed and required CPAN modules and other external dependencies.

Note

On Debian systems, like Ubuntu, you may need to manually install some Perl packages:

sudo apt install --yes libarchive-zip-perl libtimedate-perl libdatetime-perl libconvert-binhex-perl libcgi-psgi-perl libdbi-perl libdbix-connector-perl libfile-chmod-perl liblist-allutils-perl libmoo-perl libnamespace-autoclean-perl libnet-dns-perl libnet-smtp-ssl-perl libpath-class-perl libsub-exporter-perl libtemplate-perl libtext-trim-perl libtry-tiny-perl libxml-libxml-perl libyaml-libyaml-perl libdbd-mysql-perl libmail-imapclient-perl libauthen-sasl-perl libauthen-ntlm-perl libjson-xs-perl libtext-csv-xs-perl libpath-class-perl libplack-perl libplack-middleware-header-perl libplack-middleware-reverseproxy-perl libencode-hanextra-perl libio-socket-ssl-perl libnet-ldap-perl libcrypt-eksblowfish-perl libxml-libxslt-perl libxml-parser-perl libconst-fast-perl libmariadb-dev build-essential cpanminus
sudo cpanm --notest Gazelle DBD::MariaDB

sudo perl /opt/otobo/bin/otobo.CheckModules.pl --list
Checking for Perl Modules:
  o Archive::Tar.....................ok (v1.90)
  o Archive::Zip.....................ok (v1.37)
  o Crypt::Eksblowfish::Bcrypt.......ok (v0.009)
...

Note

Please note that OTOBO requires a working Perl installation with all core modules such as the module version. These modules are not explicitly checked by the script.

To install the required and optional packages, you can use either CPAN or the package manager of your Linux distribution.

Execute this command to get an install command to install the missing dependencies:

sudo /opt/otobo/bin/otobo.CheckModules.pl --inst

Note

There are a number of optional or alternative modules which can be installed, mostly for more customized versions of OTOBO. Calling otobo.CheckModules.pl without any argument will list a complete listing of packages required for full functionality.

Step 3: Create the OTOBO User

Create a dedicated user for OTOBO within its own group:

sudo useradd -r -U -d /opt/otobo -c 'OTOBO user' otobo -s /bin/bash

Step 4: Activate the Default Configuration File

There is an OTOBO configuration file bundled in $OTOBO_HOME/Kernel/Config.pm.dist. You must activate it by copying it without the .dist file name extension.

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

Step 5: Configure Systemd Services for OTOBO

The installation package provides systemd unit files. To make sure that these files are visible to the system they need to be copied to a valid systemd directory. In this example we will be using /etc/systemd/system.

sudo cp /opt/otobo/scripts/systemd/* /etc/systemd/system/
sudo systemctl daemon-reload

After the daemon-reload all services should be controllable using systemd control service like systemctl.

Step 6: Configure the Nginx Web Server

OTOBO uses a high performance Perl web server called Gazelle to serve the web interface. Gazelle listens on localhost on port 5000. In order to make it accessible from outside, you need to configure a reverse proxy.

Install the Nginx web server:

sudo apt install --yes nginx

Nginx installations commonly have a conf.d directory included. It may be found at /etc/nginx. Example configuration is provided at /opt/otobo/scripts/nginx-vhost-*.include.conf.

Configure Nginx without SSL Support

For testing purposes, you can use the provided configuration file for port 80 without SSL support. The server_name in the template file has to be changed from localhost to the desired name to become reachable externally. The new configuration needs to be activated, subsequently.

sudo cp /opt/otobo/scripts/nginx-vhost-80.include.conf /etc/nginx/sites-available/nginx.conf
sudo ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/sites-enabled/nginx.conf
sudo systemctl restart nginx

It is also required to allow port 80 on the firewall if it is enabled.

sudo ufw allow 80
sudo ufw reload

Note

A webserver without SSL support doesn’t allow any type of encryption and should never be used for production services.

Configure Nginx with SSL Support

If you want to enable SSL support, you need to copy the SSL configuration file.

sudo cp /opt/otobo/scripts/nginx-vhost-443.include.conf /etc/nginx/sites-available/nginx.conf
sudo ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/sites-enabled/nginx.conf
cd /etc/nginx/
sudo mkdir snippets
sudo cp /opt/otobo/scripts/nginx/snippets/ssl-params.conf snippets/

Edit the files and add the required information like SSL certificate storage path.

Now you restart your web server to load the new configuration settings. On most systems you can use the following command to do so:

sudo systemctl restart nginx

It is also required to allow port 80 and 443 on the firewall (if configured).

sudo ufw allow "Nginx Full"

Step 7: Set File Permissions

Please execute the following command to set the file and directory permissions for OTOBO. It will try to detect the correct user and group settings needed for your setup.

sudo /opt/otobo/bin/otobo.SetPermissions.pl --otobo-user=otobo --web-group=otobo

Step 8: Setup the Database

OTOBO requires a database to persist data. It is recommended to use the MariaDB package, which will be delivered with your Linux system. However, an external database may be used but latency may increase.

Packages for a local database may be obtained from the system’s package manager. Find the commands needed to set up MariaDB below.

sudo apt install --yes mariadb-server

After installing the database server you need configure it.

In order to use the OTOBO installer the password for the root user has to be set:

# chose a strong password and replace "NewRootPassword" with it
# openssl rand -base64 48
sudo mariadb -u root -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewRootPassword';"

Note

The following configuration settings are minimum requirements for MySQL setups. Please add the following lines to the MySQL Server configuration file /etc/mysql/mariadb.conf.d/50-server.cnf under the [mysqld] section:

max_allowed_packet   = 64M
innodb_log_file_size = 256M

Also add the following lines to the configuration file /etc/mysql/conf.d/mysqldump.cnf under the [mysqldump] section:

max_allowed_packet   = 64M

Make sure to restart the associated service after making these changes

sudo systemctl restart mariadb.service

For production purposes we recommend to use the tool mysqltuner to find the perfect setup. You can download the script from Github https://github.com/major/MySQLTuner-perl or install it on Debian or Ubuntu systems via package manager:

root> apt-get install --yes mysqltuner

After installing execute the script:

root> mysqltuner --user root --pass NewRootPassword

Step 9: Setup Elasticsearch

OTOBO recommends an active installation of Elasticsearch for quick search. The easiest way is to setup Elasticsearch on the same host as OTOBO and binding it to its default port.

Please follow the installation tutorial found at https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html.

OTOBO requires plugins to be installed into Elasticsearch:

sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch ingest-attachment
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu

Step 10: Basic System Configuration

Before starting with the initial web configuration you need to start and enable the OTOBO web service via Systemd.

sudo systemctl enable --now otobo-web.service

Please use the web installer at http://localhost/otobo/installer.pl (replace “localhost” with your OTOBO hostname) to set up your database and basic system settings such as email accounts.

Step 11: First Login

Now you are ready to login to your system at http://localhost/otobo/index.pl as user root@localhost with the password that was generated (see above).

Step 12: Start the OTOBO Daemon

OTOBO daemon is responsible for handling any asynchronous and recurring tasks in OTOBO. The daemon also handles all GenericAgent jobs and must be started from the OTOBO user.

sudo systemctl enable --now otobo-daemon.service

Step 13: Setup Bash Auto-Completion (optional)

All regular OTOBO command line operations happen via the OTOBO console interface. This provides an auto-completion for the bash shell which makes finding the right command and options much easier. You can activate the bash auto-completion by installing the package bash-completion. It will automatically detect and load the file /opt/otobo/.bash_completion for the otobo user. After restarting your shell, you can just type this command followed by TAB, and it will list all available commands:

sudo -u otobo /opt/otobo/bin/otobo.Console.pl

If you type a few characters of the command name, TAB will show all matching commands. After typing a complete command, all possible options and arguments will be shown by pressing TAB.

Note

If you have problems, you can execute the following line as user otobo and add it to your ~/.bashrc to execute the commands from the file.

source /opt/otobo/.bash_completion

Step 14: Further Information

We advise you to read the OTOBO Performance Tuning chapter.

OTOBO Installation on RHEL

This chapter describes the installation and basic configuration of the central OTOBO framework on a Red Hat Enterprise Linux (RHEL) system.

Note

Currently only RHEL 9.7 has been tested and verified. However the configuration may also work on other versions.

Follow the detailed steps in this chapter to install OTOBO on your RHEL server. You can then use its web interface to login and administer the system.

Note

We recommend Docker and Docker Compose for the OTOBO installation because its configuration works independent of the base operating system (Ubuntu, SUSE, etc.). By using the provided Docker images, all recommended dependencies (such as Elasticsearch, Redis Cache, etc.) are installed and configured automatically. Updates are thus greatly simplified and the performance may improve. You can find the instructions for Docker-based installation at: https://doc.otobo.org/manual/installation/11.0/en/content/installation/installation-docker.html .

Preparation: Disable SELinux when it is Installed and Enabled

Note

RHEL employs SELinux. However, OTOBO will not work correctly on the default ruleset. If you want to use OTOBO with SELinux enabled, you will have to configure the SELinux permission policy for this application manually.

Try the command sestatus and getenforce when you are not sure whether SELinux is installed and enabled on your system.

The sestatus command returns the SELinux status and the SELinux policy being used. SELinux status: enabled is returned when SELinux is enabled. Current mode: enforcing is returned when SELinux is running in enforcing mode. Policy from config file: targeted is returned when the SELinux targeted policy is used.

Here’s how to switch off SELinux for RHEL/CentOS/Fedora.

Configure SELINUX=permissive in the /etc/selinux/config file:

# This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#       enforcing - SELinux security policy is enforced.
#       permissive - SELinux prints warnings instead of enforcing.
#       disabled - No SELinux policy is loaded.
SELINUX=permissive
# SELINUXTYPE= can take one of these two values:
#       targeted - Targeted processes are protected,
#       mls - Multi Level Security protection.
SELINUXTYPE=targeted

Reboot your system. After reboot, confirm that the getenforce command returns Disabled:

sudo getenforce
Permissive

Step 1: Unpack and Install OTOBO

Download the latest OTOBO release from https://ftp.otobo.org/pub/otobo/. Unpack the source archive (for example, using tar) into the directory /opt/otobo-install:

sudo mkdir /opt/otobo-install && mkdir /opt/otobo                      # Create a temporary install directory
cd /opt/otobo-install                                                  # Change into the update directory
sudo wget https://ftp.otobo.org/pub/otobo/otobo-11.1.0-beta1.tar.gz    # Download the latest OTOBO 11 release
sudo tar -xzf otobo-11.1.0-beta1.tar.gz                                # Unzip OTOBO
sudo cp -r otobo-11.x.x/* /opt/otobo                                   # Copy the new otobo directory to /opt/otobo

Step 2: Create the OTOBO User

Create a dedicated user for OTOBO within its own group:

sudo useradd -r -U -d /opt/otobo -c 'OTOBO user' otobo -s /bin/bash

Step 3: Install Additional Programs and Perl Modules

OTOBO requires a working Perl installation with all core modules such as the module version.

sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms
sudo dnf install -y wget perl perl-DBD-MySQL libpq-devel libxslt-devel libxml2-devel graphviz-devel unixODBC-devel xz-devel

Required Perl modules may be installed from CPAN. However, in more confined environments, access to the internet may be restricted. Hence, one may download a prebuilt set of Perl packages (Option B):

Option A: Install packages from CPAN

To install the required packages from CPAN:

sudo dnf install -y perl-App-cpanminus                                                                   # Installs the cpanm package manager
sudo cpanm --cpanfile /opt/otobo/cpanfile.plackup --notest --installdeps /opt/otobo/install/local        # Installs all required packages

Option B: Deploy Pre-built Packages

cd /opt/otobo                                                                                         # Change into your OTOBO directory
sudo wget https://ftp.otobo.org/pub/otobo/rhel/otobo-deps-11.1-rhel-9.7-latest.tar.gz                 # Download all required packages
sudo tar -xzf otobo-deps-11.1-rhel-9.7-latest.tar.gz                                                  # Unzip packages
sudo bash -c "echo 'export PERL5LIB="/opt/otobo/install/local/lib/perl5"' >> /opt/otobo/.profile"     # Add additional library path to otobo user

You should now see a install folder containing all required Perl packages. You may run the following command to verify the installation:

sudo -i -u otobo perl /opt/otobo/bin/otobo.CheckModules.pl -list

Step 4: Activate the Default Configuration File

There is an OTOBO configuration file bundled in $OTOBO_HOME/Kernel/Config.pm.dist. You must activate it by copying it without the .dist file name extension.

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

Step 5: Configure systemd Services for OTOBO

The installation package provides systemd unit files. To make sure that these files are visible to the system they need to be copied to a valid systemd directory. In this example we will be using /etc/systemd/system.

sudo cp /opt/otobo/scripts/systemd/* /etc/systemd/system/
sudo systemctl daemon-reload

After the daemon-reload all services should be controllable using systemd control service like systemctl.

Step 6: Configure the Nginx Web Server

OTOBO’s webserver listens on localhost on port 5000. In order to make it accessible from outside, you need to configure a reverse proxy.

Install the Nginx web server:

sudo dnf install nginx

Nginx installations commonly have a conf.d directory included. It may be found at /etc/nginx. Example configuration is provided at /opt/otobo/scripts/nginx-vhost-*.include.conf.

Configure Nginx without SSL Support

In most cases no further editing of the template is required. The new configuration needs to be activated, subsequently.

sudo cp /opt/otobo/scripts/nginx-vhost-80.include.conf /etc/nginx/conf.d/nginx.conf
sudo systemctl restart nginx

It is also required to enable port 80 on the firewall.

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

Configure Nginx with SSL Support

If you want to enable SSL support, you need to copy the SSL configuration file.

sudo cp /opt/otobo/scripts/nginx-vhost-443.include.conf /etc/nginx/conf.d/nginx.conf
cd /etc/nginx/
sudo mkdir snippets
sudo cp /opt/otobo/scripts/nginx/snippets/ssl-params.conf snippets/

Please edit the files and add the required information like SSL certificate storage path.

Now you can restart your web server to load the new configuration settings. On most systems you can use the following command to do so:

sudo systemctl restart nginx

It is also required to enable port 80 and 443 on the firewall.

sudo firewall-cmd --permanent --add-service={http,https}
sudo firewall-cmd --reload

Step 7: Set File Permissions

Please execute the following command to set the file and directory permissions for OTOBO. It will try to detect the correct user and group settings needed for your setup.

sudo env PERL5LIB="/opt/otobo/install/local/lib/perl5" /opt/otobo/bin/otobo.SetPermissions.pl --otobo-user=otobo --web-group=otobo
sudo chmod +x /opt/otobo/install/local/bin/*

Step 8: Setup the Database

OTOBO requires a database to persist data. It is recommended to use the MySQL or MariaDB package, which will be delivered with your Linux system. However, an external database may be used but latency may increase.

Packages for a local database may be obtained from the system’s package manager. Find the commands needed to set up MySQL below.

sudo dnf install mariadb-server                # 'dnf install mysql-server' for mysql installations
sudo systemctl enable --now mariadb.service

After installing the database server you need configure it.

In MySQL higher or equal version 5.7 a new authentication module is active, and it is not possible to use the OTOBO web installer for database creation. Please login to the mysql console and set a different authentication module and password for the user root if this is the case:

# chose a strong password and replace "NewRootPassword" with it
# openssl rand -base64 48
sudo mysql -u root -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'NewRootPassword';"

After OTOBO installation it is possible to change the authentication module again, if needed.

Note

The following configuration settings are minimum requirements for MariaDB/MySQL setups. Please add the following lines to the Database Server configuration file /etc/my.cnf under the [mysqld] section:

max_allowed_packet   = 64M
innodb_log_file_size = 256M

In order to apply these settings, you need to restart the MySQL service.

sudo systemctl restart mysqld.service

Step 9: Setup Elasticsearch

OTOBO recommends an active installation of Elasticsearch for quick search. The easiest way is to setup Elasticsearch on the same host as OTOBO and binding it to its default port.

Please follow the installation tutorial found at https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html.

Elasticsearch Module Installation

Additionally, OTOBO requires plugins to be installed into Elasticsearch:

sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch ingest-attachment
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install --batch analysis-icu

Elasticsearch Configuration

Elasticsearch has a multitude of configuration options and possibilities.

In order to ensure error-free operation, you should adjust the JVM heap space for larger OTOBO systems. Please adjust the settings in the file /etc/elasticsearch/jvm.options. You should always set the min and max JVM heap size to the same value. For example, to set the heap to 512 MB, set:

-Xms512m
-Xmx512m

In our tests, a value between 512 MB and 4 GB for medium-sized installations has proven to be the best.

Note

See https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html for more information.

Now you can restart your Elasticsearch server to load the new configuration settings. On most systems you can use the following command to do so:

sudo systemctl restart elasticsearch

Step 10: Basic System Configuration

Before starting with the initial web configuration you need to start and enable the OTOBO web service via systemd.

sudo systemctl enable --now otobo-web.service

After that use the web installer at http://localhost/otobo/installer.pl (replace “localhost” with your OTOBO hostname or server IP) to set up your database and basic system settings such as email accounts.

Step 11: First Login

Now you are ready to login to your system at http://localhost/otobo/index.pl as user root@localhost with the password that was generated (see above).

Step 12: Start the OTOBO Daemon

OTOBO daemon is responsible for handling any asynchronous and recurring tasks in OTOBO. The daemon also handles all GenericAgent jobs and must be started from the OTOBO user.

sudo systemctl enable --now otobo-daemon.service

Step 13: Setup Bash Auto-Completion (optional)

All regular OTOBO command line operations happen via the OTOBO console interface. This provides an auto-completion for the bash shell which makes finding the right command and options much easier. You can activate the bash auto-completion by installing the package bash-completion. It will automatically detect and load the file /opt/otobo/.bash_completion for the otobo user. After restarting your shell, you can just type this command followed by TAB, and it will list all available commands:

sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl

If you type a few characters of the command name, TAB will show all matching commands. After typing a complete command, all possible options and arguments will be shown by pressing TAB.

Note

If you have problems, you can execute the following line as user otobo and add it to your ~/.bashrc to execute the commands from the file.

source /opt/otobo/.bash_completion

Step 14: Further Information

We advise you to read the OTOBO Performance Tuning chapter.

Updating OTOBO

This chapter describes the updating process of the central OTOBO framework. Please refer to any subsection for your preferred installation method.

Contents

Updating a Docker-based Installation of OTOBO

Migrating to Docker Compose v2

Stop the Containers

Updating the Docker Compose Files

Checking the Docker Compose .env File

Update OTOBO

Updating on RHEL

Step 1: Stop All Relevant Services and the OTOBO Daemon

Step 2: Backup Files and Database

Example for a Standard Installation with RHEL

Step 3: Install the new Release

Restore Old Configuration Files

Restore Article Data

Restore Already Installed Default Statistics

Set File Permissions

Step 4: Install new needed Perl Modules

Option A: Install packages from CPAN

Option B: Deploy Pre-built Packages

Step 5: Only for Minor or Major Release Upgrades (e.g., 11.0 to 11.1)

Step 6: Update Installed Packages and Reconfigure Config

Step 7: Start your Services

Step 8: (Optional) Disable Redis Caching

Updating on Ubuntu

Step 1: Stop All Relevant Services and the OTOBO Daemon

Option A: Systemd Unit Files Configured

Option B: Systemd Unit Files NOT Configured

Step 2: Backup Files and Database

Example for a Standard Installation with Ubuntu and MySQL

Step 3: Install the new Release

Restore Old Configuration Files

Restore Article Data

Restore Already Installed Default Statistics

Set File Permissions

Check Webserver Configuration Files

Step 4: Check for New Needed Perl Modules

Step 5: Only for Minor or Major Release Upgrades (e.g., 11.0 to 11.1)

Step 6: Update Installed Packages and Reconfigure Config

Step 7: Deploy new Systemd Service Files (Optional)

Check Webserver Configuration Files

Step 8: Start your Services

Option A: Services have been Migrated

Option B: Services have not been Migrated

Step 9: (Optional) Disable Redis Caching

Updating a Docker-based Installation of OTOBO

Warning

Don’t update without a complete backup of your system. See Backup and Restore for more information.

Important

Updates from one patch version to another patch version, e.g., from 11.1.6 to 11.1.7, are tested and under quality assurance. Skipping vesions in between may work, but may lead to unexpected results.

For running OTOBO under Docker we need the OTOBO software itself and an environment in which OTOBO can run. The OTOBO Docker image provides the environment and a copy of the OTOBO software. The software itself is installed in the volume otobo_opt_otobo. A named volume is used because run time data, e.g. configuration files and installed packages, is stored in the same directory tree.

When updating to a new version of OTOBO several things have to happen.

The Docker Compose files have to be updated.

The Docker Compose configuration file .env has to be checked.

The scripts/update.sh script has to be executed

Note

In the sample commands below, the version 11.x.y, corresponding to the tag 11_x_y, is used as the example version. Please substitute it with the real version, e.g. 11.1.7.

Note

Before upgrading, please check if your installed packages are available for the new version.

For OTOBO 11.1, the following packages are being migrated automatically to the framework. This means that no separate package is necessary and they will be part of OTOBO by default.

CK5-FullWindowMode

CustomerAgeShowCreated

CustomerTicketSearch

Elasticsearch-Extension

ExtendedArticleEdit

HideShowForAgentTicketCompose

ImportExportCustomerCompany

ImportExportStandardObjects

ImportExportTicket

OAuth2

OAuth2-Mail

PostMasterXFromHeader

ProcessTicketTemplates

RestorePendingInformation

RotherOSS-AccountedTimeInViews

TicketUpdateOperationExternalIdentifier

Warning

The optional 11.0 package ‘MailAccount-OAuth2’ is obsolete and replaced by new functionality in OTOBO core. It will not be uninstalled during migration to OTOBO 11.1. It will be listed as not fully installed. This will allow you to migrate configuration from the old package to new core functionality. You need to uninstall the package manually after migration.

Migrating to Docker Compose v2

Please take note, that Docker Compose v1 is deprecated and will not be supported in the future. If docker-compose --version shows a version beginning with 1, Docker Compose v1 is installed. If docker ps shows a container called otobo_web_1, then Docker Compose v1 is running your container.

If your host is a recent Ubuntu Linux, migration is straight forward and does not entail downtime of OTOBO:

# install docker compose v2
sudo apt install --yes docker-compose-v2

# Change to the otobo docker directory
cd /opt/otobo-docker

# stop the containers
docker-compose down

# start containers again usind docker compose v2
docker compose up --detach

# remove docker compose v1
sudo apt remove --yes docker-compose

Note

Docker Compose v2 entails a new naming scheme for the containers, e.g., otobo_web_1 becomes otobo-web-1 (note the change of _ to -). If you have tooling that relies on the docker-compose command or the name of the containers, e.g., when using acme.sh in standalone mode, you need to refit your setup.

Stop the Containers

cd /opt/otobo-docker
docker compose down
docker compose ps
# no containers should be listed here

Updating the Docker Compose Files

The OTOBO Docker Compose files may change between releases. Therefore, is must be made sure that the correct setup is used.

Note

See https://hub.docker.com/r/rotheross/otobo/tags for the available releases.

To obtain the new Docker Compose files, the OTOBO Docker repository must be updated to the wanted version: As a docker administrator, you can do this as follows:

# Change to the otobo docker directory
cd /opt/otobo-docker

# Get the latest tags
git fetch --tags

# Update OTOBO docker compose repository to version 11.x.y.
git switch rel-11_x_y

Checking the Docker Compose .env File

The file .env controls the OTOBO Docker container. Within that file, the variables OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, and OTOBO_IMAGE_OTOBO_NGINX declare which images are used. Please configure the these variables according to the OTOBO version you want to run rel-11_x_y. If you want to always pull the latest image, use latest.

Update OTOBO

Note

Since OTOBO 11.1 Redis caching gets migrated to FileStorage caching automatically when running update.sh. For common setups this results in increased query times. If you still want to use Redis, follow the instructions at Performance Tuning.

Warning

Please note that minor or major upgrades must always be carried out one after the other. If you would like to upgrade from version 10.0.* to the latest 11.1.*, please upgrade to 10.1 first and then to 11.1.

For minor and major version upgrades to OTOBO 11.1, the following script handles all necessary app and database update tasks automatically:

./scripts/update.sh --help
./scripts/update.sh

Updating on RHEL

This document describes the procedure for upgrading an existing OTOBO 11.0 to 11.1 on RHEL. However, the same procedure can be used for patch level updates, e.g., 11.1.0 to 11.1.1. Just omit the steps not relevant for patch level updates.

Note

It is highly recommended to perform a test update on a separate testing machine first.

Note

To prepare required Perl modules beforehand, you can already download and unzip the new OTOBO version and execute the check modules script, e.g. with the following command (please adjust the file path). This is not necessary in a regular installation and will be part of the later update instruction.

sudo -i -u otobo perl /opt/otobo/bin/otobo.CheckModules.pl --list

Note

On RHEL systems you have to manually install some Perl packages before upgrading to 11.1.

sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms
sudo dnf install -y wget perl perl-DBD-MySQL libpq-devel libxslt-devel libxml2-devel graphviz-devel unixODBC-devel xz-devel

For OTOBO 11.1, the following packages are being migrated automatically to the framework. This means that no separate package is necessary and they will be part of OTOBO by default.

CK5-FullWindowMode

CustomerAgeShowCreated

CustomerTicketSearch

Elasticsearch-Extension

ExtendedArticleEdit

HideShowForAgentTicketCompose

ImportExportCustomerCompany

ImportExportStandardObjects

ImportExportTicket

PostMasterXFromHeader

ProcessTicketTemplates

RestorePendingInformation

RotherOSS-AccountedTimeInViews

TicketUpdateOperationExternalIdentifier

OAuth2

OAuth2-Mail

Elasticsearch-FAQ

Warning

The optional 11.0 package ‘MailAccount-OAuth2’ is obsolete and replaced by new functionality in OTOBO core. It will not be uninstalled during migration to OTOBO 11.1. It will be listed as not fully installed. This will allow you to migrate configuration from the old package to new core functionality. You need to uninstall the package manually after migration.

Step 1: Stop All Relevant Services and the OTOBO Daemon

Please make sure there are no more running services or Cron jobs that try to access OTOBO. This will depend on your service configuration.

sudo systemctl stop postfix
sudo systemctl stop nginx
sudo systemctl stop crond

Now you need to be stopping the OTOBO core services.

sudo systemctl disable --now otobo-web.service otobo-daemon.service

Step 2: Backup Files and Database

Create a backup of the whole /opt/otobo directory and the database.

Example for a Standard Installation with RHEL

sudo mkdir /opt/otobo-update                            # Create a update directory
cd /opt/otobo-update                                    # Change into the update directory
sudo cp -pr /opt/otobo otobo-prod-old                   # Backup the whole OTOBO directory into the update directory
sudo mysqldump -u otobo -p otobo -r otobo-prod-old.sql  # Backup the otobo database to otobo-prod-old.sql

Please check whether all files are valid.

Warning

Do not proceed without a complete backup of your system. You can also use the Backup and Restore script for this.

Step 3: Install the new Release

Download the latest OTOBO release from https://ftp.otobo.org/pub/otobo/ and unpack the source archive (for example, using tar) into the directory /opt/otobo-update:

cd /opt/otobo-update                                                    # Change into the update directory
sudo wget https://ftp.otobo.org/pub/otobo/otobo-11.1.0-beta1.tar.gz     # Download the latest OTOBO 11.1 release
sudo tar -xzf otobo-11.1.0-beta1.tar.gz                                 # Unzip OTOBO
sudo \cp -r otobo-11.1.*/* /opt/otobo                                   # Copy the new otobo directory to /opt/otobo

Restore Old Configuration Files

We only need to copy the file Kernel/Config.pm in OTOBO 11.

cd /opt/otobo-update
sudo \cp -p otobo-prod-old/Kernel/Config.pm /opt/otobo/Kernel/
sudo \cp -p otobo-prod-old/var/cron/* /opt/otobo/var/cron/

Restore Article Data

If you configured OTOBO to store article data in the file system, restore the article folder to /opt/otobo/var/ or the folder specified in the system configuration.

cd /opt/otobo-update
sudo \cp -pr otobo-prod-old/var/article/* /opt/otobo/var/article/

Restore Already Installed Default Statistics

If you have packages installed, which provide additional statistics, restore the stats XML files with the suffix *.installed to /opt/otobo/var/stats:

cd /opt/otobo-update/otobo-prod-old/var/stats
sudo \cp *.installed /opt/otobo/var/stats

Set File Permissions

Execute the following command to set the file and directory permissions for OTOBO. It will try to detect the correct user and group settings needed for your setup.

sudo env PERL5LIB="/opt/otobo/install/local/lib/perl5" /opt/otobo/bin/otobo.SetPermissions.pl --otobo-user=otobo --web-group=otobo
sudo chmod +x /opt/otobo/install/local/bin/*

Step 4: Install new needed Perl Modules

OTOBO needs new CPAN packages to allign the installed versions with OTOBOs requierements. Required Perl modules may be installed from CPAN. However, in more confined environments, access to the internet may be restricted. Hence, one may download a prebuilt set of Perl packages (Option B):

Option A: Install packages from CPAN

To install the required packages from CPAN:

sudo dnf install -y perl-App-cpanminus                                                                   # Installs the cpanm package manager
sudo cpanm --cpanfile /opt/otobo/cpanfile.plackup --notest --installdeps /opt/otobo/install/local        # Installs all required packages

Option B: Deploy Pre-built Packages

cd /opt/otobo                                                                                        # Change into your OTOBO directory
sudo wget https://ftp.otobo.org/pub/otobo/rhel/otobo-deps-11.1-rhel-9.7-latest.tar.gz                # Download all required packages
sudo tar -xzf otobo-deps-11.1-rhel-9.7-latest.tar.gz                                                 # Unzip packages
sudo bash -c "echo 'export PERL5LIB="/opt/otobo/install/local/lib/perl5"' >> /opt/otobo/.profile"    # Add additional library path to otobo user

You should now see a install folder containing all required Perl packages. You may run the following command to verify the installation:

sudo -i -u otobo perl /opt/otobo/bin/otobo.CheckModules.pl -list

Please make sure to install all required packages and modules listed at the beginning of this article and the listed packages from the command below.

sudo -i -u otobo perl /opt/otobo/bin/otobo.CheckModules.pl --inst

Step 5: Only for Minor or Major Release Upgrades (e.g., 11.0 to 11.1)

sudo -i -u otobo /opt/otobo/scripts/DBUpdate-to-11.1.pl

Step 6: Update Installed Packages and Reconfigure Config

You can use the command below to update all installed packages. This works for all packages that are available from online repositories. You can update other packages later via the package manager (this requires a running OTOBO daemon).

sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Admin::Package::ReinstallAll
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Admin::Package::UpgradeAll
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Config::Rebuild
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Cache::Delete
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Loader::CacheCleanup
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Translations::Deploy

Step 7: Start your Services

The core services can simply be enabled and started using systemctl.

sudo systemctl enable --now otobo-web.service otobo-daemon.service

Now additional services can be started. This will depend on your service configuration, here is an example:

sudo systemctl start postfix
sudo systemctl start nginx
sudo systemctl start crond

Now you can log into your system.

Step 8: (Optional) Disable Redis Caching

Since OTOBO 11.1 we no longer recommend Redis for caching in general because it often results in increased loading times. There are still use cases in production environments where Redis is the better option but on average we recommend using the local filesystem for better results.

Depending on your setup this can either be changed in your /opt/otobo/Kernel/Config.pm file or in the Sysconfig Cache::Module in the OTOBO UI. The value has to be changed from Kernel::System::Cache::Redis to Kernel::System::Cache::FileStorable.

Updating on Ubuntu

This document describes the procedure for upgrading an existing OTOBO 11.0 to 11.1. However, the same procedure can be used for patch level updates, e.g., 11.1.0 to 11.1.1. Just omit the steps not relevant for patch level updates.

Note

It is highly recommended to perform a test update on a separate testing machine first.

Note

To prepare required Perl modules beforehand, you can already download and unzip the new OTOBO version and execute the check modules script, e.g. with the following command (please adjust the file path). This is not necessary in a regular installation and will be part of the later update instruction.

perl /tmp/otobo/bin/otobo.CheckModules.pl --list

Note

On Ubuntu/Debian systems you have to manually install some Perl packages before upgrading to 11.1.

sudo apt install --yes libarchive-zip-perl libtimedate-perl libdatetime-perl libconvert-binhex-perl libcgi-psgi-perl libdbi-perl libdbix-connector-perl libfile-chmod-perl liblist-allutils-perl libmoo-perl libnamespace-autoclean-perl libnet-dns-perl libnet-smtp-ssl-perl libpath-class-perl libsub-exporter-perl libtemplate-perl libtext-trim-perl libtry-tiny-perl libxml-libxml-perl libyaml-libyaml-perl libdbd-mysql-perl libmail-imapclient-perl libauthen-sasl-perl libauthen-ntlm-perl libjson-xs-perl libtext-csv-xs-perl libpath-class-perl libplack-perl libplack-middleware-header-perl libplack-middleware-reverseproxy-perl libencode-hanextra-perl libio-socket-ssl-perl libnet-ldap-perl libcrypt-eksblowfish-perl libxml-libxslt-perl libxml-parser-perl libconst-fast-perl libmariadb-dev build-essential cpanminus
sudo cpanm --notest Gazelle DBD::MariaDB

For OTOBO 11.1, the following packages are being migrated automatically to the framework. This means that no separate package is necessary and they will be part of OTOBO by default.

CK5-FullWindowMode

CustomerAgeShowCreated

CustomerTicketSearch

Elasticsearch-Extension

ExtendedArticleEdit

HideShowForAgentTicketCompose

ImportExportCustomerCompany

ImportExportStandardObjects

ImportExportTicket

PostMasterXFromHeader

ProcessTicketTemplates

RestorePendingInformation

RotherOSS-AccountedTimeInViews

TicketUpdateOperationExternalIdentifier

OAuth2

OAuth2-Mail

Elasticsearch-FAQ

Warning

The optional 11.0 package ‘MailAccount-OAuth2’ is obsolete and replaced by new functionality in OTOBO core. It will not be uninstalled during migration to OTOBO 11.1. It will be listed as not fully installed. This will allow you to migrate configuration from the old package to new core functionality. You need to uninstall the package manually after migration.

Step 1: Stop All Relevant Services and the OTOBO Daemon

Please make sure there are no more running services or Cron jobs that try to access OTOBO. This will depend on your service configuration.

sudo systemctl stop postfix
sudo systemctl stop apache2
sudo systemctl stop cron

Now you need to be stopping the OTOBO core services depending on your configuration.

Option A: Systemd Unit Files Configured

If you have already migrated to Systemd unit files in the past the following line can be used:

sudo systemctl disable --now otobo-web.service otobo-daemon.service

Option B: Systemd Unit Files NOT Configured

Otherwise stop OTOBO Cron jobs and the daemon manually (in this order):

cd /opt/otobo/
sudo -u otobo bin/Cron.sh stop
sudo -u otobo bin/otobo.Daemon.pl stop

Step 2: Backup Files and Database

Create a backup of the hole /opt/otobo directory and the database.

Example for a Standard Installation with Ubuntu and MySQL

sudo mkdir /opt/otobo-update                            # Create a update directory
cd /opt/otobo-update                                    # Change into the update directory
sudo cp -pr /opt/otobo otobo-prod-old                   # Backup the whole OTOBO directory into the update directory
sudo mysqldump -u otobo -p otobo -r otobo-prod-old.sql  # Backup the otobo database to otobo-prod-old.sql

Please check whether all files are valid.

Warning

Do not proceed without a complete backup of your system. You can also use the Backup and Restore script for this.

Step 3: Install the new Release

Download the latest OTOBO release from https://ftp.otobo.org/pub/otobo/ and unpack the source archive (for example, using tar) into the directory /opt/otobo-update:

cd /opt/otobo-update                                                   # Change into the update directory
sudo wget https://ftp.otobo.org/pub/otobo/otobo-11.1.0-beta1.tar.gz    # Download the latest OTOBO 11.1 release
sudo tar -xzf otobo-latest-11.1.tar.gz                                 # Unzip OTOBO
sudo cp -r otobo-11.1.*/* /opt/otobo                                   # Copy the new otobo directory to /opt/otobo

Restore Old Configuration Files

We need only copy the file Kernel/Config.pm in OTOBO 11.

cd /opt/otobo-update
sudo cp -p otobo-prod-old/Kernel/Config.pm /opt/otobo/Kernel/
sudo cp -p otobo-prod-old/var/cron/* /opt/otobo/var/cron/

Restore Article Data

If you configured OTOBO to store article data in the file system, restore the article folder to /opt/otobo/var/ or the folder specified in the system configuration.

cd /opt/otobo-update
sudo cp -pr otobo-prod-old/var/article/* /opt/otobo/var/article/

Restore Already Installed Default Statistics

If you have additional packages with default statistics, restore the stats XML files with the suffix *.installed to /opt/otobo/var/stats.

cd /opt/otobo-update/otobo-prod-old/var/stats
sudo cp *.installed /opt/otobo/var/stats

Set File Permissions

Execute the following command to set the file and directory permissions for OTOBO. It will try to detect the correct user and group settings needed for your setup.

sudo /opt/otobo/bin/otobo.SetPermissions.pl

Check Webserver Configuration Files

Newer versions of OTOBO may need you to adjust the webserver configuration. From version 11.0 onwards we moved from PSGI to native Nginx. We provide Nginx templates at scripts/nginx-vhost-443.include.conf and scripts/nginx-vhost-80.include.conf.

Step 4: Check for New Needed Perl Modules

OTOBO needs new cpan packages for some version jumps. Please make sure to install all required packages and modules listed at the beginning of this article and the listed packages from the command below.

sudo -u otobo perl /opt/otobo/bin/otobo.CheckModules.pl --inst

Step 5: Only for Minor or Major Release Upgrades (e.g., 11.0 to 11.1)

sudo -u otobo /opt/otobo/scripts/DBUpdate-to-11.1.pl

Step 6: Update Installed Packages and Reconfigure Config

You can use the command below to update all installed packages. This works for all packages that are available from online repositories. You can update other packages later via the package manager (this requires a running OTOBO daemon).

sudo -u otobo /opt/otobo/bin/otobo.Console.pl Admin::Package::ReinstallAll
sudo -u otobo /opt/otobo/bin/otobo.Console.pl Admin::Package::UpgradeAll
sudo -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Config::Rebuild
sudo -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Cache::Delete
sudo -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Loader::CacheCleanup
sudo -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Translations::Deploy

Step 7: Deploy new Systemd Service Files (Optional)

Since OTOBO 11.1 it is recommended for native installations to run their OTOBO web service and OTOBO daemon using Systemd unit files. This way the OTOBO services are becoming easier to manage and more tightly integrated into the hosts operating stack. In addition, they significantly simplify the troubleshooting experience.

If you are not sure if the unit files are already implemented you can use the following command to check.

sudo systemctl status otobo-web.service
sudo systemctl status otobo-daemon.service

If the services are showing up this step can be skipped.

To make sure that these files are visible to the system they need to be copied to a valid Systemd directory. In this example we will be using /etc/systemd/system.

sudo cp /opt/otobo/scripts/systemd/* /etc/systemd/system/
sudo systemctl daemon-reload

After the daemon-reload all services should be controllable using Systemd control service like systemctl.

Check Webserver Configuration Files

The new Systemd unit files are now relying on Gazelle webserver which means that the previous Apache webserver configs with the modperl plugin will not work anymore. The new Gazelle webserver binds the OTOBO webservice internally on port 5000. Opening this port to the public and handling SSL has to be done by an external reverse proxy. It is still possible to use Apache webserver to do this job but we strongly recommend switching to Nginx since it provides more modern features and Nginx syntax will also be used for all templates in the future.

To migrate to Nginx the old webserver has to be removed first.

sudo apt remove --yes apache2 libapache2-mod-perl2

In the next step Nginx has to be installed and configured.

sudo apt install --yes nginx

Similar to Apache, a site configuration needs to be provided to Nginx. Example configuration is provided at /opt/otobo/scripts/nginx-vhost-*.include.conf.

Configure Nginx without SSL Support

In most cases the included template is suitable. Nevertheless, the server_name in the template file has to be changed from localhost to the desired name to become reachable externally. The new configuration needs to be activated, subsequently.

sudo cp /opt/otobo/scripts/nginx-vhost-80.include.conf /etc/nginx/sites-available/nginx.conf
sudo ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/sites-enabled/nginx.conf
sudo systemctl restart nginx

It is also required to allow port 80 on the firewall if it is enabled.

sudo ufw allow 80
sudo ufw reload

Note

A webserver without SSL support doesn’t allow any type of encryption and should never be used for production services.

Configure Nginx with SSL Support

If you want to enable SSL support, you need to copy the SSL configuration file.

sudo cp /opt/otobo/scripts/nginx-vhost-443.include.conf /etc/nginx/sites-available/nginx.conf.conf
sudo ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/sites-enabled/nginx.conf
cd /etc/nginx/
sudo mkdir snippets
sudo cp /opt/otobo/scripts/nginx/snippets/ssl-params.conf snippets/

Edit the files and add the required information like SSL certificate storage path.

Restart your web server to load the new configuration settings. On most systems you can use the following command to do so:

sudo systemctl restart nginx

It is also required to allow port 80 and 443 on the firewall (if configured).

sudo ufw allow "Nginx Full"

Step 8: Start your Services

This will now depend on whether the OTOBO services have been migrated to the Systemd unit files as mentioned in Step 7 or not.

Option A: Services have been Migrated

If the services have been migrated they can simply be enabled and started using systemctl.

sudo systemctl enable --now otobo-web.service otobo-daemon.service

Option B: Services have not been Migrated

If not migrated, OTOBO daemon and cron jobs must be started using their associated scripts (in this order):

sudo -u otobo cd /opt/otobo/
sudo -u otobo bin/otobo.Daemon.pl start
sudo -u otobo bin/Cron.sh start

Now additional services can be started. This will depend on your service configuration, here is an example:

sudo systemctl start postfix
sudo systemctl start apache2        # Won't be available after systemd unit migration
sudo systemctl start cron

Now you can log into your system.

Step 9: (Optional) Disable Redis Caching

Since OTOBO 11.1 we no longer recommend Redis for caching in general because it often results in increased loading times. There are still use cases in production environments where Redis is the better option but on average we recommend using the local filesystem for better results.

Depending on your setup this can either be changed in your /opt/otobo/Kernel/Config.pm file or in the Sysconfig Cache::Module in the OTOBO UI. The value has to be changed from Kernel::System::Cache::Redis to Kernel::System::Cache::FileStorable.

Migration from OTRS 6 or OTRS 7 / ((OTRS)) Community Edition to OTOBO

Welcome and thank you for choosing OTOBO!

OTRS, ((OTRS)) Community Edition and OTOBO are very comprehensive and flexible in their application. Thus, every migration to OTOBO requires thorough preparation and possibly some rework, too.

Please take your time for the migration and follow these instructions step by step.

If you have any problem or question, please do not despair. Call our support line, write an email, or post your query in the OTOBO Community forum at https://forum.otobo.org/. We will find a way to help you!

Note

After the migration the data previously available in OTRS will be available in OTOBO. We do not modify any data of the OTRS installation during the migration.

Warning

Migration from OTRS to OTOBO is only supported on 10.1.X. Upgrade step by step through all Major/Minor until you reach your target version (10.1 → 11.0 → 11.1). Refer to the specific upgrade instructions for each version, and to the chapter Updating OTOBO in general.

Overview over the Supported Migration Scenarios

With the OTOBO Migration Interface it is possible to employ the following migration strategies:

The general migration strategy.

This is the regular way to perform a migration. Many different combinations are supported:

Change server:

Migrate and simultaneously move to a new application server.

Separate application and web servers:

It’s your choice whether you want to run application and database server on the same host or each on a dedicated host. This choice is regardless of the previous setup in OTRS / ((OTRS)) Community Edition.

Different databases:

Migrate from any of the supported databases to any other supported database.

Different operating system:

Switch from any supported operating system to any other supported operating system.

Docker:

Migrate to a Docker-based installation of OTOBO 10.1.

A variant of the general strategy where the database migration is streamlined.

Use the ETL-like migration when the source database mustn’t suffer from increased load or when access to the source database is a bottleneck. In the general strategy, the data is row by row first read from the otrs database and then inserted into the OTOBO database. In this variant, the complete otrs database tables are first exported, then transformed, and then imported into the otobo database.

Migration from an Oracle based OTRS 6 / OTRS 7 installation to an Oracle based OTOBO installation.

This is a special case that is not supported by the general migration strategy. This means that a variant of the streamlined strategy must be used.

Warning

All strategies work for both Docker-based and native installations. But for Docker-based installations some peculiarities have to be considered. These peculiarities are handled in the optional steps.

Note

It is also feasible to clone the OTRS database to the OTOBO database server before the actual migration. This can speed up the general migration strategy.

Migration Requirements

Basic requirement for a migration is that you already have an ((OTRS)) Community Edition or OTRS 6.0.* / OTRS 7.0.* running, and that you want to transfer both configuration and data to OTOBO.

Warning

Please consider carefully whether you really need the data and configuration. Experience shows that quite often a new start is the better option. This is because in many cases the previously used installation and configuration was rather suboptimal anyways. It might also make sense to only transfer the ticket data and to change the basic configuration to OTOBO Best Practice. We are happy to advise you, please get in touch at hello@otobo.io or ask your question in the OTOBO Community forum at https://forum.otobo.org/.

You need a running OTOBO installation to start the migration from there!

This OTOBO installation must contain all OPM packages installed in your OTRS that you want to use in OTOBO, too.

If you are planning to migrate to another server, then the OTOBO webserver must be able to access the location where your ((OTRS)) Community Edition or OTRS 6.0.* / OTRS 7.0.* is installed. In most cases, this is the directory /opt/otrs on the server running OTRS. The read access can be effected via SSH or via file system mounts.

The otrs database must be accessible from the server running OTOBO. Read-only access must be granted for external hosts. If access is not possible, or when the speed of the migration should be optimized, then a dump of the database is sufficient.

Note

If SSH and database access between the servers is not possible, please migrate OTRS to OTOBO on the same server and only then move the new installation.

Step 1: Install the new OTOBO System

Please start with installing a new OTOBO system. Your old OTRS / ((OTRS)) Community Edition installation will be migrated to that new system. We strongly recommend to read the chapter OTOBO Installation. For Docker-based installations (recommended) we refer to the chapter OTOBO Installation Docker.

Warning

Under Apache, there are pitfalls with running two independent mod_perl applications under on the same webserver. Therefore, it is advised to run OTRS and OTOBO on separate webservers. Alternatively remove the OTRS configuration from Apache before installing OTOBO. Use the command a2query -s and check the directories /etc/apache2/sites-available and /etc/apache2/sites-enabled for inspecting which configurations are currently available and which are enabled.

After finishing the installation please log in as root@localhost. Navigate to the OTOBO Admin Area Admin -> Packages and install all required OTOBO OPM packages.

The following OPM packages and OTRS “Feature Addons” need NOT and should NOT be installed, as these features are already available in the OTOBO standard:

OTRSHideShowDynamicField

RotherOSSHideShowDynamicField

TicketForms

RotherOSS-LongEscalationPerformanceBoost

Znuny4OTRS-AdvancedDynamicFields

Znuny4OTRS-AutoSelect

Znuny4OTRS-EscalationSuspend

OTRSEscalationSuspend

OTRSDynamicFieldDatabase

OTRSDynamicFieldWebService

OTRSBruteForceAttackProtection

Znuny4OTRS-ExternalURLJump

Znuny4OTRS-QuickClose

Znuny4OTRS-AutoCheckbox

OTRSSystemConfigurationHistory

Znuny4OTRS-PasswordPolicy

The following OTOBO packages have been integrated into OTOBO 11.0. This means that they should not be installed in the target system when the target system is OTOBO 11:

ImportExport

Step 2: Deactivate SecureMode on OTOBO

After installing OTOBO, please log in again to the OTOBO Admin Area Admin -> System Configuration and deactivate the configuration option SecureMode.

Note

Do not forget to actually deploy the changed setting.

Step 3: Stop the OTOBO Daemon

This is necessary when the OTOBO Daemon is actually running. Stopping the Daemon is different between Docker-based and non-Docker-based installations.

In the non-Docker case execute the following commands as the user otobo:

# in case you are logged in as root
su - otobo

/opt/otobo/bin/Cron.sh stop
/opt/otobo/bin/otobo.Daemon.pl stop --force

You can also use systemctl if systemd unit files are configured on OTOBO.

systemctl disable --now otobo-web.service otobo-daemon.service

When OTOBO is running in Docker, you just need to stop the service daemon:

cd /opt/otobo-docker
docker compose stop daemon
docker compose ps     # otobo-daemon-1 should have exited with the code 0

Note

It is recommended to run a backup of the whole OTOBO system at this point. If something goes wrong during migration, you will then not have to repeat the entire installation process, but can instead import the backup for a new migration.

See also

We advise you to read the OTOBO Backup and Restore chapter.

Optional Step: Mount /opt/otrs for Convenient Access

Often OTOBO should be running on a new server where /opt/otrs isn’t available initially. In these cases the directory /opt/otrs on the OTRS server can be mounted into the file system of the OTOBO server. When a regular network mount is not possible, then using sshfs might be an option.

Optional Step: Install sshpass and rsync when /opt/otrs Should be Copied via SSH

This step is only necessary when you want to migrate OTRS from another server and when /opt/otrs from the remote server hasn’t been mounted on the server running OTOBO.

The tools sshpass and rsync are needed so that migration.pl can copy files via SSH. For installing sshpass, please log in on the server as user root and execute one of the following commands:

# Install sshpass under Debian / Ubuntu Linux
sudo apt install sshpass

# Install sshpass under RHEL/CentOS Linux
sudo yum install sshpass

# Install sshpass under Fedora
sudo dnf install sshpass

# Install sshpass under OpenSUSE Linux
sudo zypper install sshpass

The same thing must be done for rsync when it isn’t available yet.

Step 4: Preparing the OTRS / ((OTRS)) Community Edition system

Note

Be sure to have a valid backup of your OTRS / ((OTRS)) Community Edition system, too. Yes, we do not touch any OTRS data during the migration, but at times a wrong entry is enough to cause trouble.

Now we are ready for the migration. First of all we need to make sure that no more tickets are processed and no users log on to OTRS:

Please log in to the OTRS Admin Area Admin ->  System Maintenance and add a new system maintenance slot for a few hours. After that, delete all agent and user sessions (Admin ->  Sessions) and log out.

Stop All Relevant Services and the OTRS Daemon

Please make sure there are no running services or cron jobs.

# in case you are logged in as root
su - otrs

/opt/otrs/bin/Cron.sh stop
/opt/otrs/bin/otrs.Daemon.pl stop --force

Clear the Caches and the Operational Data

The cached data and the operational data doesn’t have to be migrated. The mail queue should at this point already be empty.

# in case you are logged in as root
su - otrs

/opt/otrs/bin/otrs.Console.pl Maint::Cache::Delete
/opt/otrs/bin/otrs.Console.pl Maint::Session::DeleteAll
/opt/otrs/bin/otrs.Console.pl Maint::Loader::CacheCleanup
/opt/otrs/bin/otrs.Console.pl Maint::WebUploadCache::Cleanup
/opt/otrs/bin/otrs.Console.pl Maint::Email::MailQueue --delete-all

Optional Step for Docker: Make Required Data Available Inside Container

There are some specifics to be considered when your OTOBO installation is running under Docker. The most relevant: processes running in a Docker container generally cannot access directories outside the container. There is an exception though: directories mounted as volumes into the container can be accessed. Also, note that the MariaDB database running in otobo-db-1 is not directly accessible from outside the container network.

Note

In the sample commands, we assume that the user docker_admin is used for interacting with Docker. The Docker admin may be either the root user of the Docker host or a dedicated user with the required permissions.

Copy /opt/otrs into the Volume otobo_opt_otobo

In this section, we assume that the OTRS home directory /opt/otrs is available on the Docker host.

There are at least two viable possibilitie

Copy /opt/otrs into the existing volume otobo_opt_otobo

Mount /opt/otrs as an additional volume

Let’s concentrate on option a. here.

First we need to find out where the volume otobo_opt_otobo is available on the Docker host.

otobo_opt_otobo_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_opt_otobo)
echo $otobo_opt_otobo_mp  # just a sanity check

For safe copying, we use rsync. Depending on your Docker setup, the command rsync might need to be run with sudo.

# when docker_admin is root
rsync --recursive --safe-links --owner --group --chown 1000:1000 --perms --chmod "a-wx,Fu+r,Du+rx" /opt/otrs/ $otobo_opt_otobo_mp/var/tmp/copied_otrs
ls -la $otobo_opt_otobo_mp/var/tmp/copied_otrs  # just a sanity check

# when docker_admin is not root
sudo rsync --recursive --safe-links --owner --group --chown 1000:1000 --perms --chmod "a-wx,Fu+r,Du+rx" /opt/otrs/ $otobo_opt_otobo_mp/var/tmp/copied_otrs
sudo ls -la $otobo_opt_otobo_mp/var/tmp/copied_otrs  # just a sanity check

This copied directory will be available as /opt/otobo/var/tmp/copied_otrs within the container.

Step 5: Perform the Migration!

Please use the web migration tool at http://localhost/otobo/migration.pl. Be aware that you might have to replace “localhost” with your OTOBO hostname and you might have to add your non-standard port. The application then guides you through the migration process.

Warning

Sometimes, a warning is shown that the deactivation of SecureMode has not been detected. Please restart the webserver in this case. This forces the webserver to read in the current configuration.

For a native installation, the command is:

systemctl restart apache2 # Or nginx depending on your setup

For a Docker-based installation, the commands are:

cd /opt/otobo-docker
docker compose restart web
docker compose ps     # otobo-web-1 should be running again

Note

If OTOBO runs inside a Docker container, keep the default settings localhost for the OTRS server and /opt/otobo/var/tmp/copied_otrs for the OTRS home directory. This is the path of the data that was copied in the optional step.

Note

The default values for OTRS database user and password are taken from Kernel/Config.pm in the OTRS home directory. Change the proposed settings if you are using a dedicated database user for the migration. Also change the settings when you work with a database that was copied into the otobo-db-1 Docker container.

Note

In the Docker case, a database running on the Docker host won’t be reachable via 127.0.0.1 from within the Docker container. This means that the setting 127.0.0.1 won’t be valid for the input field OTRS Server. In that case, enter one of the alternative IP addresses reported by the command hostname --all-ip-addresses for OTRS Server.

Note

When migrating to a new application server, or to a Docker-based installation, quite often the database cannot be accessed from the target installation. This is usually due to the fact that the otobo database user can only connect from the host the database runs on. In order to allow access anyways it is recommended to create a dedicated database user for the migration. E.g., CREATE USER 'otrs_migration'@'%' IDENTIFIED BY 'otrs_migration'; and GRANT SELECT, SHOW VIEW ON otrs.* TO 'otrs_migration'@'%';. This user can be dropped again after the migration: DROP USER 'otrs_migration'@'%'.

Custom settings in Kernel/Config.pm are carried over from the old OTRS installation to the new OTOBO installation. When you have custom settings, then please take a look at the migrated file /opt/otobo/Kernel/Config.pm. You might want to adapt custom paths or LDAP settings. In the best case you might find that some custom setting are longer needed.

When the migration is complete, please take your time and test the entire system. Once you have decided that the migration was successful and that you want to use OTOBO from now on, start the OTOBO Daemon:

# in case you are logged in as root
su - otobo

/opt/otobo/bin/Cron.sh start
/opt/otobo/bin/otobo.Daemon.pl start

In case you have systemd unit files configured:

systemctl disable --now otobo-web.service otobo-daemon.service

In the Docker case:

cd ~/otobo-docker
docker compose start daemon

Step 6: After Successful Migration!

Uninstall sshpass if you do not need it anymore.

Drop the databases and database users dedicated to the migration if you created any.

Have fun with OTOBO!

Known Migration Problems

1. Login After Migration not Possible

During our migration tests, the browser used for the migration sometimes had problems. After restarting the browser, this problem usually was solved. With Safari it was sometimes necessary to manually delete the old OTRS session.

2. Final Page of the Migration Has a Strange Layout Due to Missing CSS Files

This can happen when the setting ScriptAlias has a non-standard value. The migration simply substitutes otrs for otobo. This might lead to the effect that the CSS and JavaScript can no longer be retrieved in OTOBO. When that happens, please check the settings in Kernel/Config.pm and revert them to sane values.

3. Migration Stops due to MySQL Errors

On systems that experienced problems with an upgrade in the past, the migration process may stop due to MySQL errors in the tables ticket and ticket_history. Usually these errors are NULL values in the source table that are no longer allowed in the target table. These conflicts have to be manually resolved before you can resume the migration.

There is a check in migration.pl that checks for NULL values before the data transfer is done. Note, that the resolution still needs to be performed manually.

4. Errors in Step 5 when Migrating to PostgreSQL

In these cases the not so helpful message “System was unable to complete data transfer.” is shown by migration.pl. The Apache logfile, and the OTOBO logfile, show a more meaningful message: "Message: ERROR:  permission denied to set parameter "session_replication_role", SQL: 'set session_replication_role to replica;'". In order to give the database user otobo the needed superuser privileges, run the following statement as the PostgreSQL admin: ALTER USER otobo WITH SUPERUSER;. Then retry running http://localhost/otobo/migration.pl. After the migration, return to the normal state by running ALTER USER otobo WITH NOSUPERUSER.

It is not clear yet, whether the extended privileges have to be granted in every setup.

See also

The discussion in https://otobo.de/de/forums/topic/otrs-6-mysql-migration-to-otobo-postgresql/.

5. Problems with the Deployment the Merged System Configuration

The system configuration is migrated after the database tables were migrated. In this context, migration means merging the default settings of OTOBO with the system configuration of the source OTRS system. Inconsistencies can arise in this step. An real life example is the setting Ticket::Frontend::AgentTicketQuickClose###State. This setting is new in OTOBO 10 and the default value is the state closed successful. But this setting is invalid when the state closed successful has been dropped or renamed in the source system. This inconsistency is detected as an error in the migration step Migrate configuration settings. Actually, the merged system configuration is stored in the database, but additional validity checks are performed during deployment.

The problem must be alleviated manually by using OTOBO console commands.

List the inconsistencies with the command bin/otobo.Console.pl Admin::Config::ListInvalid

Interactively fix the invalid values with bin/otobo.Console.pl Admin::Config::FixInvalid

Deploy the collected changes from migration.pl, including the deactivated SecureMode with bin/otobo.Console.pl Maint::Config::Rebuild

After these manual steps you should be able to run migration.pl again. The migration will continue with the step where the error occurred.

Step 7: Manual Migration Tasks and Changes

1. Password Policy Rules

With OTOBO 10 a new default password policy for agent and customer users is in effect, if local authentication is used. The password policy rules can be changed in the system configuration (PreferencesGroups###Password and CustomerPersonalPreference###Password).

Password Policy Rule | Default
PasswordMinSize | 8
PasswordMin2Lower2UpperCharacters | Yes
PasswordNeedDigit | Yes
PasswordHistory | 10
PasswordTTL | 30 days
PasswordWarnBeforeExpiry | 5 days
PasswordChangeAfterFirstLogin | Yes

2. Under Docker: Manually Migrate cron Jobs

In a non-Docker installation of OTOBO, there is at least one cron job which checks the health of the Daemon. Under Docker, this cron job no longer exists. Furthermore, there is no cron daemon running in any of the Docker containers. This means that you have to look for an individual solution for OTRS systems with customer-specific cron jobs (e.g., backing up the database).

Special Topics

Migration from Oracle to Oracle

For migration to Oracle the ETL-like strategy must be employed. This is because Oracle provides no easy way to temporarily turn off foreign key checks.

On the OTOBO host a Oracle client and the Perl module DBD::Oracle must be installed.

Note

When using the Oracle instant client, then the optional SDK is also needed for installing DBD::Oracle.

There are many ways of cloning a schema. In the sample commands we use expdb and impdb which use Data Pump under the hood.

Note

The connect strings shown in this documentation refer to the case when both source and target database run in a Docker container. See also https://github.com/bschmalhofer/otobo-ideas/blob/master/oracle.md .

Clear out OTOBO

Stop the webserver for OTOBO, so that the DB connection for OTOBO is closed.

-- in the OTOBO database
DROP USER otobo CASCADE

Export the complete OTRS schema.

mkdir /tmp/otrs_dump_dir

-- in the OTRS database
CREATE DIRECTORY OTRS_DUMP_DIR AS '/tmp/otrs_dump_dir';
GRANT READ, WRITE ON DIRECTORY OTRS_DUMP_DIR TO sys;

expdp \"sys/Oradoc_db1@//127.0.0.1/orclpdb1.localdomain as sysdba\" schemas=otrs directory=OTRS_DUMP_DIR dumpfile=otrs.dmp logfile=expdpotrs.log

Import the OTRS schema, renaming the schema to otobo.

impdp \"sys/Oradoc_db1@//127.0.0.1/orclpdb1.localdomain as sysdba\" directory=OTRS_DUMP_DIR dumpfile=otrs.dmp logfile=impdpotobo.log remap_schema=otrs:otobo

-- in the OTOBO database
-- double check
select owner, table_name from all_tables where table_name like 'ARTICLE_DATA_OT%_CHAT';

-- optionally, set the password for the user otobo
    ALTER USER otobo IDENTIFIED BY XXXXXX;

Adapt the cloned schema otobo:

cd /opt/otobo
scripts/backup.pl --backup-type migratefromotrs # it's OK that the command knows only about the otobo database, only last line is relevant
sqlplus otobo/otobo@//127.0.0.1/orclpdb1.localdomain < /home/bernhard/devel/OTOBO/otobo/2021-03-31_13-36-55/orclpdb1.localdomain_post.sql >sqlplus.out 2>&1
double check with `select owner, table_name from all_tables where table_name like 'ARTICLE_DATA_OT%_CHAT';

Start the web server for OTOBO again

Proceed with step 5, that is with running migration.pl.

Note

If migrating to OTOBO version greater or equal 10.1 the script /opt/otobo/scripts/DBUpdate-to-10.1.pl has to be executed, to create the tables stats_report & data_storage, which were newly added in version 10.1.

Optional Step: Streamlined Migration of the Database (only for Experts and Special Scenarios)

In the general migration strategy, all data in the database tables is copied row by row from the OTRS database into the OTOBO database. Exporting the data from the OTRS database and importing it into the OTOBO database might save time and is more stable in some circumstances.

Note

This variant works for both Docker-based and native installations.

Note

These instructions assume that OTRS is using MySQL as its backend.

First of all, we need a dump of the needed OTRS database tables. Then we need to perform a couple of transformations:

convert the character set to utf8mb4

rename a couple of tables

shorten some table columns

After the transformation we can overwrite the tables in the OTOBO schema with the transformed data from OTRS. Effectively we need not a single dump file, but several SQL scripts.

When mysqldump is installed and a connection to the OTRS database is possible, you can create the database dump directly on the Docker host. This case is supported by the script bin/backup.pl.

Warning

This requires that an OTOBO installation is available on the Docker host.

cd /opt/otobo
scripts/backup.pl -t migratefromotrs --db-name otrs --db-host=127.0.0.1 --db-user otrs --db-password "secret_otrs_password"

Note

Alternatively, the database can be dumped on another server and then be transferred to the Docker host afterwards. An easy way to do this is to copy /opt/otobo to the server running OTRS and perform the same command as above.

The script bin/backup.pl generates four SQL scripts in a dump directory, e.g., in 2021-04-13_12-13-04 In order to execute the SQL scripts, we need to run the command mysql.

Native installation:

cd <dump_dir>
mysql -u root -p<root_secret> otobo < otrs_pre.sql
mysql -u root -p<root_secret> otobo < otrs_schema_for_otobo.sql
mysql -u root -p<root_secret> otobo < otrs_data.sql
mysql -u root -p<root_secret> otobo < otrs_post.sql

Docker-based installation:

Run the command mysql within the Docker container db for importing the database dump files. Note that the password for the database root is now the password that has been set up in the file .env on the Docker host.

cd /opt/otobo-docker
docker compose exec -T db mysql -u root -p<root_secret> otobo < /opt/otobo/<dump_dir>/otrs_pre.sql
docker compose exec -T db mysql -u root -p<root_secret> otobo < /opt/otobo/<dump_dir>/otrs_schema_for_otobo.sql
docker compose exec -T db mysql -u root -p<root_secret> otobo < /opt/otobo/<dump_dir>/otrs_data.sql
docker compose exec -T db mysql -u root -p<root_secret> otobo < /opt/otobo/<dump_dir>/otrs_post.sql

For a quick check whether the import worked, you can run the following commands.

mysql -u root -p<root_secret> -e 'SHOW DATABASES'
mysql -u root -p<root_secret> otobo -e 'SHOW TABLES'
mysql -u root -p<root_secret> otobo -e 'SHOW CREATE TABLE ticket'

When running under Docker:

docker compose exec -T db mysql -u root -p<root_secret> -e 'SHOW DATABASES'
docker compose exec -T db mysql -u root -p<root_secret> otobo -e 'SHOW TABLES'
docker compose exec -T db mysql -u root -p<root_secret> otobo -e 'SHOW CREATE TABLE ticket'

The database is now migrated. This means that during the next step we can skip the database migration. Watch out for the relevant checkbox.

Backup and Restore

OTOBO has built in scripts for backup and restore scripts/backup.pl and scripts/restore.pl. Execute the scripts with the option -h for more information.

Backup

In order to backup the OTOBO system, the script scripts/backup.pl can be used. The script creates a backup of the OTOBO system in the specified directory.

Note

To create a new backup, write permission for the destination directory is needed for the user otobo.

/opt/otobo/scripts/backup.pl -h

The output of the script:

Backup an OTOBO system.

Usage:
 backup.pl -d /data_backup_dir [-c gzip|bzip2] [-r DAYS] [-t fullbackup|nofullbackup|dbonly]
 backup.pl --backup-dir /data_backup_dir [--compress gzip|bzip2] [--remove-old-backups DAYS] [--backup-type fullbackup|nofullbackup|dbonly]

Short options:
 [-h]                   - Display help for this command.
 -d                     - Directory where the backup files should place to.
 [-c]                   - Select the compression method (gzip|bzip2).\ Default: gzip.
 [-r DAYS]              - Remove backups which are more than DAYS days old.
 [-t]                   - Specify which data will be saved (fullbackup|nofullbackup|dbonly).\ Default: fullbackup.

Long options:
 [--help]                     - same as -h
 --backup-dir                 - same as -d
 [--compress]                 - same as -c
 [--remove-old-backups DAYS]  - same as -r
 [--backup-type]              - same as -t

Help:
Using -t fullbackup saves the database and the whole OTOBO home directory (except /var/tmp and cache directories).
Using -t nofullbackup saves only the database, /Kernel/Config* and /var directories.
With -t dbonly only the database will be saved.

Override the max allowed packet size:
When backing up a MySQL one might run into very large database fields.\ In this case the backup fails.
For making the backup succeed one can explicitly add the parameter --max-allowed-packet=<SIZE IN BYTES>.
This setting will be passed on to the command mysqldump.

Output:
 Config.tar.gz          - Backup of /Kernel/Config* configuration files.
 Application.tar.gz     - Backup of application file system (in case of full backup).
 VarDir.tar.gz          - Backup of /var directory (in case of no full backup).
 DataDir.tar.gz         - Backup of article files.
 DatabaseBackup.sql.gz  - Database dump.

Note

--extra-dump-options="--single-transaction" prevents the database tables from being locked, so OTOBO may still be used during backup archive creation.

Docker

The same scripts might be used when OTOBO is running under Docker, but some Docker specific limitations have to be considered. In order to be able to write a backup archive to the file system outside of the Docker container, appropriate volume mounts and permissions must be configured.

# create the backup directory on the host
mkdir otobo_backup

# give the backup dir to the user otobo.
# we use the UID and GID of the user otobo inside the container
chown 1000:1000 otobo_backup

# create the Docker volume
docker volume create --name otobo_backup \
  --opt type=none \
  --opt device=$PWD/otobo_backup \
  --opt o=bind

We use an ephemeral container of OTOBO to pull the backup and place it in the backup directory on the host:

docker run -it --rm --volume otobo_opt_otobo:/opt/otobo \
   --volume otobo_backup:/otobo_backup \
   --network otobo_default \
   rotheross/otobo:latest-11_0 scripts/backup.pl \
   --extra-dump-options="--single-transaction" -d /otobo_backup

The parameters used, assume the defaults presented throughout this manual. You may need to fit them to your setup, e.g., if you use a different network name or a different image tag.

Restore

To restore the OTOBO system from backup, the script scripts/restore.pl can be used. For the script to be able to place the data into the database, the database name, name, and password have to be setup like the backed up system. The restore script, restores the configuration files from the backup archive first, and then uses the restored configuration files to connect to the database and restore the data. You may read them from backup to fit your database setup:

tar -xOzf Config.tar.gz Kernel/Config.pm | grep '{Database'

You may also fit the database connection parameters within the backup file before running the restore script:

vim Config.tar.gz

Note

To restore the database make sure the target database contains no tables.

You may execute the restore script with the option -h for more information.

/opt/otobo/scripts/restore.pl -h

The output of the script:

Restore an OTOBO system from backup.

Usage:
 restore.pl -b /data_backup/<TIME>/ -d /opt/otobo/

Options:
 -b                     - Directory of the backup files.
 -d                     - Target OTOBO home directory.
 [-h]                   - Display help for this command.

After successful restore it is advised to clear the OTOBO cache. To do this execute the following command:

/opt/otobo/bin/otobo.Console.pl Maint::Cache::Delete

Docker

To drop an existing OTOBO database and create a new one you can use the following commands. First, you have to connect to the MariaDB command line interface of the db container:

cd /opt/otobo-docker
docker compose exec db mysql -u root -p

Enter the database root password when prompted. As soon as you are connected to the MySQL server, you can drop and recreate the otobo database:

DROP DATABASE otobo;
CREATE DATABASE otobo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON otobo.* TO 'otobo'@'%';

For restoring the backup we also need to specify which backup should be restored. The placeholder <TIMESTAMP> is something like 2020-09-07_09-38.

# restore a backup
docker run -it --rm \
  --volume otobo_opt_otobo:/opt/otobo \
  --volume otobo_backup:/otobo_backup \
  --network otobo_default \
  rotheross/otobo:latest-11_0 \
  scripts/restore.pl -d /opt/otobo -b /otobo_backup/<TIMESTAMP>

After successful restore it is advised to clear the OTOBO cache. To do this change to your OTOBO directory (by default /opt/otobo-docker) and execute the following command:

docker compose exec web bin/otobo.Console.pl Maint::Cache::Delete

Kerberos Single Sign On in OTOBO Docker installation

Please read to the chapter OTOBO Installation Docker for basic information about installing and configure OTOBO. This tutorial assumes that OTOBO has been installed and configured using Docker.

Note

In the following, we will refer from AD (Active Directory), of course the Kerberos configuration is also possible under LDAP.

Generate Active Directory User

Please create a new Active Directory User with the following settings and save the marked settings:

Note

Please use as Username only this syntax: HTTP/fqdn.from.your.otobo.de. fqdn.from.your.otobo.de needs to be a A-Record DNS entry, not a CNAME! In the next step, it is also possible to use other URLs for OTOBO, they must then point as CNAME to our A-record defined above.

The username part HTTP/ should be written in capital letters, as Kerberos expects it that way.

The password doesn’t work properly with some special characters (e.g. ‘&’).

You have to create a separate AD-user. You can not use the one that you already use for your LDAP/AD sync.

Generate Active Directory Keytab file

In the next step, we connect to a domain controller of the Active Directory and open a console (cmd) there with administrator privileges. Now we use the tool ktpass.exe to generate the needed keytab file:

ktpass.exe -princ HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL -mapuser OTRS\otrs32-centos6 -crypto All -pass Password -ptype KRB5_NT_PRINCIPAL -out c:\krb5.keytab

-princ = HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL → Picture Number 1 and 2

-mapuser = OTRS\otrs32-centos6  (Username prä Win 2000) → Picture Number 3 and 4

-pass = Password → from user otrs32-centos6 (Active Directory User)

-out = c:/krb5.keytab → storage location for the generated keytab file

Note

Please write the domain (@OTRS.LOCAL) always in capital letters. The password must not contain some special characters.

In the next step please move the krb5.keytab file to the OTOBO Server:

# Create new directory
mkdir /opt/otobo-docker/nginx-conf

# Move the file krb5.keytab to the new directory (Attention, depending on where you have placed the krb5.conf file, the command below will change.)
mv ?/krb5.keytab /opt/otobo-docker/nginx-conf/krb5.keytab

Create a new Volume for Your Custom Nginx Configuration

docker volume create otobo_nginx_custom_config
otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest-11_0 (watch out: version number)
docker cp tmp-nginx-container:/etc/nginx/templates /tmp
docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx-kerberos.conf.template.hidden $otobo_nginx_custom_config_mp/otobo_nginx.conf.template
docker rm tmp-nginx-container
vim docker-compose/otobo-nginx-custom-config.yml

Create new OTOBO .env File

First of all we need to move the old file /opt/otobo-docker/.env to .env.tmp and create a new .env file including the kerberos settings.

# Stop OTOBO Container if running
cd /opt/otobo-docker
docker compose down

# create a backup of the old .env file
mv /opt/otobo-docker/.env /opt/otobo-docker/.env.tmp

# create a new backup file including kerberos settings
cp /opt/otobo-docker/.docker_compose_env_https_kerberos /opt/otobo-docker/.env

Now copy your existing configuration options to the new .env file (at least OTOBO_DB_ROOT_PASSWORD, OTOBO_NGINX_SSL_CERTIFICATE, OTOBO_NGINX_SSL_CERTIFICATE_KEY) and insert the following Kerberos settings:

# Kerberos keytab
OTOBO_NGINX_KERBEROS_KEYTAB=/opt/otobo-docker/nginx-conf/krb5.keytab

# Kerberos config (Important, please comment out this option like here!)
# In default configuration the krb5.conf file is generated automatically
# OTOBO_NGINX_KERBEROS_CONFIG=/opt/otobo-docker/nginx-conf/krb5.conf

# Kerberos Service Name
OTOBO_NGINX_KERBEROS_SERVICE_NAME=HTTP/otrs32-centos6.otrs.local # -> Picture Number 1

# Kerberos REALM
OTOBO_NGINX_KERBEROS_REALM=ROTHER-OSS.COM -> OTRS.LOCAL # -> Picture Number 2

# Active Directory Domain Controller / Kerberos kdc
OTOBO_NGINX_KERBEROS_KDC=

# Active Directory Domain Controller / Kerberos Admin Server
OTOBO_NGINX_KERBEROS_ADMIN_SERVER=rother-oss.com

# Kerberos Default Domain
OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN=otrs.local

Start OTOBO

After the initial Kerberos configuration we start OTOBO again:

# Start OTOBO using Docker Compose
docker compose up -d

Tell OTOBO to use the Kerberos-Authentication

In case you have configured AD-Authentication, de-activate it (e.g. by commenting out the respective lines from your Kernel/Config.pm). The authentication will not take place via LDAP anymore.

To use Kerberos-Authentication take the Kerberos-lines from Kernel/Config/Defaults.pm and put it into you Kernel/Config.pm E.g. these lines could work:

$Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth';

# In case you need to replace some part of the REMOTE_USER, you can
# use the following RegExp ($1 will be new login).
$Self->{'AuthModule::HTTPBasicAuth::ReplaceRegExp'} = '^(.+?)@.+?$';

Configure Browser to Understand Kerberos SSO

For SSO to work, the browser must be configured accordingly.

Chrome, Edge, Internet Explorer, etc.

Add page under local or trusted pages and activate ‘Integrated Windows Authentication’ (Internet Options).

Firefox

Enter “about:config” in the firefox address line

and change the following settings:

network.negotiate-auth.trusted-uris = https:// (or https://otobofqdn)
network.negotiate-auth.delegation-uris = http:// (or https://otobofqdn)

Debugging and Problems

If the Kerberos SSO does not work, please check first if the NGINX container is started:

# Check Container
docker ps

In the next step please check the NGINX logs for more information:

# Check NGINX logs
docker compose logs nginx -f

If NGINX is running, please login into the NGINX Container and check all needed files:

# Now please check if the krb5.conf file exists with your needed values
docker compose exec nginx cat /etc/krb5.conf

# Now please check if the krb5.keytab file exists
docker compose exec nginx cat /etc/krb5.keytab

# If not, please quit from the container and copy the file again using docker
docker compose cp /opt/otobo-docker/nginx-conf/krb5.keytab nginx:/etc/krb5.keytab

Kerberos Debugging

# Login to the NGINX Container
docker compose exec nginx bash

Now you are able to debug the Kerberos settings. Examples:

env KRB5_TRACE=/dev/stdout kvno HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL
klist -e

kinit -VV -k -t /etc/krb5.keytab HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL

kinit username@OTRS.LOCAL

In case you stumble upon the issue that apparently the authentication works but the agent is not yet in the database, then your sync (if implemented) might not work. An error 52e (First bind failed) indicates that something is wrong with your Search User. This happens if you use the same user for the AD sync and as a SSO user. Please use separate AD users for that. In order to not have to create a new keytab and having to repeat the steps mentioned above, it could be easier to create a new user to use in your AD sync (probably in your Kernel/Config.pm).

In case SSO is not working properly, make sure: * the user for which it is not working is in Active Directory * the system has to be in the domain * it is properly stated as a trusted page (see ‘Configure Browser to understand Kerberos SSO’)

Kerbeos Single Sign On for OTOBO Native Installation

In this instruction we setup the

Active Directory

OTOBO Linux server

User browser setup

to ensure the AD user seamless authorization into OTOBO.

Note

Please read the chapter OTOBO Installation for basic information about installing and configure OTOBO. This manual assumes that OTOBO has been installed and configured using Nginx.

Kerberos SSO Overview

To avoid manual creation of Agents accounts, OTOBO allows users and agents to login in OTOBO using their AD credentials.

Note

For agents LDAP auth backend example, in Kernel/Config/Defaults.pm search

$Self->{'AuthModule'} = 'Kernel::System::Auth::Sync::LDAP';

We can do even better and authenticate users and agents fully automatically, skipping the login screen entirely. This is called Single Sign-On (SSO) and could be done using Kerberos protocol.

Note

The SSO setup with Kerberos is quite complex. You may stay with LDAP and avoid all the headache.

SSO Authentication Process Overview

user logins into windows using his AD credentials

user opens OTOBO website with a browser

browser and webserver do some Kerbeos crypto-magic

browser pass the name of the authorized user to OTOBO

OTOBO trust the username passed in the REMOTE_USER environment variable or the Remote-User HTTP header and skips the login screen

Kerberos SSO Setup

In our example OTOBO runs at https://otobo.company.com/ . AD controller should be able to reach the OTOBO service by its name using DNS A-Record!

AD domain name is “DOMAIN” (because it may differ from “COMPANY.COM”).

OTOBO is a service in Kerberos terminology Service communicates with AD using a service account. Let service account name be “serviceaccount”.

Active Directory Settings

Login on AD controller under administrator. Open “Active Directory Users and Computers” application. Inside the Users container, create a new account:

User logon name (warning - here are two fields): HTTP/otobo.company.com @DOMAIN.COM

user logon name (pre Windows 2000) (two fields): DOMAIN\ serviceaccount

in account options: set checkbox on:

this account supports Kerberos-AES-128

this account supports Kerberos-AES-256

Register an Service Principal Name (SPN) for the OTOBO service. Open a terminal and run:

setspn -A HTTP/otobo.company.com DOMAIN\serviceaccount

Check that SPN has been added. Distinguished Name - that includes CN, DC, OU - can be different depending from your AD structure. Important is that you see your service principal name (HTTP/...).

setspn -L DOMAIN\serviceaccount
Registered Serviceprincipalname (SPN) for CN=OTOBO,DC=company,DC=com:
    HTTP/otobo.company.com

Generate Keytab File

Note

Keytab is a cryptographic file containing a representation of the service and its long-term key as it exists in the directory service. In our Active Directory domain, keytab file will be used by the Webserver (that runs on Linux) to authenticate users against AD via Kerberos protocol.

Login into AD under domain administrator account and generate keytab file using ktpass:

ktpass -out krb5.keytab -princ HTTP/otobo.company.com@DOMAIN.COM -mapuser DOMAIN\serviceaccount -crypto All -pass <serviceaccount_password> -ptype KRB5_NT_PRINCIPAL

Setup Kerberos Client on the OTOBO Server

Copy the keytab file from the AD controller to the OTOBO server:

scp krb5.keytab root@otobo.company.com:/etc/krb5.keytab

Login on the Linux server and install Kerberos client libraries:

DEBIAN_FRONTEND=noninteractive apt install -y krb5-user

Note

DEBIAN_FRONTEND=noninteractive is required to skip inital keytab configuration since the keytab file is configured manually.

Now check the keytab file content:

root@otobo:~# klist -kte /etc/krb5.keytab
Keytab name: FILE:/etc/krb5.keytab
KVNO Timestamp           Principal
---- ------------------- ------------------------------------------------------
  11 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (DEPRECATED:des-cbc-crc)
  11 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (DEPRECATED:des-cbc-md5)
  11 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (DEPRECATED:arcfour-hmac)
  11 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (aes256-cts-hmac-sha1-96)
  11 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (aes128-cts-hmac-sha1-96)

Configure your domain in /etc/krb5.conf:

[libdefaults]
    default_realm = DOMAIN.COM

    # The following krb5.conf variables are only for MIT Kerberos.
    kdc_timesync = 1
    ccache_type = 4
    forwardable = true
    proxiable = true
    rdns = false

    # The following libdefaults parameters are only for Heimdal Kerberos.
    fcc-mit-ticketflags = true

[realms]
    TR-GRUPPE.DE = {
        kdc = domain_controller.company.com
        admin_server = domain_controller.company.com
    }

Then try to obtain a ticket-granting ticket (TGT) from AD:

kinit -V HTTP/otobo.company.com -k -t /etc/krb5.keytab
Using keytab: /etc/krb5.keytab
Authenticated to Kerberos v5

This is a correct answer. Goto webserver section.

Error: No Suitable Keys for Service

kinit -V HTTP/otobo.company.com -k -t /etc/krb5.keytab
kinit: Keytab contains no suitable keys for HTTP/otobo.company.com@DOMAIN.COM while getting initial credentials

Double check your kinit arguments. If arguments are correct, but you still got this error, the keytab may have an incorrect SPN inside.

List the SPN entries in keytab: klist -kte krb5.keytab.

The list should contain exact principal (service account) name (+ AD domain name), that you have registered in AD, e.g.

1 01/01/1970 00:00:00 HTTP/otobo.company.com@DOMAIN.COM (DEPRECATED:arcfour-hmac)

If not, you probably had mistyped the ktpass command arguments and have to regenerate the keytab file.

Error: Client not Found in Kerberos

kinit -V HTTP/otobo.company.com -k -t /etc/krb5.keytab
kinit: Client 'HTTP/otobo.company.com@DOMAIN.COM' not found in Kerberos database while getting initial credentials

This error happens when:

service user name (serviceaccount) in keytab file and in AD are different

service user password from keytab file and AD differs

if serviceaccount password has been changed in AD - regenerate the keytab file

SPN (Service Principal Name) was not registered or differs from the Principal name in the keytab file.

Check if SPN is registered for “serviceaccount” - under AD user on windows run setspn -L DOMAIN\serviceaccount

The output SPN should match with the output of klist -kte krb5.keytab

Nginx with Kerberos SSO and SSL

Note

If Nginx is not already up and running refer to Otobo basic installation manual

Install required Nginx modules:

sudo apt install -y libnginx-mod-http-auth-spnego

Ensure that the file permissions for /etc/krb5.keytab are set correctly:

sudo chown root:www-data /etc/krb5.keytab
sudo chmod 640 /etc/krb5.keytab

Note

The name of the webserver group can change depending on your OS. For SUSE and Red Hat/CentOS/Fedora it is called nginx. On Debian and Ubuntu www-data.

The following Nginx config file /etc/nginx/sites-available/nginx.conf should replace your previous default config file. It should contain the this content:

# Config for nginx serving as a reverse proxy for the OTOBO web application.

# This config is based on default.conf in the nginx installation

# The master process runs as root.
# When no user is configured then the workers will run as nobody.
#user

proxy_send_timeout 120;
proxy_read_timeout 99999;
proxy_buffering    off;
tcp_nodelay        on;

# Do not serve HTTP, redirect to HTTPS instead.
# See https://linuxize.com/post/redirect-http-to-https-in-nginx/.
server {
    listen 80;
    listen [::]:80;

    # catch all domains
    server_name _;

    # 301 Moved Permanently, (in 'SEO-speak', it is said that the 'link-juice' is sent to the new URL).
    return 301 https://otobo.company.com$request_uri;
}

# serve HTTPS
server {
    listen 443 ssl http2;                # falls back to regular HTTPS over HTTP/1.1 when the browser does not support HTTP/2
    listen [::]:443 ssl http2;

    # See https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04
    # See https://ssl-config.mozilla.org/
    include snippets/ssl-params.conf;
    ssl_certificate     /etc/ssl/certs/otobo.de.cert;
    ssl_certificate_key /etc/ssl/private/otobo.de.nopass.key;

    server_name  otobo.company.com;

    # allow large uploads of files
    client_max_body_size 1G;

    #access_log  /var/log/nginx/host.access.log  main;

    # proxy to the otobo webapp accessible from the host
    # pass on information about the client
    location / {

        # Settings for using Kerberos SSO (mostly untested)
        proxy_set_header                REMOTE_USER $remote_user;
        auth_gss                        on;
        auth_gss_keytab                 /etc/krb5.keytab;
        auth_gss_service_name           HTTP/otobo.company.com;
        auth_gss_realm                  DOMAIN.COM;
        auth_gss_allow_basic_fallback   on;

        proxy_set_header X-Forwarded-Host $host:$server_port;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass       http://localhost:5000/;
    }
}

Note

Make sure to replace ssl_certificate and ssl_certificate_key with your custom ssl configuration. Adjust auth_gss_service_name and auth_gss_realm with values depending on your Kerberos Realm setup.

If you have the old Nginx configuration for Otobo - don’t forget to disable it.

Enable our website

sudo ln -s /etc/nginx/sites-available/nginx.conf /etc/nginx/sites-enable/nginx.conf
sudo systemctl reload nginx

Ensure the webserver sends a proper header, that invites browser to use Kerberos authentication:

curl -v localhost:443

output should have a following header:

WWW-Authenticate: Negotiate …

Otobo Configuration

To make Otobo trust the username passed by the webserver (in the REMOTE_USER environment variable or the Remote-User HTTP header) and skip the login screen, you have to enable a HTTPBasicAuth auth backend in the Otobo configuration Kernel/Config.pm:

for agents: $Self->{AuthModule} = 'Kernel::System::Auth::HTTPBasicAuth (instead of LDAP)

for users: $Self->{'Customer::AuthModule'} = 'Kernel::System::CustomerAuth::HTTPBasicAuth';

You still can use LDAP to populate Users data from the AD, as it is described in the corresponding sections of``Kernel/Config/Defaults.pm``

Configure Browser to Understand Kerberos SSO

In the browser address line, open about:config and change the following settings:

network.negotiate-auth.trusted-uris = https://otobo.company.com
network.negotiate-auth.delegation-uris = https://otobo.company.com
network.automatic-ntlm-auth.trusted-uris = https://otobo.company.com  # a fallback ntlm windows mechanism, not sure if needed
signon.autologin.proxy = true

Adapt Customer Interface with Corporate Identity

In OTOBO it is very easy to adapt the customer area to your own corporate identity. Follow this tutorial step by step and OTOBO will shine in your own design in a short time.

Note

Currently, it is not so easy to adapt the agent area to one’s own CI. Changes in the OTOBO .css files would be necessary here. One exception is the logo on the agent login page and the agent header. The logos can be easily exchanged by copying the logos to the server and then adjusting the options AgentLoginLogo and AgentLogo under Admin -> System Configuration.

Change Colors in Customer Area

To change the colors for the OTOBO customer interface, please go to Admin -> System Configuration and change the following settings:

CustomerColorDefinitions

To change the colors on the Customer Dashboard, please go to Admin -> System Configuration and search for CustomerDashboard. In the search result you will find all the options you need with color definitions.

Change Logos and Pictures

In the first step please copy your Logos and Pictures to the OTOBO Server. Please use an SCP client (e.g., WinSCP) for this purpose. Often you do not have the permissions to copy the logos to the right place. In this case, it is best to use the folder /tmp.

In the next step copy the logo into the OTOBO home directory:

# Using OTOBO Docker Installation
docker cp /tmp/logo.png otobo-web-1:/opt/otobo/var/httpd/htdocs/skins/Customer/default/img/

# Nativ installation in /opt/otobo
cp /tmp/logo.png /opt/otobo/var/httpd/htdocs/skins/Customer/default/img/

The next sections describe the changes required in the OTOBO Agent Interface.

Change Customer Login Pictures and Text

Navigate to Admin -> System Configuration and change the following settings.

1 and 2 - System Configuration option CustomerLogin::Settings

Remove Opacity and Watermark

Note

At the moment it is not possible to remove the overlay and watermark used in the image on the right by system configuration.

To remove the opacity, please adjust the option #oooLoginBG > .oooBG in the file var/httpd/htdocs/skins/Customer/default/css/Core.Login.css:

 #oooLoginBG > .oooBG {
    position: relative;
    width: 100%;
    height: 100%;
 /*   opacity: 0.45; Disable opacity */
    background-size: cover;
    overflow: hidden;
}

To remove the watermark, please remove the following line inside the file Kernel/Output/HTML/Templates/Standard/CustomerLogin.tt:

<!-- start login -->
<div id="oooLoginBG">
    <div class="oooBG" style="background-image: url([% Data.Background | html %]);">
<!-- remove this line: <div id="oooBGSignet" style="background-image: url([% Config("Frontend::WebPath") %]common/img/otobo-signet_border.svg);"></div> -->
    </div>
    <h1>[% Translate(Data.LoginText) | html %]</h1>
</div>

Note

Please add the files to a OPM package in the next step, so that the changes remain persistent. You can find instructions on how to do this in our Admin Manual: https://doc.otobo.org/manual/developer/11.0/en/content/how-to-publish-otobo-extensions.html

Change Customer Dashboard Tiles and Options

To change the colors on the Customer Dashboard, please go to Admin -> System Configuration and search for CustomerDashboard. In the search result you will find all the options you need with color definitions.

1 - To change the picture, link and text please use the System Configuration option CustomerDashboard::Tiles###FeaturedLink-01

2 - To change the toplevel text please use the System Configuration option CustomerDashboard::Configuration::Text

Note

Please disable the configuration options from not needed tiles.

Installing Perl Modules from CPAN

When there are special requirements then the need for additional Perl modules may arise. Fortunately, Perl has an excellent package repository that can satisfy almost all needs. That repository is called CPAN and is available at https://metacpan.org/.

It is recommended to use the command line client cpanm for installing modules. cpanm is often already installed on your system. Please see https://metacpan.org/pod/App::cpanminus for what to do when is isn’t already available.

Alternatively, many Perl modules are also available as packages for your operating system. These packages can be installed with your systems regular package manager.

Per default cpanm installs modules into a system-wide location. In this case modules must be installed as the root user. For example, the command

cpanm -M https://cpan.metacpan.org Acme::Dice

results in:

perldoc -l Acme::Dice
# /usr/local/share/perl/5.30.0/Acme/Dice.pm

Docker-based Installations

Special care must be taken when OTOBO runs under Docker. In this case an installation into a system-wide location would initially work as well. However, due to how Docker works, this installed modules would be lost when the container is restarted. Therefore, the modules must be installed into a location that does survive a restart. The directory /opt/otobo/local within the volume otobo_opt_otobo can be used for that. Modules that are installed in /opt/otobo/local will be picked up by Perl because the environment variables PERL5LIB and PATH are preset accordingly.

The installed Perl modules will also be available after an upgrade of OTOBO. There is the general rule that files added to /opt/otobo won’t be removed by an upgrade.

For installing Perl modules in a specific location we need to modify our install command. Specifically, we need to add the option --local-lib. Here is a sample session in the container web.

# starting a bash session in the container web
docker_admin> cd /opt/otobo-docker/
docker_admin> docker compose exec web bash
otobo@6ef90ed00cd0:~$ pwd
/opt/otobo

# installing the sample module Acme::Dice
otobo@6ef90ed00cd0:~$ cpanm --local-lib local -M https://cpan.metacpan.org Acme::Dice
--> Working on Acme::Dice
Fetching http://www.cpan.org/authors/id/B/BO/BOFTX/Acme-Dice-1.01.tar.gz ... OK
Configuring Acme-Dice-1.01 ... OK
Building and testing Acme-Dice-1.01 ... OK
Successfully installed Acme-Dice-1.01
1 distribution installed

# confirm the installation directory
otobo@6ef90ed00cd0:~$ perldoc -l Acme::Dice
/opt/otobo/local/lib/perl5/Acme/Dice.pm

# locally installed module is found because the environment is preset accordingly
otobo@6ef90ed00cd0:~$ echo $PERL5LIB
/opt/otobo_install/local/lib/perl5:/opt/otobo/local/lib/perl5
otobo@6ef90ed00cd0:~$ echo $PATH
/opt/otobo_install/local/bin:/opt/otobo/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Performance Tuning

This is a list of performance enhancing techniques for your OTOBO installation. The topics include configuration, coding, memory use, and more.

Ticket Index Module

Ticket index module can be set via system configuration setting Ticket::IndexModule. There are two back end modules building the index for the ticket queue view:

Kernel::System::Ticket::IndexAccelerator::RuntimeDB

This is the default option, which will generate each queue view on the fly from the ticket table. You will not have performance trouble until you have about 60,000 open tickets in your system.

Kernel::System::Ticket::IndexAccelerator::StaticDB

The most powerful module, should be used when you have above 80,000 open tickets. It uses an extra ticket_index table, which will be populated with keywords based on ticket data. Use the following command for generating an initial index after switching back ends:

/opt/otobo/bin/otobo.Console.pl Maint::Ticket::QueueIndexRebuild

Ticket Search Index

OTOBO uses a special search index to perform full-text searches across fields in articles from different communication channels.

To create an initial index, use this command:

/opt/otobo/bin/otobo.Console.pl Maint::Ticket::FulltextIndex --rebuild

Note

Actual article indexing happens via an OTOBO daemon job in the background. While articles which were just added in the system are marked for indexing immediately, it could happen their index is available only after a few minutes.

There are some options available for fine-tuning the search index:

Ticket::SearchIndex::IndexArchivedTickets

Defines if archived tickets will be included in the search index (disabled by default). This is advisable to keep the index small on large systems with archived tickets. If this is enabled, archived tickets will be found by full-text searches.

Ticket::SearchIndex::Attribute

Basic full-text index settings.

[picture]

Ticket::SearchIndex::Attribute Setting

Note

Run the following command in order to generate a new index:

otobo> /opt/otobo/bin/otobo.Console.pl Maint::Ticket::FulltextIndexRebuild

WordCountMax

Defines the maximum number of words which will be processed to build up the index. For example only the first 1000 words of an article body are stored in the article search index.

WordLengthMin and WordLengthMax

Used as word length boundaries. Only words with a length between these two values are stored in the article search index.

Ticket::SearchIndex::Filters

Filters based on regular expressions exclude parts of the original text from the full-text index.

[picture]

Ticket::SearchIndex::Filters setting

There are three default filters defined:

The first filter strips out special chars like: , & < > ? " ! * | ; [ ] ( ) + $ ^ =

The second filter strips out words which begin or end with one of following chars: ' : .

The third filter strips out words which do not contain a word character: a-z, A-Z, 0-9, _

Ticket::SearchIndex::StopWords

English stop words for full-text index. These words will be removed from the search index.

[picture]

Ticket::SearchIndex::StopWords###en setting

There are so-called stop-words defined for some languages. These stop-words will be skipped while creating the search index.

See also

If your language is not in the system configuration settings or you want to add more words, you can add them to this setting:

Ticket::SearchIndex::StopWords###Custom

Document Search

OTOBO uses Elasticsearch for its document search functionality. For a good introduction into the concepts, installation and usage of Elasticsearch, please follow the Getting Started guide.

Heap Size

Elasticsearch is written in Java and therefore runs in a Java Virtual Machine (JVM) on any cluster node. Such a JVM uses a part of the memory, called heap, which size can be configured in configuration file jvm.options.

The heap minimum and maximum configurations are by default set to a value of 1 GB and can be modified with the following options:

Xms1g: minimum heap size.

Xmx1g: maximum heap size.

If the Xms has a lower value than Xmx, the JVM will resize the used heap anytime the current limit is exceeded, until the value of Xmx is reached. Such a resizing causes the service to pause until it is finished, which may decrease the speed and reactivity of the search or indexing actions. Therefore it is highly recommended to set those configurations to an equal value.

Warning

If the maximum heap size is exceeded, the related cluster node stops working and might even shutdown the service.

The higher the heap maximum value is set, the more memory can be used by Elasticsearch, which also increases the possible pauses for garbage collection, done by the JVM. Therefore it is recommended to set a value for Xmx, that is not higher than 50% of the physical memory.

For more information and good rules of thumb about the heap size, please follow the official documentation.

Disk Allocation

While running the service, Elasticsearch inspects the available disk space. Based on the result, it decides whether to allocate new shards to a cluster node. In some cases it even relocates shards away from a node. This behavior is determined by the current disk capacity. It can be configured by settings in the configuration file elasticsearch.yml. Here are some relevant configuration settings. They come with good default values, but might be important in trouble shooting.

cluster.routing.allocation.disk.watermark.low

Default value of 85%. When this limit is exceeded, Elasticsearch will no longer allocate more shards to the related cluster node. The operation of that node is not influenced and data can still be indexed and searched.

cluster.routing.allocation.disk.watermark.high

Default value of 90%. When this limit is exceeded, Elasticsearch will try to relocate existing shards to other nodes that have enough space available.

cluster.routing.allocation.disk.watermark.flood_stage

Default value of 95%. When this limit is exceeded, Elasticsearch will update the configuration of all indices, that have at least one shard allocated to the related cluster node, to read-only index blocks. Specifically, they are flagged with index.blocks.read_only_allow_delete. After that update, it is no longer possible to index new data to such indices. The indexes are restricted to searches and to delete actions only.

Note

If the flood stage was exceeded and certain indices are configured to read-only mode, such configuration will not automatically be changed by Elasticsearch. If the related disks contain enough free space again due to manual actions, it is needed to change the configuration back to normal mode manually.

For more information about disk watermarks and disk-based shard allocation, please follow the official documentation.

Article Storage

There are two different back end modules for the article storage of phone, email and internal articles. The used article storage can be configured in the setting Ticket::Article::Backend::MIMEBase::ArticleStorage.

Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageDB

This default module will store attachments in the database. It also works with multiple front end servers, but requires much storage space in the database.

Note

Don’t use this with large setups.

Kernel::System::Ticket::Article::Backend::MIMEBase::ArticleStorageFS

Use this module to store attachments on the local file system. It is fast, but if you have multiple front end servers, you must make sure the file system is shared between the servers. Place it on an NFS share or preferably a SAN or similar solution.

Note

Recommended for large setups.

You can switch from one back end to the other on the fly. You can switch the back end in the system configuration, and then run this command line utility to put the articles from the database onto the file system or the other way around:

otobo> /opt/otobo/bin/otobo.Console.pl Admin::Article::StorageSwitch --target ArticleStorageFS

You can use the --target option to specify the target back end.

Note

The entire process can take considerable time to run, depending on the number of articles you have and the available CPU power and/or network capacity.

If you want to keep old attachments in the database, you can activate the system configuration option Ticket::Article::Backend::MIMEBase::CheckAllStorageBackends to make sure OTOBO will still find them.

Archiving Tickets

As OTOBO can be used as an audit-proof system, deleting closed tickets may not be a good idea. Therefore there is a feature that allows you to archive tickets.

Tickets that match certain criteria can be marked as archived. These tickets are not accessed if you do a regular ticket search or run a generic agent job. The system itself does not have to deal with a huge amount of tickets any longer as only the latest tickets are taken into consideration when using OTOBO. This can result in a huge performance gain on large systems.

To use the archive feature:

Activate the Ticket::ArchiveSystem setting in the system configuration.

Define a generic agent job:

Click on the Add Job button in the Generic Agent screen.

Job Settings: provide a name for the archiving job.

Automatic Execution: select proper options to schedule this job.

Select Tickets: it might be a good idea to only archive those tickets in a closed state that have been closed a few months before.

Update/Add Ticket Attributes: set the field Archive selected tickets to archive tickets.

Save the job at the end of the page.

Click on the Run this task link in the overview table to see the affected tickets.

Click on the Run Job button.

Note

Up to 5000 tickets can be modified by running this job manually.

When you search for tickets, the system default is to search tickets which are not archived.

To search for archived tickets:

Open the ticket search screen.

Set Archive search to Unarchived tickets or All tickets.

Perform the search.

Caching

A fast cache module is a great help in terms of performance. In sepcial cases it might be applicable to use Redis for caching.

Install a Redis Cache Server

The following chapter describes the installation and configuration of Redis on either Docker-based or native installations.

1. Install Redis Server

First of all you need to install the Redis Server.

On native installations, setup Redis on the same host as OTOBO and binding it to its default port.

When using OTOBO Docker the Redis service is provided in an override at docker-compose/caching/redis.yml. In order to add it to your Docker Compose Stack you have to include it in the COMPOSE_FILE environment variable. Append it to the end of the ‘:’-separated list. Change the variable in the /opt/otobo-docker/.env env file.

# /opt/otobo-docker/.env

COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose/otobo-base.yml: ... :docker-compose/caching/redis.yml # <-- Right here

...

After this the compose stack needs to be restarted.

cd /opt/otobo-docker
sudo docker compose down && docker compose up -d

1. Install Perl Module

Note

Docker users can skip this part as the module is already included in the provided image.

Either Redis or Redis::Fast (recommend, ~2x faster) have to be installed. Use otobo.CheckModules.pl --list to choose the right package for you:

sudo -i -u otobo /opt/otobo/bin/otobo.CheckModules.pl --all

1. Configure OTOBO for Redis

Use the OTOBO SysConfig (Admin -> System Configuration) to configure OTOBO properly:

| Setting                       | Description                | Default value  |
| ----------------------------- | -------------------------- | -------------- |
| Cache::Redis###Server         | Redis server URL           | 127.0.0.1:6379 |
| Cache::Redis###DatabaseNumber | Number of logical database | 0              |
| Cache::Redis###RedisFast      | Use or not Redis::Fast     | 0              |
| Cache::Module                 | Activate Redis Cache Module| DB (use Redis) |

Ramdisk Caching

OTOBO caches a lot of temporary data in /opt/otobo/var/tmp. Please make sure that this uses a high performance file system and storage. If you have enough RAM, you can also try to put this directory on a ramdisk like this:

sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Session::DeleteAll
sudo -i -u otobo /opt/otobo/bin/otobo.Console.pl Maint::Cache::Delete
sudo mount -o size=16G -t tmpfs none /opt/otobo/var/tmp

Note

Add persistent mount point in /etc/fstab.

Warning

This will be a non-permanent storage that will be lost on server reboot. All your sessions (if you store them in the file system) and your cache data will be lost.

Clustering

For very high loads, it can be required to operate OTOBO on a cluster of multiple front end servers. This is a complex task with many pitfalls. We strongly advise to get in touch with our experts before trying to implement this on your own.

Documentation History

2019 - OTRS Installation Guide - OTRS AG (https://otrs.com)

2020 - OTOBO Installation Tutorial - Rother OSS GmbH (https://otobo.de)

Published by: Rother OSS GmbH, (https://otobo.de), Oberwalting 31, 94339 Leiblfing, Germany. Authors: OTRS AG (original version), Rother OSS GmbH (https://otobo.de)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found on the GNU website.

Index