en	Backup and Restore

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

en	Backup

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

en	The output of the script:

en	Restore

en	To restore the database make sure that the database ``otobo`` exists and contains no tables.

en	Considerations for running OTOBO under Docker

en	The same scripts can be used with OTOBO running under Docker. However some Docker specific limitation must be considered. Please read to the chapter :doc:`backup-restore-docker` for information about that case.

en	Backup and Restore using Docker

en	Please read to the chapter :doc:`backup-restore` for basic information about the backup and restore scripts.

en	The standard scripts ``backup.pl`` and ``restore.pl`` can also be used with OTOBO running under Docker. However some Docker specific limitations have to be considered.

en	First, we need to make sure that the backup files are not created in the file system that is internal to a Docker container. Because in that case the created files would be lost when the container is stopped. This means that the backup directory must located within in a volume. For this manual we only consider the most simple case, where the backup directory is a local directory on the Docker host. The location of the backup dir in the container can be arbitrarily chosen. In this example we choose the local dir ``otobo_backup`` as the location on the host and ``/otobo_backup`` as the location in the container.

en	Secondly, commands in the Docker container usually run as the user `otobo` with the user id 1000 and the group id 1000. It must be made sure, that this user can write in the backup directory.

en	First we need to create the volume.

en	For creating the backup we need a running database and the volumes ``otobo_opt_otobo`` and ``otobo_backup``. This means that the webserver and the OTOBO daemon may, but don't have to, be stopped.

en	To drop an existing otobo database and create a new one you can use the following commands. First, you have to connect to the MySQL CLI of the `db` container.

en	As soon as you are connected to the MySQL server, you can drop and recreate the `otobo` database.

en	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``.

en	Adapt customer interface with corporate identity

en	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.

en	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``.

en	Change colors in Customer Area

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

en	CustomerColorDefinitions

en	To change the colours 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 colour definitions.

en	Change Logos and Pictures

