Configuration

This section describes the available configuration options that can be used within the faunadb.yml file. Detailed information is only provided for the options required for basic administration.

Options reference

Option Description

accelerate_indexes Boolean false

A flag that can enable index build tasks using internal class indexes, rather than table scans. This is faster for small classes. More storage and write throughput is needed for internal indexes.

admin_ssl_key_file String

Path to the private key used to encrypt communication between the admin tool and the server.

admin_ssl_password String

The password used to unlock the private key. Can be overridden with the environment variable FAUNADB_ADMIN_SSL_PASSWORD.

admin_ssl_trust_file String

The path to the trust certificate used to verify incoming private keys.

auth_root_key String secret Required

The admin key that secures the cluster. Used to create databases and server keys. Must be set before cluster initialization.

auth_root_key_hash String

Set auth_root_key to the key in plain-text, or use the faunadb-admin hash-key KEY command to create a hash of KEY that can be used in auth_root_key_hash. If you supply a key but no hash, FaunaDB hashes your key for you. If you supply a hash but no key, FaunaDB uses the hash. If you set both, FaunaDB prefers the hash.`

background_enable_garbage_collection Boolean true

Enables deletion of instance history according to each instance’s retention policy, configured in its class with the history_days and ttl_days fields.

background_enable_schema_deletion Boolean true

Enables deletion of a schema object (e.g. database, class, index) history after schema_retention_days + cache_schema_ttl_seconds.

background_enable_task_execution Boolean true

Enables asynchronous tasks such as index (re-)builds, schema cache shootdowns, and repair.

background_index_scan_period_seconds Integer 24 * 3600 * 7

Configures the amount of time taken (in seconds) to execute a table scan, across the corpus of indexes, for garbage collection and size estimation.

background_instance_scan_period_seconds Integer 24 * 3600 * 2

Configures the amount of time taken (in seconds) to execute a table scan, across the corpus of instances, for garbage collection and size estimation.

background_task_exec_backoff_time_seconds Integer 300

Configures the maximum amount of time (in seconds) that asynchronous task execution sleeps before polling for new work.

background_task_exec_sleep_time_seconds Integer 10

Configures the minimum amount of time (in seconds) that asynchronous task execution sleeps before polling for new work.

cache_schema_size_mb Integer 24

The amount of RAM (in megabytes) to give to the schema cache.

cache_schema_ttl_seconds Integer 60

Specifies how often (in seconds) that cached schema objects should be updated.

cluster_name String fauna Required

A unique name that identifies a cluster. Replicas only join a cluster with the same name.

http_ssl_password String

The password used to unlock the private key. Can be overridden with the environment variable FAUNADB_HTTP_SSL_PASSWORD.

http_ssl_key_file String

The path to the private key used to encrypt communication sent to the client.

http_ssl_trust_file String

The path to the trust certificate used to verify incoming private keys.

log_level String INFO

One of ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN.

log_path String /var/log/faunadb

The path to the directory containing all FaunaDB logs.

log_pattern String %d{ISO8601} %m%n

The log format string.

log_queries Boolean false

A flag indicating whether to log queries to a file.

log_rotate_count Integer 0

The number of rotated log files to retain.

log_rotate_size_mb Integer 128

The maximum size (in megabytes) that a log file is allowed to reach before rotating to a new file.

log_slow_query_ms Integer 5000

Log any query that takes longer than this threshold (in milliseconds) to the slow-query log.

log_trace Boolean false

A flag indicating whether to log traced queries to a file.

network_admin_http_address String 127.0.0.1

The IP address to bind the admin interface to.

network_admin_http_port Integer 8444

The port to bind the admin interface to.

network_broadcast_address String 127.0.0.1

This node’s IP address in a cluster. Should be accessible from any node in the cluster. Typically set to a node’s public/external IP address. See https://tools.ietf.org/html/rfc1918.

network_connections_per_host Integer 1

The number of sockets each member of a cluster should open to each other member of the cluster.

network_coordinator_http_address String The value of network_listen_address

The IP address to bind the coordinator to. For instance, if using a sidecar proxy on the same machine, you might bind this to localhost and send traffic through the proxy.

network_coordinator_http_port String 8443

The port to bind the coordinator to.

network_host_id String The value of network_broadcast_address

Sent in request headers to identify the coordinator of the request.

network_listen_address String The value of network_broadcast_address

Determines which network interface that Fauna should bind to. Should be accessible from nodes in the same replica. Typically set to a node’s private IP address. See https://tools.ietf.org/html/rfc1918.

network_max_message_bytes Integer Int.MaxValue (2147483647)

The maximum number of bytes in a single network message.

network_peer_port Integer 7500

The port used for inter-node communication.

network_peer_secure_port Integer 7501

The port used for inter-node encrypted communication. Nodes fall back to network_peer_port if they don’t require encryption. See peer_encryption_level.

network_read_timeout_ms Integer 5000

The time (in milliseconds) within which a read-only query must complete before an HTTP 503 response is returned.

network_round_trip_time_ms Integer 300

The network round trip time (in milliseconds) between replicas.

network_stream_timeout_ms Integer 30000

The time (in milliseconds) in which a data transfer, between members of a cluster, must complete before retrying.

network_write_timeout_ms Integer 30000

The time (in milliseconds) in which a write query must complete before returning an HTTP 503 response.

peer_encryption_cipher_suites Array of Strings

An array of allowed TLS/SSL cipher suites for node to node communications.

peer_encryption_key_file String

The path to the private key file. Use this option, or peer_encryption_key_store, but not both. If both are set, peer_encryption_key_store takes precedence.

peer_encryption_key_store String

The path to the private key store. Use this option, or peer_encryption_key_file, but not both. If both are set, peer_encryption_key_store takes precedence.

peer_encryption_level String

Determines what communication is encrypted:

none

no internal encryption

dc

only encrypt data between regions

all

encrypt all communication

peer_encryption_password String

The password used to unlock the private key/store. Can be overridden with the environment variable FAUNADB_PEER_ENCRYPTION_PASSWORD.

peer_encryption_trust_file String

The path to the trust certificate used to verify incoming keys. Use this option, or peer_encryption_trust_store, but not both. If both are set, peer_encryption_trust_store takes precedence.

peer_encryption_trust_store String

The path to the trust store used to verify incoming keys. Use this option, or peer_encryption_trust_file, but not both. If both are set, peer_encryption_trust_store takes precedence.

replica_name String The value of network_datacenter_name Required

A unique name for a replica within a cluster. A replica is a complete copy of the data.

runtime_heap_mb Integer Xmx

The maximum amount of heap assumed to be available to the database. Useful for JVMs <10 in container environments.

runtime_processors Integer detected from OS

The number of processors assumed to be available to the database. Useful for JVMs <10 in container environments.

schema_retention_days Integer 1

The number of days to wait before clearing all data in a deleted database, class, or index.

shutdown_grace_period_seconds Integer 30

Determines how long (in seconds) that the server should wait to gracefully shut down. Disables /ping to notify load balancers that the node is going to shut down.

stats_binary_protocol Boolean false

Use the binary protocol supported by statsite.

stats_csv_path String

Send stats to a CSV file located at this path. Use this option, or stats_host, but not both. If both are set, stats_host takes precedence.

stats_host String

Send stats to this host using the StatsD protocol. Use this option, or stats_csv_path, but not both. If both are set, stats_host takes precedence.

stats_poll_seconds Integer 10

How often (in seconds) that stats are flushed from internal buffers.

stats_port Integer 8125

Used in combination with stats_host, sets the UDP port that stats should be sent to.

stats_prefix String

A prefix added to every metric name, e.g. [prefix].metric-name.

storage_concurrent_reads Integer 128

The maximum number of concurrent read operations allowed.

storage_concurrent_writes Integer 256

The maximum number of concurrent write operations allowed.

storage_data_path String /var/lib/faunadb

The data storage directory.

storage_snapshot_path String storage_data_path/snapshots

The path to the snapshot storage directory. Typically, this is a folder within the data storage directory.

storage_sync_on_shutdown Boolean true

A flag that configures storage should flush in-memory state to disk prior to terminating the database.

storage_sync_period_mins Integer 2

Configures the amount of time (in minutes) between flushes of in-memory state to disk.

storage_temp_path String storage_data_path/tmp

The path to the temporary file storage directory. Typically, this is a folder within the data storage directory. This path is used for file transfers and native extensions. It is erased when the database starts.

Root access

Set the admin key for the cluster. Required to create databases or server keys, and must be set before a cluster can be initialized. Only one should be set.

The faunadb-admin hash-key KEY command creates a hash of KEY that can be used in auth_root_key_hash.

Set auth_root_key to the key in plain-text OR use the faunadb-admin hash-key KEY command to create a hash of KEY that can be used in auth_root_key_hash. If you supply a key but no hash, FaunaDB hashes your key for you. If you supply a hash but no key, FaunaDB uses the hash. If you set both, FaunaDB prefers the hash.

Name Default

auth_root_key

secret

auth_root_key_hash

Network peer communication ports

The ports that nodes use to communicate with each other. If peer-to-peer encryption is configured, nodes first initiate an SSL-encrypted connection over the secure ports. If it is established that the two nodes are in the same replica, then the connection is switched over to the normal ports and encryption is dropped.

It is acceptable to open network_peer_secure_port to the public internet. network_peer_port is unsecured and should be protected by a firewall or equivalent mechanism.

Name Default

network_peer_port

7500

network_peer_secure_port

7501

Cluster name

Identifies the FaunaDB Hybrid cluster. Nodes with different cluster names do not connect with each other. Required.

Name Default

cluster_name

fauna

Replica name

Identifies the replica the node is in.

Name Default

replica_name

NoDC

Network host ID

The identifier returned in the headers of requests to identify the coordinator of the request.

Name Default

network_host_id

network_broadcast_address

Broadcast address

The primary network address that identifies the node to the cluster. This should be routable by any node within the cluster.

In an AWS cluster, this should be set to the node’s public IP.

Name Default

network_broadcast_address

IP address associated with the node’s hostname

Listen address

In a situation where network_broadcast_address may not be set to the actual IP of the node, this setting determines the interface FaunaDB should bind to and should be set to the IP of the node.

It does not need to be routable by all nodes, but nodes within the same replica should be able to connect to it.

In an AWS cluster, this should be set to the node’s private IP.

Name Default

network_listen_address

IP address associated with the node

Data directories

Paths to log and data directories, respectively. These paths must exist and be writable by the FaunaDB service.

Name Default

log_path

/var/log/faunadb

storage_data_path

/var/lib/faunadb

storage_temp_path

»storage_path«/tmp

Snapshots are, by default, saved within the storage_data_path, but you can specify another place to store them using storage_snapshot_path. storage_temp_path lets you specify where FaunaDB stores its temporary files.

Log level

FaunaDB creates several logs that can help during the debugging process. By default, logging is done at the INFO level, and we recommend leaving that alone when you are first getting started. However, the log level can be raised or lowered through the configuration file. Logs can be disabled completely by setting log_level to OFF.

Name Default

log_level

INFO

FaunaDB config

You can specify the config file for the faunadb script using faunadb_config. If nothing is specified, FaunaDB looks for the config in the usual places (./faunadb.yml, /usr/etc/faunadb.yml, /etc/faunadb.yml).

Name Default

faunadb_config

Deprecated options

The following options were used in previous versions of FaunaDB. They continue to be accepted in current versions of FaunaDB, but you should consider updating your faunadb.yml file if these options are included.

Old option New option (if available) Version

auto_join_seed_host

2.5.4

background_task_threads

2.5.4

cache_reload_threads

2.6.0

coordinator_read_timeout_ms

2.7.0

coordinator_write_timeout_ms

2.7.0

encryption_cipher_suites

2.5.4

encryption_keystore

2.5.4

encryption_keystore_password

2.5.4

encryption_level

2.5.4

encryption_protocol

2.5.4

encryption_store_type

2.5.4

encryption_truststore

2.5.4

encryption_truststore_password

2.5.4

network_cluster_name

2.5.6

network_datacenter_name

2.5.6

network_rack_name

2.7.0

network_repair_timeout_ms

2.6.3

network_stream_throughput_mbit

2.7.0

storage_backup_requests

2.6.1

storage_enable_bootstrap

2.7.0

storage_num_tokens

2.6.0

storage_transaction_log_nodes

2.6.0

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!