.. title:: Database

---------
Database
---------

PostgreSQL Database
====================
Kasm uses Postgres as the backend database. This section covers backup and restoration of the Kasm database.

Backups
---------
The following script will backup the Postgres data and all conf files to a single file.

.. code-block:: Bash

  # this will place the back at /tmp/backup.tar
  sudo docker exec kasm_db pg_dump -U kasmapp -F t kasm > /tmp/backup.tar

.. hint::

  This can be scripted out in a cron job, for example daily, with the date in the filename of the tar file for historical backups. Change the /tmp to a directory that is using an NFS mount so the files are stored off the server.

Restore
---------
The following script will restore the database from backup. This example assumes the server is just the database role, however, this process will work just as well on a system where all roles are installed.

.. parsed-literal::

  # download the same version of kasm that is on the primary database server and unpack it
  cd /tmp
  curl -O |release_url|
  tar -xf kasm_release*.tar.gz
  # install just the database component
  sudo bash kasm_release/install.sh -b
  # copy the backup.tar into the kasm_db container
  sudo docker cp backup.tar kasm_db:/tmp/backup.tar
  # restore the database
  sudo docker exec kasm_db pg_restore -d kasm /tmp/backup.tar -c -U kasmapp

.. warning::

  If you restore to a different server you will need to change the database IP or hostname that is referenced by all API and Manager systems. You can avoid this using several methods. Use a hostname and change the IP address in your DNS record. This may take up to an hour to propogate depending on the TTL setting of the DNS record. Use a 5 minute TTL if possible. The other method is to use a virtual IP address if you have a router or firewall inbetween your database servers and the manager/api components. Finally, you can use NGINX with layer 4 load balancing. You can back one backend server as back in the upstream definition in nginx.

Change Database Password
------------------------
Administrators may wish to change the password Kasm API service uses to connect to the database. The following will change the password for the kasmapp user in the PostgreSQL database
and the password that the Kasm API is configured to use when attempting to connect to the PostgreSQL database.

.. warning:: 

  Changing the Postgres password involves restarting Kasm services and will result in an interruption in service.

Login to the server with the Database role and run the following to change the database password. Replace 'new_password' with your desired password, ensuring it does not contain any ``$``, ``'`` or ``"`` characters.

.. code-block:: Bash

  sudo docker exec -it kasm_db psql -U kasmapp -d kasm -c "ALTER ROLE kasmapp WITH PASSWORD 'new_password';"

Login to the server with the WebApp role and stop the Kasm Services.

.. code-block:: Bash

  sudo /opt/kasm/bin/stop

Edit the API app config, replacing the value on the line starting with 'password: ' with your new desired password.

.. code-block:: Bash

  sudo vi /opt/kasm/current/conf/app/api.app.config.yaml

Start Kasm Services on WebApp server.

.. code-block:: Bash

  sudo /opt/kasm/bin/start

Redis Database
==============
Kasm uses a Redis database to store chat messages in Kasm Shared sessions

Change Redis Database Password
------------------------------
Administrators may wish to change the password Kasm API service uses to connect to the Redis Database. The following will change the password in the Redis startup config and the Kasm API config.

.. warning:: 

  Changing the Redis password involves restarting Kasm services and will result in an interruption in service.


Log into the server with the Database role and edit the docker-compose file, replacing the value of REDIS_PASSWORD with your new, desired password. Ensure that the password does not contain any special characters. 

.. code-block:: Bash

  sudo vi /opt/kasm/current/docker/docker-compose.yaml

Restart the Database services.

.. code-block:: Bash

  sudo /opt/kasm/bin/stop
  sudo /opt/kasm/bin/start

Log into the server with the WebApp Role and stop the Kasm Services.

.. code-block:: Bash

  sudo /opt/kasm/bin/stop

Edit the api config and replace the value of 'redis_password' with your new password.

.. code-block:: Bash

  sudo vi /opt/kasm/current/conf/app/api.app.config.yaml

Start the Kasm Services on the WebApp Role server.

.. code-block:: Bash

  sudo /opt/kasm/bin/start