en	In the first step please copy your Logos and Pictures to the OTOBO Server. Please use an SCP client (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/.

en	In the next step copy the Logo into the OTOBO Home directory:

en	Now change inside the OTOBO Agent Interface to ``Admin -> System Configuration`` and change the following settings:

en	Change Customer Login Pictures and Text

en	1 and 2 - System Configuration Option **CustomerLogin::Settings**

en	**Remove Opacity and Watermark**

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

en	To remove the opacity, please adjust the option **#oooLoginBG > .oooBG** in the file

en	``var/httpd/htdocs/skins/Customer/default/css/Core.Login.css``

en	To remove the watermark, please remove the following line inside the file:

en	``Kernel/Output/HTML/Templates/Standard/CustomerLogin.tt``

en	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/10.1/en/content/how-to-publish-otobo-extensions.html

en	Change Customer Dashboard tiles and options

en	To change the colours on the Customer Dashboard, please go to ``Admin -> System Configuration`` and search for **CustomerDashboard**.

en	In the search result you will find all the options you need with colour definitions.

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

en	2 - To change the toplevel text please use the System Configuration Option **CustomerDashboard::Configuration::Text**

en	Please disable the config options from not needed tiles.

en	Documentation History

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

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

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

en	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 <https://www.gnu.org/licenses/fdl-1.3.txt>`__.

en	OTOBO Installation Tutorial

en	This work is copyrighted by OTRS AG (https://otrs.com), Zimmersmühlenweg 11, 61440 Oberursel, Germany.

en	Copyright © for modifications and amendments 2019-2022 ROTHER OSS GmbH (https://otobo.de), Oberwalting 31, 94339 Leiblfing, Germany

en	Terms and Conditions OTRS: 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.

en	Terms and Conditions Rother OSS: 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 is included in the section entitled "COPYING".

en	Published by: Rother OSS GmbH, (https://otobo.de), Oberwalting 31, 94339 Leiblfing, Germany.

en	Authors: OTRS AG (original version), Rother OSS GmbH (https://otobo.de).

en	Contents

en	OTOBO Installation

en	This chapter describes the installation and basic configuration of the central OTOBO framework.

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

en	We recommend Docker and Docker Compose for the OTOBO installation. 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 has been improved. You can find the instructions for Docker-based installation at https://doc.otobo.org/manual/installation/10.1/en/content/installation-docker.html .

en	Preparation: Disable SELinux when it is installed and enabled

en	If your system uses SELinux, you should disable it, otherwise OTOBO will not work correctly.

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

en	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.

en	Here's how to disable SELinux for RHEL/CentOS/Fedora.

en	Configure ``SELINUX=disabled`` in the ``/etc/selinux/config`` file:

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

en	Step 1: Unpack and Install OTOBO

en	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``:

en	Step 2: Install Additional Programs and Perl Modules

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

en	On Debian systems you may need to manually install some perl packages:

en	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. You may need to install a ``perl-core`` package on some systems like RHEL that do not install the Perl core packages by default.

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

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

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

en	Step 3: Create the OTOBO User

en	Create a dedicated user for OTOBO within its own group:

en	Add the user to web server group (if the web server is not running as otobo user):

en	Step 4: Activate the Default Configuration File

en	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.

en	Step 5: Configure the Apache Web Server

en	First of all, you should install the Apache2 web server and mod_perl; you'd typically do this from your system's package manager. Below you'll find the commands needed to set up Apache on the most popular Linux distributions.

en	A critical setting of the Apache web server is the choice of the multi-processing module. For running OTOBO, the recommended choice is the module **mpm_prefork**. Like other Apache modules the multi-processing module can be managed with the tools a2dismod and a2enmod.

en	All is fine whem mpm_prefork already is enabled.

en	Disable mpm_event when it is currently active.

en	Disable mpm_worker in case that MPM is enabled.

en	Finally activate mpm_prefork.

en	OTOBO requires a few more Apache modules to be active for optimal operation. Again, on most platforms you can make sure they are active via the tool a2enmod.

en	On some platforms not all Apache modules exist and an error is displayed when installing. Do not worry and finish the installation, in most cases the module will not be needed.

en	Most Apache installations have a ``conf.d`` directory included. On Linux systems you can usually find this directory under ``/etc/apache`` or ``/etc/apache2``.

en	Configure Apache without SSL support

en	Copy the template file ``/opt/otobo/scripts/apache2-httpd.include.conf`` to the apache ``sites-available`` directory. In most cases no further editing of the template is required. Then enable the new configuration.

en	Configure Apache **with** SSL support

en	Copy the template files ``/opt/otobo/scripts/apache2-httpd-vhost-80.include.conf`` and ``/opt/otobo/scripts/apache2-httpd-vhost-443.include.conf`` to the apache ``sites-available`` directory.

en	Please edit the files and add the required information like SSL certificate storage path. After that, enable the OTOBO Apache configuration:

en	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:

en	Step 6: Set File Permissions

en	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.

en	Step 7: Setup the Database

en	First of all, you should install the database package. It is recommended to use the MySQL or MariaDB package, which will be delivered with your Linux system, but it is possible to use PostgreSQL or Oracle as well.

en	You'd typically do this from your systems package manager. Below you'll find the commands needed to set up MySQL on the most popular Linux distributions.

en	After installing the MySQL server you need configure it.

en	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:

en	For MariaDB > 10.1 use instead the following command:

en	If this command not work, please try the following commands:

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

en	The following configuration settings are minimum requirements for MySQL setups. Please add the following lines to the MySQL Server configuration file ``/etc/my.cnf``, ``/etc/mysql/my.cnf`` or ``/etc/mysql/mysql.conf.d/mysqld.cnf`` under the ``[mysqld]`` section:

en	For MySQL prior to MySQL 8.0 the query cache size should also be set:

en	Also add the following lines to the MySQL Server configuration file ``/etc/my.cnf``, ``/etc/mysql/my.cnf`` or ``/etc/mysql/mysql.conf.d/mysqldump.cnf`` under the ``[mysqldump]`` section:

en	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:

en	After installing execute the script:

en	Step 8: Setup Elasticsearch

en	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.

en	Elasticsearch installation example based on Ubuntu 18.04 LTS

en	JDK Installation

en	Elasticsearch Installation

en	Elasticsearch Installation on another Linux distribution

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

en	Elasticsearch Module Installation

en	Additionally, OTOBO requires plugins to be installed into Elasticsearch:

en	Elasticsearch Configuration

en	Elasticsearch has a multitude of configuration options and possibilities.

en	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 4 GB, set:

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

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

en	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:

en	Step 9: Basic System Configuration

en	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.

en	Step 10: First Login

en	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).

en	Step 11: Start the OTOBO Daemon

en	OTOBO daemon is responsible for handling any asynchronous and recurring tasks in OTOBO. What has been in cron file definitions previously is now handled by the OTOBO daemon, which is required to operate OTOBO. The daemon also handles all GenericAgent jobs and must be started from the OTOBO user.

en	Step 12: Cron jobs for the OTOBO user

en	There are two default OTOBO cron files in ``/opt/otobo/var/cron/\*.dist``, and their purpose is to make sure that the OTOBO Daemon is running. They need to be be activated by copying them without the ".dist" filename extension.

en	With this step, the basic system setup is finished.

en	Step 13: Setup Bash Auto-Completion (optional)

en	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.

en	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.

en	After restarting your shell, you can just type this command followed by TAB, and it will list all available commands:

en	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.

en	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.

en	Step 14: Further Information

en	We advise you to read the OTOBO :doc:`performance-tuning` chapter.

en	Installing using Docker and Docker Compose

en	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.

en	Service *db*: MariaDB is set up as the default database.

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

en	Service *redis*: Redis is enabled for fast caching.

en	Service *web*: Gazelle is used as fast Perl webserver.

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

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

en	Requirements

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

en	Docker 19.03.13

en	Docker Compose 1.25.0

en	Git 2.17.1

en	To get the required minimal versions on Ubuntu 18.04 follow the instructions in https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04 and https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04.

en	git, Docker, and Docker Compose can be installed with the standard system tools. Here is an example for installation on Ubuntu 20.04:

en	Please check the Git and the Docker documentation for instructions on further setup.

en	Installation

en	The following instructions assume that all requirements are met, that you have a working Docker environment. We assume here 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.

en	1. Clone the otobo-docker repo

en	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 10.1.10* is the current version then please use the tag *rel-10_1_10*.

en	The location of the cloned repository does not matter. For these instructions we chose */opt/otobo-docker* as the working dir.

en	2. Create an initial *.env* file

en	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 there are several example files that should 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 specialised use cases.

en	.docker_compose_env_http

en	The OTOBO web app provides HTTP.

en	.docker_compose_env_https

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

en	.docker_compose_env_https_custom_nginx

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

en	.docker_compose_env_https_kerberos

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

en	.docker_compose_env_http_selenium and .docker_compose_env_https_selenium

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

en	Use ``ls -a`` for listing the hidden sample files.

en	Per default OTOBO is served on the standard ports. Port 443 for HTTPS and port 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.

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

en	3. Configure the password for the database admin user

en	Change the following setting inside your *.env* file:

en	``OTOBO_DB_ROOT_PASSWORD=<your_secret_password>``

en	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**.

en	4. Set up a volume with SSL configuration for the nginx webproxy (optional)

en	This step can be skipped when OTOBO should be available only via HTTP.

en	nginx needs for SSL encryption a certificate and a private key.

en	For testing and development a self-signed certificate can be used. However for productive use you should work with regular registered certificates.

en	See e.g. https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04 on how to create self-signed certificates.

en	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.

en	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:

en	The names of the copied files need to be set in our newly created *.env* file. E.g.

en	``OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/ssl-cert.crt`` and ``OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/ssl-key.key``

en	Please adapt only the name of the files as the path */etc/nginx/ssl/* is hard coded in the Docker image.

en	5. Start the Docker containers with Docker Compose

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

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

en	6. Install and start OTOBO

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

en	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.

en	**Have fun with OTOBO!**

en	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``.

en	Additional technical information

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

en	List of Docker containers

en	Container otobo_web_1

en	OTOBO webserver on internal port 5000.

en	Container otobo_daemon_1

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

en	Container otobo_db_1

en	Run the database MariaDB on internal port 3306.

en	Container otobo_elastic_1

en	Elasticsearch on the internal ports 9200 and 9300.

en	Container otobo_redis_1

en	Run Redis as caching service.

en	Optional container otobo_nginx_1

en	Run nginx as reverse proxy for providing HTTPS support.

en	Overview over the Docker volumes

en	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.

en	otobo_opt_otobo

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

en	otobo_mariadb_data

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

en	otobo_elasticsearch_data

en	contains */usr/share/elasticsearch/datal* in the container **elastic**.

en	otobo_redis_data

en	contains data for the container `redis`.

en	otobo_nginx_ssl

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

en	Docker environment variables

en	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.

en	**MariaDB settings**

en	OTOBO_DB_ROOT_PASSWORD

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

en	**Elasticsearch settings**

en	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.

en	OTOBO_Elasticsearch_ES_JAVA_OPTS

en	Example setting: *OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m* Please adjust this value for production env to a value up to 4g.

en	**Webserver settings**

en	OTOBO_WEB_HTTP_PORT

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

en	**Nginx webproxy settings**

en	These setting are used when HTTPS is enabled.

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

en	OTOBO_WEB_HTTPS_PORT

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

en	OTOBO_NGINX_SSL_CERTIFICATE

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

en	OTOBO_NGINX_SSL_CERTIFICATE_KEY

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

en	**Nginx webproxy settings for Kerberos**

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

en	OTOBO_NGINX_KERBEROS_KEYTAB

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

en	OTOBO_NGINX_KERBEROS_CONFIG

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

en	OTOBO_NGINX_KERBEROS_SERVICE_NAME

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

en	OTOBO_NGINX_KERBEROS_REALM

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

en	OTOBO_NGINX_KERBEROS_KDC

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

en	OTOBO_NGINX_KERBEROS_ADMIN_SERVER

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

en	OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN

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

en	NGINX_ENVSUBST_TEMPLATE_DIR

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

en	**Docker Compose settings**

en	These settings are used by Docker Compose directly.

en	COMPOSE_PROJECT_NAME

en	The project name is used as the prefix for the volumes and containers. Per 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.

en	COMPOSE_PATH_SEPARATOR

en	Separator for the value of COMPOSE_FILE

en	COMPOSE_FILE

en	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*.

en	OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, ...

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

en	Advanced topics

en	Custom configuration of the nginx webproxy

en	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.

en	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:

en	For configuring SSL.

en	OTOBO_NGINX_WEB_HOST

en	The internally used HTTP host.

en	OTOBO_NGINX_WEB_PORT

en	The internally used HTTP port.

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

en	When the standard macros are not sufficient, then the customisation 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.

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

en	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 config. 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:

en	The changed Docker Compose configuration can be inspected with:

en	Finally, the containers can be started again:

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

en	Single Sign On Using the Kerberos Support in Nginx

en	**Short Description**

en	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.

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

en	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 directove in *docker-compose/otobo-override-https-kerberos.yml*.

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

en	**Kerberos SSO Installation Tutorial**

en	:doc:`sso-kerberos`

en	Choosing non-standard ports

en	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.

en	Skip startup of specific services

en	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:

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

en	Prepare offline installation

en	Please download `the latest version of otobo-docker <https://doc.otobo.org/manual/installation/10.1/en/content/installation-docker.html#clone-the-otobo-docker-repo>`__ on a system that has internet access and where docker is installed. Then navigate to the following folder *otobo-docker/docker-compose*.

en	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*.

en	After that, the images (.docker) are located in the docker-compose folder and can be uploaded to the target system via e.g `SCP <https://en.wikipedia.org/wiki/Secure_copy_protocol>`__.

en	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.

en	In the following example I import the mariadb image:

en	Customizing OTOBO Docker Compose

en	Instead of editing the files under *docker-compose/* and risking to overwrite your own options with the `next update <https://doc.otobo.org/manual/installation/10.1/en/content/updating-docker.html#updating-the-docker-compose-files>`_ of the otobo-docker folder, it is advisable to create an extra YAML file where the specific services are overwritten with additional options.

en	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 thats look like:

en	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:

en	Now we can use *docker-compose* to recreate our container

en	With this procedure you can customize any service or volumes.

en	Customizing the OTOBO Docker image

en	Many customizations 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`.

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

en	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 writeup of that process is available at https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.

en	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:

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

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

en	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:

en	Finally we can doublecheck:

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

en	Building local images

en	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.

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

en	*otobo.web.dockerfile*

en	*otobo.nginx.dockerfile*

en	*otobo.elasticsearch.dockerfile*

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

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

en	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 *.env*.

en	Automatic Installation

en	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.

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

en	List of useful commands

en	**Docker**

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

en	``docker version`` show version

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

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

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

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

en	``docker ps`` show running images

en	``docker images`` show available images

en	``docker volume ls`` list volumes

en	``docker volume inspect otobo_opt_otobo`` inspect a volume

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

en	``docker volume rm tmp_volume`` remove a volume

en	``docker inspect <container>`` inspect a container

en	``docker save --output otobo.tar otobo:latest-10_1 && tar -tvf otobo.tar`` list files in an image

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

en	**Docker Compose**

en	``docker-compose config`` check and show the configuration

en	``docker-compose ps`` show the running containers

en	``docker-compose exec nginx nginx -s reload`` reload nginx

en	Resources

en	Finally, here is a highly subjective collection of links.

en	**General info and tutorials**

en	`Perl Maven: Getting Started with Perl on Docker <https://perlmaven.com/getting-started-with-perl-on-docker>`_

en	`Dockerfile best practices <https://www.docker.com/blog/intro-guide-to-dockerfile-best-practices/>`_

en	`Environment <https://vsupalov.com/docker-arg-env-variable-guide/>`_

en	**Tips and hints**

en	`Newer version of Docker Compose on Ubuntu 18.04 LTS <https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04>`_

en	`Newer version of Docker on Ubuntu 18.04 LTS <https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04>`_

en	`Clean up unused images <https://forums.docker.com/t/command-to-remove-all-unused-images>`_

en	`Docker Host IP <https://nickjanetakis.com/blog/docker-tip-65-get-your-docker-hosts-ip-address-from-in-a-container>`_

en	`Self signed certificate <https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04>`_

en	**Troubleshooting**

en	`Docker cache invalidation <https://stackoverflow.com/questions/34814669/when-does-docker-image-cache-invalidation-occur>`_

en	`Using tcpdump <https://rmoff.net/2019/11/29/using-tcpdump-with-docker/>`_

en	`Inspect failed builds <https://pythonspeed.com/articles/debugging-docker-build/>`_

en	Installing Perl Modules from CPAN

en	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/.

en	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.

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

en	Per default ``cpanm`` installs modules into a systemwide location. In this case modules must be installed as the root user. For example, the command

en	results in:

en	Docker-based installations

en	Special care must be taken when OTOBO runs under Docker. In this case an installation into a systemwide 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.

en	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.

en	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**.

en	Introduction

en	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.

en	About This Manual

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

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

en	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.

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

en	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.

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

en	Welcome and thank you for choosing OTOBO!

en	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.

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

en	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!

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

en	Overview over the Supported Migration Szenarios

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

en	The general migration strategy.

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

en	Change server:

en	Migrate and simultaneously move to a new application server.

en	Separate application and web servers:

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

en	Different databases:

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

en	Different operating system:

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

en	Docker:

en	Migrate to a Docker-based installation of OTOBO 10.

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

en	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.

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

en	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.

en	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.

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

en	Migration Requirements

en	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.

en	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.de or ask your question in the OTOBO Community forum at https://forum.otobo.org/.

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

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

en	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.

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

en	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.

en	Step 1: Install the new OTOBO System

en	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 :doc:`installation`. For Docker-based installations we refer to the chapter :doc:`installation-docker`.

en	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.

en	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.

en	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:

en	OTRSHideShowDynamicField

en	RotherOSSHideShowDynamicField

en	TicketForms

en	RotherOSS-LongEscalationPerformanceBoost

en	Znuny4OTRS-AdvancedDynamicFields

en	Znuny4OTRS-AutoSelect

en	Znuny4OTRS-EscalationSuspend

en	OTRSEscalationSuspend

en	OTRSDynamicFieldDatabase

en	OTRSDynamicFieldWebService

en	OTRSBruteForceAttackProtection

en	Znuny4OTRS-ExternalURLJump

en	Znuny4OTRS-QuickClose

en	Znuny4OTRS-AutoCheckbox

en	OTRSSystemConfigurationHistory

en	Znuny4OTRS-PasswordPolicy

en	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.

en	ImportExport

en	Step 2: Deactivate ``SecureMode`` on OTOBO

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

en	Do not forget to actually deploy the changed setting.

en	Step 3: Stop the OTOBO Daemon

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

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

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

en	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.

en	We advise you to read the OTOBO :doc:`backup-restore` chapter.

en	Optional Step: Mount /opt/otrs for Convenient Access

en	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.

en	Optional Step: Install ``sshpass`` and ``rsync`` when */opt/otrs* Should be Copied via ssh

en	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.

en	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:

en	The same thing must be done for *rsync* when it isn't available yet.

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

en	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.

en	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:

en	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.

en	Stop All Relevant Services and the OTRS Daemon

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

en	Clear the Caches and the Operational Data

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

en	Optional Step for Docker: make required data available inside container

en	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.

en	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.

en	Copy */opt/otrs* into the volume *otobo_opt_otobo*

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

en	There are at least two viable possibilities:

en	copy */opt/otrs* into the existing volume *otobo_opt_otobo*

en	mount */opt/otrs* as an additional volume

en	Let's concentrate on option **a.** here.

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

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

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

en	Step 5: Perform the Migration!

en	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.

en	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.

en	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.

en	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.

en	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``.

en	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'@'%'``.

en	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 pathes or LDAP settings. In the best case you might find that some custom setting are longer needed.

en	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:

en	In the Docker case:

en	Step 6: After Successful Migration!

en	Uninstall ``sshpass`` if you do not need it anymore.

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

en	Have fun with OTOBO!

en	Known Migration Problems

en	1. Login after migration not possible

en	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.

en	2. Final page of the migration has a strange layout due to missing CSS files

en	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.

en	3. Migration stops due to MySQL errors

en	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.

en	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.

en	4. Errors in Step 5 when migrating to PostgreSQL

en	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``.

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

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

en	5. Problems with the Deployment the Merged System Configuration

en	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.

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

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

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

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

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

en	Step 7: Manual Migration Tasks and Changes

en	1. Password policy rules

en	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``).

en	Password Policy Rule

en	Default

en	``PasswordMinSize``

en	8

en	``PasswordMin2Lower2UpperCharacters``

en	Yes

en	``PasswordNeedDigit``

en	``PasswordHistory``

en	10

en	``PasswordTTL``

en	30 days

en	``PasswordWarnBeforeExpiry``

en	5 days

en	``PasswordChangeAfterFirstLogin``

en	2. Under Docker: Manually migrate cron jobs

en	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).

en	Special topics

en	Migration from Oracle to Oracle

en	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.

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

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

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

en	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 .

en	Clear out otobo

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

en	Export the complete OTRS schema.

en	Import the OTRS schema, renaming the schema to 'otobo'.

en	Adapt the cloned schema otobo

en	Start the web server for otobo again

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

en	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.

en	Optional Step: Streamlined migration of the database (only for experts and spezial scenarios)

en	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.

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

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

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

en	convert the character set to *utf8mb4*

en	rename a couple of tables

en	shorten some table columns

en	After the transfomation 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.

en	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*.

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

en	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.

en	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``.

en	Native installation:

en	Docker-based installation:

en	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.

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

en	or when running under Docker

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

en	Performance Tuning

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

en	Ticket Index Module

en	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:

en	``Kernel::System::Ticket::IndexAccelerator::RuntimeDB``

en	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.

en	``Kernel::System::Ticket::IndexAccelerator::StaticDB``

en	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:

en	Ticket Search Index

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

en	To create an initial index, use this command:

en	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.

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

en	``Ticket::SearchIndex::IndexArchivedTickets``

en	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.

en	``Ticket::SearchIndex::Attribute``

en	Basic full-text index settings.

en	``Ticket::SearchIndex::Attribute`` Setting

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

en	``WordCountMax``

en	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.

en	``WordLengthMin`` and ``WordLengthMax``

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

en	``Ticket::SearchIndex::Filters``

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

en	``Ticket::SearchIndex::Filters`` Setting

en	There are three default filters defined:

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

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

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

en	``Ticket::SearchIndex::StopWords``

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

en	``Ticket::SearchIndex::StopWords###en`` Setting

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

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

en	``Ticket::SearchIndex::StopWords###Custom``

en	Document Search

en	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 <https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html>`__.

en	Heap Size

en	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``.

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

en	``Xms1g``: minimum heap size.

en	``Xmx1g``: maximum heap size.

en	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.

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

en	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.

en	For more information and good rules of thumb about the heap size, please follow `the official documentation <https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html>`__.

en	Disk Allocation

en	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.

en	``cluster.routing.allocation.disk.watermark.low``

en	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.

en	``cluster.routing.allocation.disk.watermark.high``

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

en	``cluster.routing.allocation.disk.watermark.flood_stage``

en	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``.

en	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.

en	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.

en	For more information about disk watermarks and disk-based shard allocation, please follow `the official documentation <https://www.elastic.co/guide/en/elasticsearch/reference/current/disk-allocator.html>`__.

en	Article Storage

en	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``.

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

en	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.

en	Don't use this with large setups.

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

en	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.

en	Recommended for large setups.

en	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:

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

en	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.

en	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.

en	Archiving Tickets

en	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.

en	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.

en	To use the archive feature:

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

en	Define a generic agent job:

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

en	*Job Settings*: provide a name for the archiving job.

en	*Automatic Execution*: select proper options to schedule this job.

en	*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.

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

en	Save the job at the end of the page.

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

en	Click on the *Run Job* button.

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

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

en	To search for archived tickets:

en	Open the ticket search screen.

en	Set *Archive search* to *Unarchived tickets* or *All tickets*.

en	Perform the search.

en	Caching

en	A fast cache module is a great help in terms of performance. We recommend to use a Redis Cache server or to create a ramdisk.

en	Install a Redis Cache Server

en	Install Redis Server

en	First of all you need to install the newest Redis Server. The easiest way is to `setup Redis <https://redis.io/topics/quickstart>`__ on the same host as OTOBO and binding it to its default port.

en	Install Perl module Redis or Redis::Fast

en	You can choose which Redis module to use: `Redis` or `Redis::Fast` (which is compatible with `Redis` but **~2x faster**). Please use ``otobo.CheckModules.pl --list`` to choose the right package for you:

en	Configure OTOBO for Redis

en	Please use the OTOBO `SysConfig` (Admin -> System Configuration) to configure OTOBO properly:

en	RamDisk Caching

en	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:

en	Add persistent mount point in ``/etc/fstab``.

en	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.

en	Clustering

en	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.

en	Hardware and Software Requirements

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

en	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.

en	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.

en	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-get). There is a console command for checking the module dependencies:

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

en	The listed commands should then be executed with root privileges.

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

en	Hardware Requirements

en	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.

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

en	small CPU

en	4 GB RAM

en	10 GB storage

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

en	3 GHz Xeon or comparable CPU

en	8 GB RAM (16 GB recommend)

en	40 GB storage

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

en	Software requirements

en	Perl

en	Perl 5.24.0 or higher

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

en	Web Server

en	Apache HTTP Server Version 2.4

en	Databases

en	MySQL 5.6 or higher

en	MariaDB

en	PostgreSQL 9.2 or higher

en	Oracle 10g or higher

en	Optional

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

en	Redis (fast caching)

en	nginx or any other web server that can be used as a reverse proxy (SSL support and load distribution)

en	Web browsers

en	Apple Safari

en	Google Chrome

en	Microsoft Internet Explorer 11

en	Microsoft Edge

en	Mozilla Firefox

en	Any other modern web browser with JavaScript support

en	Kerberos Single Sign On in OTOBO Docker installation

en	Please read to the chapter :doc:`installation-docker` for basic information about installing and configure OTOBO. This tutorial assumes that OTOBO has been installed and configured using Docker.

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

en	Generate Active Directory User

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

en	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.

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

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

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

en	Generate Active Directory Keytab file

en	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:

en	`-princ = HTTP/otrs32-centos6.otrs.local@OTRS.LOCAL -> Picture Number 1+@+Picture Number 2`

en	`-mapuser = OTRS\otrs32-centos6 (Username prä Win 2000) -> -> Picture Number 3+\+Picture Number`

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

en	`-out = c:/krb5.keytab`

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

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

en	Create a new volume for your custom nginx configuration

en	Create new OTOBO .env file

en	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.

en	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:

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

en	# 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

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

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

en	# Active Directory Domain Controller / Kerberos kdc OTOBO_NGINX_KERBEROS_KDC=

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

en	# Kerberos Default Domain OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN=otrs.local

en	Start OTOBO

en	After the initial Kerberos configuration we start OTOBO again:

en	Tell OTOBO to use the Kerberos-Authentication

en	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.

en	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:

en	Configure Browser to understand Kerberos SSO

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

en	**Chrome, Edge, Internet Explorer, etc.**

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

en	**Firefox**

en	Enter "about:config" in the firefox address line

en	and change the following settings:

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

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

en	Debugging and Problems

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

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

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

en	Kerberos debugging

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

en	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 seperate 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).

