Global section¶

Parameters that sets Odyssey execution behaviour or that are common for all Odyssey rules.

Configuration Parameters Reference¶

include¶

string

Include one or more configuration files. Include files can include other files.

include "path"

daemonize¶

yes|no

Start as a daemon.

By default Odyssey does not run as a daemon. Set to 'yes' to enable.

daemonize no

sequential_routing¶

yes|no

Try to match routes exactly in config order.

By default, Odyssey tries to match all specific routes first, and then all default ones. It may be confusing because auth-denying default route can be overridden with more specific auth-permitting route below in the config. With this option set, Odyssey will match routes exactly in config order, like in HBA files.

sequential_routing no

priority¶

integer

Process priority.

Set Odyssey parent process and threads priority.

priority -10

pid_file¶

string

If pid_file is specified, Odyssey will write its process id to the specified file at startup.

pid_file "/var/run/odyssey.pid"

unix_socket_dir¶

string

UNIX socket directory.

If unix_socket_dir is specified, Odyssey will enable UNIX socket communications. Specified directory path will be used for searching socket files.

unix_socket_dir "/tmp"

unix_socket_mode¶

string

Set unix_socket_mode file mode to any created unix files.

unix_socket_mode "0755"

locks_dir¶

string

If locks_dir is specified, directory path will be used for placing lock files.

log_file¶

string

If log_file is specified, Odyssey will additionally use it to write log events.

log_file "/var/log/odyssey.log"

log_format¶

string

Log text format.

Odyssey allows to configure log text format. This could be useful to support external log parser format. Format string can contain plain text, escape symbols and format flags.

Supported flags:

%n = unixtime
%t = timestamp with date in iso 8601 format
%e = millisEcond
%p = process ID
%i = client ID
%s = server ID
%u = user name
%d = database name
%c = context
%l = level (error, warning, debug)
%m = message
%M = message tskv
%r = client port
%h = client host
%H = server host

log_format "%p %t %e %l [%i %s] (%c) %m\n"

log_to_stdout¶

yes|no

Set to 'yes' if you need to additionally display log output in stdout. Enabled by default.

log_to_stdout yes

log_syslog¶

yes|no

Log to system logger.

To enable syslog(3) usage, set log_syslog to 'yes'. Additionally set log_syslog_ident and log_syslog_facility.

log_syslog no

log_syslog_ident¶

string

Set syslog ident name.

log_syslog_ident "odyssey"

log_syslog_facility¶

string

Set syslog facility name.

log_syslog_facility "daemon"

log_debug¶

yes|no

Enable verbose logging of all events, which will generate a log of detailed information useful for development or testing.

It is also possible to enable verbose logging for specific users (see routes section).

log_debug no

log_config¶

yes|no

Write configuration to the log during start and config reload.

log_config yes

log_session¶

yes|no

Write client connect and disconnect events to the log.

log_session yes

log_query¶

yes|no

Write client queries text to the log. Disabled by default.

log_query no

log_stats¶

yes|no

Periodically display information about active routes.

log_stats yes

promhttp_server_port¶

integer

Port on which metrics server listen. http://localhost:port/ -- check is port running. http://localhost:port/metrics -- get metrics as a response.

log_general_stats_prom¶

yes|no

Write information about active routes in Prometheus format in addition to ordinary format. Requires C Prometheus client library installed. Log only info not specific to route

log_route_stats_prom¶

yes|no

Write information about active routes in Prometheus format in addition to ordinary format. Requires C Prometheus client library installed. Log all available info

stats_interval¶

integer

Set interval in seconds for internal statistics update and log report.

stats_interval 3

workers¶

integer

Set size of thread pool used for client processing.

1: By default, Odyssey runs with a single worker. This is a special mode optimized for general use. This mode also made to reduce multi-thread communication overhead.

N: Add additional worker threads, if your server experience heavy load, especially using TLS setup.

workers 1

resolvers¶

integer

Number of threads used for DNS resolving. This value can be increased, if your server experience a big number of connecting clients.

resolvers 1

readahead¶

integer

Set size of per-connection buffer used for io readahead operations. Rounded up to whole page numbers.

readahead 8192

cache_coroutine¶

integer

