Skip to content

Commit

Permalink
[#407] Vault Implementation
Browse files Browse the repository at this point in the history
  • Loading branch information
ashu3103 committed Mar 24, 2024
1 parent 11a1f47 commit 8da9875
Show file tree
Hide file tree
Showing 40 changed files with 2,337 additions and 580 deletions.
2 changes: 1 addition & 1 deletion AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@ Nikita Bugrovsky <nbugrovs@redhat.com>
Lawrence Wu <lawrence910426@gmail.com>
Yongting You <2010youy01@gmail.com>
Ashutosh Sharma <ash2003sharma@gmail.com>
Henrique de Carvalho <decarv.henrique@gmail.com>
Henrique de Carvalho <decarv.henrique@gmail.com>
1 change: 1 addition & 0 deletions doc/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ The available keys and their accepted values are reported in the table below.
| log_disconnections | `off` | Bool | No | Log disconnects |
| blocking_timeout | 30 | Int | No | The number of seconds the process will be blocking for a connection (disable = 0) |
| idle_timeout | 0 | Int | No | The number of seconds a connection is been kept alive (disable = 0) |
| rotate_frontend_password_timeout | 0 | Int | No | The number of seconds after which the passwords of frontend users updated periodically (disable = 0) |
| max_connection_age | 0 | Int | No | The maximum number of seconds that a connection will live (disable = 0) |
| validation | `off` | String | No | Should connection validation be performed. Valid options: `off`, `foreground` and `background` |
| background_interval | 300 | Int | No | The interval between background validation scans in seconds |
Expand Down
50 changes: 50 additions & 0 deletions doc/VAULT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# pgagroal-vault configuration

The configuration which is mandatory is loaded from either the path specified by the `-c` flag or `/etc/pgagroal/pgagroal_vault.conf`.

The configuration of `pgagroal-vault` is split into sections using the `[` and `]` characters.

The pgagroal-vault section, called `[pgagroal-vault]`, is where you configure the overall properties of the vault's server.

The other section provide configuration for the management port of pgagroal. For now there can be only one pgagroal management port to connect.
This section don't have any requirements to their naming so you can give them
meaningful names but generally named as `[main]`.

All properties within a section are in the format `key = value`.

The characters `#` and `;` can be used for comments. A line is totally ignored if the
very first non-space character is a comment one, but it is possible to put a comment at the end of a line.
The `Bool` data type supports the following values: `on`, `yes`, `1`, `true`, `off`, `no`, `0` and `false`.

See a more complete [sample](./etc/pgagroal_vault.conf) configuration for running `pgagroal-vault` on `localhost`.

## [pgagroal-vault]

This section is mandatory and the pooler will refuse to start if the configuration file does not specify one and only one. Usually this section is place on top of the configuration file, but its position within the file does not really matter.
The available keys and their accepted values are reported in the table below.

| Property | Default | Unit | Required | Description |
|----------|---------|------|----------|-------------|
| host | | String | Yes | The bind address for pgagroal-vault |
| port | | Int | Yes | The bind port for pgagroal-vault |
| log_type | console | String | No | The logging type (console, file, syslog) |
| log_level | info | String | No | 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` |
| log_path | pgagroal.log | String | No | The log file location. Can be a strftime(3) compatible string. |
| log_rotation_age | 0 | String | No | 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. |
| log_rotation_size | 0 | String | No | 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. |
| log_line_prefix | %Y-%m-%d %H:%M:%S | String | No | A strftime(3) compatible string to use as prefix for every log line. Must be quoted if contains spaces. |
| log_mode | append | String | No | Append to or create the log file (append, create) |
| log_connections | `off` | Bool | No | Log connects |
| log_disconnections | `off` | Bool | No | Log disconnects |

## [main]

The section with a name different from `pgagroal-vault` will be treated as an main section.

| Property | Default | Unit | Required | Description |
|----------|---------|------|----------|-------------|
| host | | String | Yes | The address of the pgagroal running the management server |
| port | | Int | Yes | The management port of pgagroal |
| user | | String | Yes | The admin user of the pgagroal remote management service |

Note: For `pgagroal-vault` to function and connect properly to pgagroal, the remote server for management of the `pgagroal` should be enabled i.e. `management` should be greater than 0.
2 changes: 1 addition & 1 deletion doc/man/pgagroal-admin.1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -73,4 +73,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal(1), pgagroal-cli(1)
pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-vault(1)
2 changes: 1 addition & 1 deletion doc/man/pgagroal-cli.1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -108,4 +108,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal(1), pgagroal-admin(1)
pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal(1), pgagroal-admin(1), pgagroal-vault(1)
50 changes: 50 additions & 0 deletions doc/man/pgagroal-vault.1.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
==============
pgagroal-vault
==============

--------------------------------------------------------------------------------
Simple vault that hosts an HTTP server to handle user frontend password requests
--------------------------------------------------------------------------------

:Manual section: 1

SYNOPSIS
========

pgagroal-vault [ -c CONFIG_FILE ] [ -u USERS_FILE ]

DESCRIPTION
===========

**pgagroal-vault** is a basic HTTP server designed to handle special HTTP GET requests for retrieving pgagroal user passwords. When a client sends an HTTP GET request to ``http://<host_name>:<port>/users/<frontend_user>``, the vault extracts ``<frontend_user>`` from the URL. It then connects to the pgagroal main process to fetch the current ``<frontend_password>`` corresponding to the ``<frontend_user>``.

If the vault successfully fetches the ``<frontend_password>``, it responds with an HTTP status code 200 and includes ``<frontend_password>`` in the response body. Otherwise, the server responds with an HTTP 404 error indicating that the password for the specified user could not be found.

**Note:** For pgagroal-vault to operate correctly, the management port of the pgagroal server must be open and functional.

OPTIONS
=======

-c, --config CONFIG_FILE
Set the path to the pgagroal_vault.conf file

-u, --users USERS_FILE
Set the path to the pgagroal_vault_users.conf file

-?, --help
Display help

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.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal-cli(1), pgagroal-admin(1), pgagroal(1)
2 changes: 1 addition & 1 deletion doc/man/pgagroal.1.rst
Original file line number Diff line number Diff line change
Expand Up @@ -61,4 +61,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal-cli(1), pgagroal-admin(1)
pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal-cli(1), pgagroal-admin(1), pgagroal-vault(1)
5 changes: 4 additions & 1 deletion doc/man/pgagroal.conf.5.rst
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,9 @@ blocking_timeout
idle_timeout
The number of seconds a connection is been kept alive (disable = 0). Default is 0

rotate_frontend_password_timeout
The number of seconds after which the passwords of frontend users updated periodically (disable = 0). Default is 0

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

Expand Down Expand Up @@ -216,4 +219,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1)
pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1), pgagroal-vault(1)
2 changes: 1 addition & 1 deletion doc/man/pgagroal_databases.conf.5.rst
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1)
pgagroal.conf(5), pgagroal_hba.conf(5), pgagroal_vault.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1), pgagroal-vault(1)
2 changes: 1 addition & 1 deletion doc/man/pgagroal_hba.conf.5.rst
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ pgagroal is licensed under the 3-clause BSD License.
SEE ALSO
========

pgagroal.conf(5), pgagroal_databases.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1)
pgagroal.conf(5), pgagroal_databases.conf(5), pgagroal_vault.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1), pgagroal-vault(1)
94 changes: 94 additions & 0 deletions doc/man/pgagroal_vault.conf.5.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
===================
pgagroal_vault.conf
===================

------------------------------------------
Main configuration file for pgagroal-vault
------------------------------------------

:Manual section: 5

DESCRIPTION
===========

pgagroal_vault.conf is the main configuration file for pgagroal-vault.

The file is split into different sections specified by the ``[`` and ``]`` characters. The main section is called ``[pgagroal-vault]``.

Other sections (generally called the ``main`` section) specifies the ``pgagroal`` remote management 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 pgagroal-vault section are

host
The bind address for pgagroal-vault. Mandatory

port
The bind port for pgagroal-vault. Mandatory

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) 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) 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

The options for the main section are

host
The address of the pgagroal instance running the management server. Mandatory

port
The management port of pgagroal. Mandatory

user
The admin user of the pgagroal remote management service. Mandatory

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.conf(5), pgagroal_hba.conf(5), pgagroal_databases.conf(5), pgagroal(1), pgagroal-cli(1), pgagroal-admin(1), pgagroal-vault(1)
Loading

0 comments on commit 8da9875

Please sign in to comment.