en	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')

en	Updating

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

en	On Debian systems you may need to manually install some perl packages before upgrading from 10.0 to 10.1

en	Step 1: Stop All Relevant Services and the OTOBO Daemon

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

en	Stop OTOBO cron jobs and the daemon (in this order):

en	Step 2: Backup Files and Database

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

en	Example for a standard installation with Ubuntu and MySQL

en	Please check if all files are valid. Now we have a backup with all required data.

en	Don't proceed without a complete backup of your system. You can use also the :doc:`backup-restore` script for this.

en	Step 3: Install the New Release

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

en	Restore Old Configuration Files

en	We need only copy the file ``Kernel/Config.pm`` in OTOBO 10.

en	Restore Article Data

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

en	Restore Already Installed Default Statistics

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

en	Set File Permissions

en	Check Apache configuration files

en	Newer versions of OTOBO may need you to adjust the apache configuration. From version 10.1 and onwards we moved from CGI to PSGI. Take a look at ``scripts/apache2-httpd-vhost-443.include.conf`` to see what settings needs to be adjusted/added.

en	Step 4: Check for new needed perl modules

en	OTOBO needs new cpan packages for some version jumps. Please check if new packages are needed and install them if necessary.

en	On Debian systems you may need to manually install some packages:

en	Step 5: Update Installed Packages and reconfigure config