Set pool size of free coroutines cache. It is a good idea to set this value to a sum of max clients plus server connections. Please note, that each coroutine consumes around 16KB of memory.

Set to zero, to disable coroutine cache.

cache_coroutine 128

nodelay¶

yes|no

TCP nodelay. Set to 'yes', to enable nodelay.

nodelay yes

keepalive¶

integer

TCP keepalive time. Set to zero, to disable keepalive.

keepalive 15

keepalive_keep_interval¶

integer

The number of seconds between TCP keep-alive probes. 5 by default.

keepalive_keep_interval 10

keepalive_probes¶

integer

TCP keep-alive probes to send before giving up and killing the connection if no response is obtained. 3 by default.

keepalive_probes 5

keepalive_usr_timeout¶

integer

When the value is greater than 0, it specifies the maximum amount of time in milliseconds that transmitted data may remain unacknowledged before TCP will forcibly close the corresponding connection.

When the value is negative, the default system user timeout will be used.

When no value or 0 is provided 1000 * (keepalive + keepalive_keep_interval * keepalive_probes) - 500 is used.

keepalive_usr_timeout 7

backend_connect_timeout_ms¶

integer

Timeout for connection to backend (postgres). Default value is 30000 (30 secs)

backend_connect_timeout_ms 20000

coroutine_stack_size¶

integer

Coroutine stack size.

Set coroutine stack size in pages. In some rare cases it might be necessary to make stack size bigger (like that using the Odyssey with LDAP auth required coroutine_stack_size 16). Actual stack will be allocated as (coroutine_stack_size + 1_guard_page) * page_size. Guard page is used to track stack overflows. Stack by default is set to 16KB.

coroutine_stack_size 4

client_max¶

integer

Global limit of client connections.

Comment 'client_max' to disable the limit. On client limit reach, Odyssey will reply with 'too many connections'.

client_max 100

client_max_routing¶

integer

Global limit of client connections concurrently being routed. Client connection is being routed after it is accepted and until it's startup message is read and connection is assigned route to the database. Most of the routing time is occupied with TLS handshake. Unset or zero 'client_max_routing' will set it's value equal to 64 * workers

client_max_routing 32

server_login_retry¶

integer

If server responds with "Too many clients" client will wait for server_login_retry milliseconds. 1 by default.

hba_file¶

string

Path to file containing host based authentication rules. Omit this option to disable HBA.

hba_file "path"

HBA file format follows the format of the PostgreSQL pg_hba.conf file. * Supported record types: local, host, hostssl, hostnossl. * Database field: all, sameuser, multiple names. * User field: all, multiple names. * Address field: IPv4 or IPv6 range. * Auth-method field: deny or reject (equivalent keywords), which leads to immediate disconnection, allow or trust (also equivalent keywords), which means applying auth method specified in matching route.

graceful_die_on_errors¶

yes|no

If specified, after receiving the signal SIGUSR2, Odyssey will shutdown the socket for receptions and continue working only with old connections

graceful_shutdown_timeout_ms¶

integer

Timeout for graceful shutdown in milliseconds Default:30000 (30 seconds), use 0 to disable

graceful_shutdown_timeout_ms 30000

availability_zone¶

string

Specify Odyssey instance availability zone for host selection.

availability_zone "us-east-1a"

enable_online_restart¶

yes|no

Online restart feature. When setting to yes, restart odyssey simply with running new version (old one will automatically perform graceful shutdown)

enable_online_restart no

online_restart_drop_options¶

This section can be used to configure connections dropping during online restart

drop_enabled¶

yes|no

When set to yes - connections to old odyssey instance will be dropped by rate of one per sec for each worker. When set to no - odyssey will work with connections on old instance until it disconnect. Default: yes

online_restart_drop_options {
    drop_enabled no
}

bindwith_reuseport¶

yes/no

Enable SO_REUSEPORT for listening sockets. Allow to run several Odyssey instances on one listen address. Useful for online restart feature.

max_sigterms_to_die¶

integer

Maximum SIGTERM count before hard exit(1)

max_sigterms_to_die 10

enable_host_watcher¶

yes/no

Start thread to watch host CPU and memory consumption. Makes show host_utilization works.

enable_host_watcher yes