Oxla Configuration File

Overview

Oxla configuration is managed through a configuration file, which defines various aspects of Oxla’s usage and is helpful for both development and deployment. When Oxla is being run as a docker container, the config file is generated automatically inside a container in /oxla/startup_config, based on environment variables and default values.

Mounting Config Directory

The /oxla/startup_config config directory can be mounted using -v /path/to/mount:/oxla/startup_config command to access the config file directly:

docker run --rm -it -p 5432:5432 -v /path/to/mount:/oxla/startup_config public.ecr.aws/oxla/release:latest

Configuring File Handling

Automatic Generation from Defaults

If no configuration is found in the specified directory, Oxla generates one using default values (the default name would be config.yml). During generation, Oxla takes into account environment variables. When the environment variable is passed, this value is written to the generated config instead of the default one.

Modifying Default Config Path

To modify the default config path inside Oxla’s docker container, you need to pass the OXLA_CONFIG_FILE=path/to/config.yml environment variable to the docker run command. Passing an empty path would result in using the default values.

Partial Variable Specification

When creating a custom configuration file, it is not required to pass all the possible variables. If a variable is not passed, it assumes the default value. An empty configuration file can be used, however Oxla will use defaults for everything.

Regenerating the Config File

The best way to regenerate the config file is to remove or rename the existing config file, so there’s no /oxla/startup_config/config.yml. Oxla will then automatically generate a new configuration file based on the default values.

Variables Configuration

The YAML file below is the default configuration file in Oxla:

network:
  port: 5769
  slots_port: 5770
  postgresql_port: 5432
  prometheus_port: 8080
  nodes:
    - "localhost"
  cluster_name: "cluster_1"
  host_name: "oxla_node_1"

leader_election:
  leader_name: "oxla_node_1"

metrics:
  no_prometheus_exposer: false

insertion:
  buffer_size_limit: 42M
  buffer_timeout: 100 ms

logging:
  level: "INFO"

storage:
  oxla_home: "/oxla/data"
  s3:
    enable_discovery: true
    use_dual_stack: true
    endpoint: ""

access_control:
  mode: DEFAULT

ssl:
  mode: off

Below is a list of key configuration variables:

Variable	Description	Values / Units
network.port	Port on which Oxla listens for connections from nodes in the cluster	-
network.postgresql_port	Port on which the node listens for TCP connections to the PostgreSQL client	-
network.prometheus_port	Port on which the process listens for HTTP connections for Prometheus metrics	-
network.nodes	List of IP addresses or DNS addresses to which Oxla connects	-
network.cluster_name	Common cluster name used for node connection validation	-
network.host_name	Unique name of a single node in the cluster	-
metrics.no_prometheus_exposer	Option for disabling the Prometheus exposer	-
insertion.buffer_size_limit	Threshold for data or time before dumping data from memory to the filesystem	G, M, K
insertion.buffer_timeout	Timeout for dumping data from memory to the filesystem	h, min, s, ms
logging.info	Logging level	VERBOSE, DEBUG, INFO, WARNING, ERROR, FATAL, NONE
storage.oxla_home	Directory for data (either on local disk, path inside the container or on S3)	-
storage.s3.enable_discovery	By default, regional or overridden endpoints are used. To enable endpoint discovery, set the variable to true	false, true
storage.s3.use_dual_stack	Enable or disable dual-stack IPv4 and IPv6 endpoints (not all AWS services support IPv6 in all Regions)	-
storage.s3.endpoint	Endpoint for the S3 protocol. If not provided, the default AWS endpoint is used	-
access_control.mode	Access control mode that Oxla sticks to during connection and execution of queries by connected users	DEFAULT: keeps the default behavior of Oxla OFF: turns off the access control. Everyone can login and execute any query ON: turns on the access control and all the validations are executed
ssl.mode	SSL connection mode for securing database communication	Optional: SSL is used if available, otherwise a non-SSL connection is attempted Require: SSL must be used, non-SSL connections are rejected Off: No SSL is used, all connections are unencrypted

Environment Variables

Values in the configuration file take precedence over environment variables and default values. Naming conventions for environment variables are derived from the configuration variable names, with __ (double underscore) replacing YAML hierarchy levels. For example:

network:
  port: 5769

The port is expressed as the NETWORK__PORT environment variable

Environment variables can be passed using the -e parameter in the docker run command, as presented below:

docker run --rm -it -p 5432:5432 -e INSERTION__BUFFER_TIMEOUT=1ms public.ecr.aws/oxla/release:latest