en	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).

en	Step 6: Only for minor or major release upgrades (for example to upgrade from 10.0 to 10.1)

en	Step 7: Start your Services

en	Start OTOBO cron jobs and the daemon (in this order):

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

en	Now you can log into your system.

en	Updating a Docker-based Installation of OTOBO

en	Don't update without a complete backup of your system. You can use the :doc:`backup-restore-docker` script in your existing Docker installation for that.

en	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.

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

en	The Docker Compose files have to be updated.

en	The Docker Compose config file *.env* has to be checked.

en	The new Docker image has to be fetched.

en	The volume *otobo_opt_otobo* must be updated.

en	Some maintainance tasks must be executed.

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

en	Updating the Docker Compose files

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

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

en	Checking the Docker Compose .env file

en	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. The latest images are used when these variables are not set. If you want to use a specific version, then please set these variables accordingly.

en	Fetch the new Docker images

en	Docker compose can be used for fetching the wanted images from https://hub.docker.com/r/rotheross/otobo/.

en	Update OTOBO

en	In this step the volume *otobo_opt_otobo* is updated and the following OTOBO console commands are performed:

en	Admin::Package::ReinstallAll

en	Admin::Package::UpgradeAll

en	Maint::Config::Rebuild

en	Maint::Cache::Delete

en	Running the above mentioned commands can be automated with the help of the script *scripts/update.sh*. This script runs the commands starting with the **docker-compose pull** command. Note that that calling the database upgrade scripts is not included.