ODB configuration

Run the operational database of a Zato environment on SQLite, MySQL or PostgreSQL.

The ODB (operational database) is where a Zato environment keeps its configuration - servers, services, channels, security definitions and other objects. Each server and the Dashboard connect to the same ODB.

Zato supports three engines:

Engine	Where it runs
SQLite	Inside the container - the default, with no setup
MySQL	Outside the container, on your own database server
PostgreSQL	Outside the container, on your own database server

SQLite lives inside the container, so when a container is rebuilt, the ODB is rebuilt with it - the configuration comes back from your project's enmasse YAML, and anything created only in the Dashboard and never exported to enmasse is not retained. Run the ODB on MySQL or PostgreSQL when several containers share one environment or when the configuration must be retained independently of any container.

Enable SSL/TLS on the database server

MySQL

Point MySQL at its certificate files in my.cnf. With require_secure_transport = ON, MySQL refuses unencrypted TCP connections:

[mysqld]
ssl_ca   = /etc/mysql/certs/ca.crt
ssl_cert = /etc/mysql/certs/server.crt
ssl_key  = /etc/mysql/certs/server.key
require_secure_transport = ON

Alternatively, require TLS for the ODB user only:

alter user 'zato'@'%' require ssl;

To additionally require a client certificate from the ODB user (mutual TLS):

alter user 'zato'@'%' require x509;

PostgreSQL

Point PostgreSQL at its certificate files in postgresql.conf:

ssl = on
ssl_cert_file = 'server.crt'
ssl_key_file = 'server.key'
ssl_ca_file = 'ca.crt'

To refuse all unencrypted TCP connections, use hostssl instead of host in pg_hba.conf:

# TYPE  DATABASE  USER   ADDRESS     METHOD
hostssl zato      zato   0.0.0.0/0   scram-sha-256

To additionally require a client certificate from the ODB role (mutual TLS):

hostssl zato      zato   0.0.0.0/0   scram-sha-256  clientcert=verify-ca

Reload the configuration afterwards:

psql -U postgres -c 'select pg_reload_conf()'

Enable SSL/TLS in Zato

Set the SSL variables alongside the other Zato_ODB_* ones. Zato_ODB_SSL_Cert_File and Zato_ODB_SSL_Key_File are needed only when the database requires a client certificate (mutual TLS):

export Zato_ODB_SSL=on
export Zato_ODB_SSL_CA_File=/path/to/ca.crt
export Zato_ODB_SSL_Verify=on
export Zato_ODB_SSL_Cert_File=/path/to/client.crt
export Zato_ODB_SSL_Key_File=/path/to/client.key

Docker

Zato containers select their ODB through the Zato_ODB_* environment variables:

docker run \
  -e Zato_ODB_Type=postgresql \
  -e Zato_ODB_Host=db.example.com \
  -e Zato_ODB_Port=5432 \
  -e Zato_ODB_Username=zato \
  -e Zato_ODB_Password=my.secret.password \
  -e Zato_ODB_Name=zato \
  -e Zato_ODB_SSL=on \
  -e Zato_ODB_SSL_CA_File=/opt/hot-deploy/ssl/odb-ca.crt \
  -v /path/on/host/odb-ca.crt:/opt/hot-deploy/ssl/odb-ca.crt \
  ...

The certificate paths point to locations inside the container, so mount the certificate files first, for example under /opt/hot-deploy/ssl. For all the variables, see the environment variable reference.

Page	What it covers
Backup	Backing up and restoring the databases that run outside the container
Audit log	The separate database that records API traffic
Environment variables	All the Zato_ODB_* variables, grouped with the other configuration subjects