---
name: "pgagroal.conf"
section: "5"
platform: "linux"
package: "pgagroal"
version: "1.6.0-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pgagroal.conf"
---

# pgagroal.conf(5)

Main configuration file for pgagroal

## NAME

pgagroal.conf - Main configuration file for pgagroal

## DESCRIPTION

pgagroal.conf is the main configuration file for pgagroal.

The file is split into different sections specified by the **\[** and **\]** characters. The main section is called **\[pgagroal\]**.

Other sections specifies the PostgreSQL server configuration.

All properties are in the format **key = value**.

The characters **#** and **;** can be used for comments; must be the first character on the line. The **Bool** data type supports the following values: **on**, **1**, **true**, **off**, **0** and **false**.

## OPTIONS

The options for the main section are

- **host**

  The bind address for pgagroal. Mandatory

- **port**

  The bind port for pgagroal. Mandatory

- **unix\_socket\_dir**

  The Unix Domain Socket location. Mandatory

- **metrics**

  The metrics port. Default is 0 (disabled)

- **metrics\_cache\_max\_age**

  The number of seconds to keep in cache a Prometheus (metrics) response. If set to zero, the caching will be disabled. Can be a string with a suffix, like **2m** to indicate 2 minutes. Default is 0 (disabled)

- **metrics\_cache\_max\_size**

  The maximum amount of data to keep in cache when serving Prometheus responses. Changes require restart. This parameter determines the size of memory allocated for the cache even if **metrics\_cache\_max\_age** or **metrics** are disabled. Its value, however, is taken into account only if **metrics\_cache\_max\_age** is set to a non-zero value. Supports suffixes: **B** (bytes), the default if omitted, **K** or **KB** (kilobytes), **M** or **MB** (megabytes), **G** or **GB** (gigabytes). Default is 256k

- **management**

  The remote management port. Default is 0 (disabled)

- **log\_type**

  The logging type (console, file, syslog). Default is console

- **log\_level**

  The logging level, any of the (case insensitive) strings **FATAL**, **ERROR**, **WARN**, **INFO** and **DEBUG** (that can be more specific as **DEBUG1** thru **DEBUG5**). Debug level greater than 5 will be set to **DEBUG5**. Not recognized values will make the **log\_level** be **INFO**. Default is info

- **log\_path**

  The log file location. Default is pgagroal.log. Can be a [strftime(3)](/strftime/3.md) compatible string

- **log\_rotation\_age**

  The age that will trigger a log file rotation. If expressed as a positive number, is managed as seconds. Supports suffixes: **S** (seconds, the default), **M** (minutes), **H** (hours), **D** (days), **W** (weeks). A value of **0** disables. Default is 0 (disabled)

- **log\_rotation\_size**

  The size of the log file that will trigger a log rotation. Supports suffixes: **B** (bytes), the default if omitted, **K** or **KB** (kilobytes), **M** or **MB** (megabytes), **G** or **GB** (gigabytes). A value of **0** (with or without suffix) disables. Default is 0

- **log\_line\_prefix**

  A [strftime(3)](/strftime/3.md) compatible string to use as prefix for every log line. Must be quoted if contains spaces. Default is **%Y-%m-%d %H:%M:%S**

- **log\_mode**

  Append to or create the log file (append, create). Default is append

- **log\_connections**

  Log connects. Default is off

- **log\_disconnections**

  Log disconnects. Default is off

- **blocking\_timeout**

  The number of seconds the process will be blocking for a connection (disable = 0). Default is 30

- **idle\_timeout**

  The number of seconds a connection is been kept alive (disable = 0). Default is 0

- **max\_connection\_age**

  The maximum number of seconds that a connection will live (disable = 0). Default is 0

- **validation**

  Should connection validation be performed. Valid options: off, foreground and background. Default is off

- **background\_interval**

  The interval between background validation scans in seconds. Default is 300

- **max\_retries**

  The maximum number of iterations to obtain a connection. Default is 5

- **max\_connections**

  The maximum number of connections (max 1000). Default is 1000

- **allow\_unknown\_users**

  Allow unknown users to connect. Default is true

- **authentication\_timeout**

  The number of seconds the process will wait for valid credentials. Default is 5

- **pipeline**

  The pipeline type. Valid options are auto, performance, session and transaction. Default is auto

- **auth\_query**

  Enable authentication query. Default is false

- **failover**

  Enable failover support. Default is false

- **failover\_script**

  The failover script

- **tls**

  Enable Transport Layer Security (TLS). Default is false

- **tls\_cert\_file**

  Certificate file for TLS

- **tls\_key\_file**

  Private key file for TLS

- **tls\_ca\_file**

  Certificate Authority (CA) file for TLS

- **libev**

  The libev backend to use. Valid options: auto, select, poll, epoll, iouring, devpoll and port. Default is auto

- **buffer\_size**

  The network buffer size (SO\_RCVBUF and SO\_SNDBUF). Default is 65535

- **keep\_alive**

  Have SO\_KEEPALIVE on sockets. Default is on

- **nodelay**

  Have TCP\_NODELAY on sockets. Default is on

- **non\_blocking**

  Have O\_NONBLOCK on sockets. Default is off

- **backlog**

  The backlog for listen(). Minimum 16. Default is max\_connections / 4

- **hugepage**

  Huge page support. Default is try

- **tracker**

  Track connection lifecycle. Default is off

- **track\_prepared\_statements**

  Track prepared statements (transaction pooling). Default is off

- **pidfile**

  Path to the PID file. If omitted, automatically set to **unix\_socket\_dir/pgagroal.port.pid**

- **update\_process\_title**

  The behavior for updating the operating system process title, mainly related to connection processes. Allowed settings are: **never** (or **off**), does not update the process title; **strict** to set the process title without overriding the existing initial process title length; **minimal** to set the process title to **username/database**; **verbose** (or **full**) to set the process title to **user@host:port/database**. Please note that **strict** and **minimal** are honored only on those systems that do not provide a native way to set the process title (e.g., Linux). On other systems, there is no difference between **strict** and **minimal** and the assumed behaviour is **minimal** even if **strict** is used. **never** and **verbose** are always honored, on every system. On Linux systems the process title is always trimmed to 255 characters, while on system that provide a natve way to set the process title it can be longer

Danger zone

- **disconnect\_client**

  Disconnect clients that have been idle for more than the specified seconds. This setting DOES NOT take long running transactions into account. Default is 0

- **disconnect\_client\_force**

  Disconnect clients that have been active for more than the specified seconds. This setting DOES NOT take long running transactions into account. Default is off

The options for the PostgreSQL section are

- **host**

  The address of the PostgreSQL instance. Mandatory

- **port**

  The port of the PostgreSQL instance. Mandatory

- **primary**

  Identify the instance as the primary instance (hint)

- **tls**

  Enable Transport Layer Security (TLS) support (Experimental - no pooling). Default is off

## REPORTING BUGS

pgagroal is maintained on GitHub at *https://github.com/agroal/pgagroal*

## COPYRIGHT

pgagroal is licensed under the 3-clause BSD License.

## SEE ALSO

[pgagroal\_hba.conf(5)](/pgagroal_hba.conf/5.md), [pgagroal\_databases.conf(5)](/pgagroal_databases.conf/5.md), [pgagroal(1)](/pgagroal/1.md), [pgagroal-cli(1)](/pgagroal-cli/1.md), [pgagroal-admin(1)](/pgagroal-admin/1.md)