Tuturial updates

doc/tutorial/01_install.md

@@ -5,50 +5,49 @@ in order to get a running connection pool.
 
 ## Preface
 
-This tutorial assumes that you already have an installation of PostgreSQL 12 (or higher).
+This tutorial assumes that you already have an installation of [PostgreSQL](https://www.postgresql.org) 13 (or higher).
 
 For RPM based distributions such as Fedora and RHEL you can add the
-[PostgreSQL YUM repository](https://yum.postgresql.org/){:target="_blank"}
-and do the install via the distribution package manager `dnf`:
+[PostgreSQL YUM repository](https://yum.postgresql.org/) and do the install via the distribution package manager `dnf`:
 
 ```
 dnf install -y pgagroal
 ```
 
-If you don't have PostgreSQL already installed, you can install both PostgreSQL and [**pgagroal**](https://github.com/agroal/pgagroal)
+If you don't have [PostgreSQL](https://www.postgresql.org) already installed, you can install both [PostgreSQL](https://www.postgresql.org) and [**pgagroal**](https://github.com/agroal/pgagroal)
 in a single pass:
 
 ```
 dnf install -y postgresql14 postgresql14-server pgagroal
 ```
 
-(assuming you want to install version 14 of PostgreSQL).
+Assuming you want to install version 14 of [PostgreSQL](https://www.postgresql.org).
 
 ### PostgreSQL setup
 
-In the case you don't have yet a PostgreSQL running instance, you need to initialize the cluster the connection pooler will connect to. The followings are simple and quick steps to get a cluster up and running as soon as possible.
+In the case you don't have yet a [PostgreSQL](https://www.postgresql.org) running instance, you need to initialize the cluster the connection pooler will connect to. The followings are simple and quick steps to get a cluster up and running as soon as possible.
 
 It is assumed that you run an RPM based distribution, like Fedora or RHEL. Some commands could be in different paths depending on the operating system distribution you are using.
 
 #### Initialize cluster
 
-You need to define a `PGDATA` data directory where PostgreSQL will store the data in.
-In the following, it is assumed that the PostgreSQL directory is `/postgres/14/data`, then
+You need to define a `PGDATA` data directory where [PostgreSQL](https://www.postgresql.org) will store the data in.
+In the following, it is assumed that the [PostgreSQL](https://www.postgresql.org) directory is `/postgres/14/data`, then
 you can do the following commands in a shell as the operating system user `postgres`:
 
 ```
 export PATH=/usr/pgsql-14/bin:$PATH
 mkdir -p /postgres/14/data
 export PGDATA=/postgres/14/data
-initdb $PGDATA
+initdb -k $PGDATA
 ```
 
 (`postgres` user)
 
 
 #### Remove default accesses
 
-By default, PostgreSQL allows trusted accesses from the local machine to any database within the cluster.
+By default, [PostgreSQL](https://www.postgresql.org) allows trusted accesses from the local machine to any database within the cluster.
 It is better to harden your cluster, thus providing accesses only to who and when it is needed.
 In order to do this, with your text editor of choice, edit the file `$PGDATA/pg_hba.conf` and remote the following lines:
 
@@ -61,43 +60,40 @@ host    replication     all             ::1/128                 trust
 ```
 
 from `/postgres/14/data/pg_hab.conf`
+
 (`postgres` user)
 
 #### Add access for a user and a database
 
 Assume you will have a database named `mydb` and a user named `myuser` that will be granted access to such database. In order to do so, edit again the `$PGDATA/pg_hba.conf` file and add a couple of lines like the followings:
 
 ```
-host    mydb             myuser          127.0.0.1/32            md5
-host    mydb             myuser          ::1/128                 md5
+host    mydb             myuser          127.0.0.1/32            scram-sha-256
+host    mydb             myuser          ::1/128                 scram-sha-256
 ```
 
 The first line  grants access to the user `myuser` against the database `mydb` on IPv4 `localhost`; the second line  does the same but on IPv6 `localhost` connection.
 
-Please check the value of the setting `password_encryption` in the configuration file `$PGDATA/postgresql.conf` in order to ensure it matches `md5` as the last column in the previous two lines.
-
+Please check the value of the setting `password_encryption` in the configuration file `$PGDATA/postgresql.conf` in order to ensure it matches `scram-sha-256` as the last column in the previous two lines.
 
 #### Start PostgreSQL
 
-It is now time to run the PostgreSQL instance, so as the `postgres` operating system user, run:
+It is now time to run the [PostgreSQL](https://www.postgresql.org) instance, so as the `postgres` operating system user, run:
 
 ```
-pg_ctl  -D $PGDATA start
+pg_ctl -D $PGDATA -l /tmp/logfile start
 ```
 
-
 #### Create the database and the user
 
 It is now time to create the database and the user of the previous step. As operating system user `postgres`, execute:
 
 ```
 psql -c "CREATE ROLE myuser WITH LOGIN PASSWORD 'mypassword';"
 psql -c "CREATE DATABASE mydb WITH OWNER myuser;"
-
 ```
 
-It is strongly suggested to choose a strong password to protect the database access!
-
+It is strongly suggested to choose a strong password to protect the database access !
 
 #### Verify access
 
@@ -109,7 +105,6 @@ psql -h localhost -p 5432 -U myuser -c 'SELECT current_timestamp:'  mydb
 
 Type the `mypassword` password when asked, and if you get back the current date and time, everything is working fine!
 
-
 ### pgagroal setup
 
 In order to run [**pgagroal**](https://github.com/agroal/pgagroal), you need at list to configure the main `pgagroal.conf` configuration file, that will tell the pooler how to work, and then `pgagroal_hba.conf` that will instrument the pooler about which users are allowed to connect thru the pooler.
@@ -134,14 +129,12 @@ As the [**pgagroal**](https://github.com/agroal/pgagroal) operating system user,
 
 ```
 pgagroal-admin master-key
-
 pgagroal-admin -f /etc/pgagroal/pgagroal_users.conf -U myuser -P mypassword user add
 ```
 
-**You have to choose a password for the master key - remember it!**
+**You have to choose a password for the master key - remember it !**
 
-
-It is now time to create the main `/etc/pgagroal/pgagroal.conf` configration file, with your editor of choice of using `cat` from the command line, create the following content:
+It is now time to create the main `/etc/pgagroal/pgagroal.conf` configuration file with your editor of choice or using `cat` from the command line, create the following content:
 
 ```
 cd /etc/pgagroal
@@ -164,7 +157,7 @@ host = localhost
 port = 5432
 ```
 
-and press `Ctrl-D` (if running `cat`) to save the file.
+and press `Ctrl-d` (if running `cat`) to save the file.
 
 Similarly, create the `/etc/pgagroal/pgagroal_hba.conf` file;
 
@@ -174,46 +167,37 @@ cat > pgagroal_hba.conf
 host   mydb   myuser   all   all
 ```
 
-and press `Ctrl-D` (if using `cat`) to save the file. Shortly,
-the above line tells `pgagral` to allow the user `myuser` to *try*
+and press `Ctrl-d` (if using `cat`) to save the file. The above line tells `pgagral` to allow the user `myuser` to *try*
 to connect to `mydb` using a TCP-IP connection.
 
 See [the documentation about `pgagroal_hba.conf` for more details](https://github.com/agroal/pgagroal/blob/master/doc/CONFIGURATION.md#pgagroal_hba-configuration).
 
-
 #### Start pgagroal
 
 It is now time to start [**pgagroal**](https://github.com/agroal/pgagroal), so as the [**pgagroal**](https://github.com/agroal/pgagroal) operating system user run:
 
 ```
-pgagroal -c /etc/pgagroal/pgagroal.conf -a /etc/pgagroal/pgagroal_hba.conf -u /etc/pgagroal/pgagroal_users.conf
+pgagroal -d
 ```
 
 If the system is running, you will see some output on the log file `/tmp/pgagroal.log`.
 
-Since the default configuration files are usually searched into the `/etc/pgagroal/` directory, and have well defined names, you can omit the files from the command line if you named them `pgagroal.conf`, `pgagroal_hba.conf` and `pgagroal_users.conf`:
-
-
-```
-pgagroal
-```
+Since the default configuration files are usually searched into the `/etc/pgagroal/` directory, and have well defined names, you can omit the files from the command line if you named them `pgagroal.conf`, `pgagroal_hba.conf` and `pgagroal_users.conf`.
 
 You will not need to specify any command line flag for files that have the standard name like:
-- `/etc/pgagroal/pgagroal.conf` (main configuration file)
-- `/etc/pgagroal/pgagroal_hba.conf` (host based access configuration file)
-- `/etc/pgagroal/pgagroal_databases.conf` (limits file)
-- `/etc/pgagroal/pgagroal_admins.conf` (remote management file)
-- `/etc/pgagroal/pgagroal_frontend_users.conf` (split security user remapping)
-
-**In the case you named the configuration files differently or in a different folder, you need to specify them on the command line!**
 
+* `/etc/pgagroal/pgagroal.conf` (main configuration file)
+* `/etc/pgagroal/pgagroal_hba.conf` (host based access configuration file)
+* `/etc/pgagroal/pgagroal_databases.conf` (limits file)
+* `/etc/pgagroal/pgagroal_admins.conf` (remote management file)
+* `/etc/pgagroal/pgagroal_frontend_users.conf` (split security user remapping)
 
+**In the case you named the configuration files differently or in a different folder, you need to specify them on the command line!**
 
 ### Shell completion
 
 There is a minimal shell completion support for `pgagroal-cli` and `pgagroal-admin`. If you are running such commands from a Bash or Zsh, you can take some advantage of command completion.
 
-
 #### Installing command completions in Bash
 
 There is a completion script into `contrib/shell_comp/pgagroal_comp.bash` that can be used

doc/tutorial/02_prefill.md

@@ -1,29 +1,33 @@
 ## Enable prefill for pgagroal
 
 This tutorial will show you how to do enable *prefill* for [**pgagroal**](https://github.com/agroal/pgagroal).
+
 The prefill is the capability to activate connections against a specific database
 even if no one has been actively requested by a user or an application. This allows the pooler
 to serve a connection faster once it is effectively requested, since the connection is already
 established.
 
-Prefill is done by making [**pgagroal**](https://github.com/agroal/pgagroal) to open the specified amount of connections to a specific database with a specific username, therefore you need to know credentials used on the PostgreSQL side.
+Prefill is done by making [**pgagroal**](https://github.com/agroal/pgagroal) to open the specified amount of connections to a specific database with a specific username,
+therefore you need to know credentials used on the [PostgreSQL](https://www.postgresql.org) side.
 
 ### Preface
 
-This tutorial assumes that you have already an installation of PostgreSQL 12 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
+This tutorial assumes that you have already an installation of [PostgreSQL](https://www.postgresql.org) 13 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
 
 In particular, this tutorial refers to the configuration done in [Install pgagroal](https://github.com/pgagroal/pgagroal/blob/master/doc/tutorial/01_install.md).
 
-
 ### Create prefill configuration
 
 Prefill is instrumented by the `pgagroal_databases.conf` configuration file, where you need
 to list databases, usernames, and limits.
+
 Every username/database pair has to be specified on a separated line.
+
 The limits are assumed as:
-- *max number of allowed connections* for that username/database
-- *initial number of connections*, that is the effective prefill;
-- *minimum number of connections* to always keep open for the pair username/database.
+
+* *max number of allowed connections* for that username/database
+* *initial number of connections* that is the effective prefill;
+* *minimum number of connections* to always keep open for the pair username/database.
 
 Assuming you want to configure the prefill for the `mydb` database with the `myuser` username,
 you have to edit the file `/etc/pgagroal/pgagroal_databases.conf` with your editor of choice
@@ -35,14 +39,15 @@ cat > pgagroal_databases.conf
 mydb   myuser   2   1   0
 ```
 
-and press `Ctrl-D` to save the file.
+and press `Ctrl-d` to save the file.
 
 This will create a configuration where `mydb` will have a maximum connection size of 2,
-an initial connection size of 1 and a minimum connection size of 0 for the `myuser` user.
+an initial connection size of 1 and a minimum connection size of 0 for the `myuser` user using the `mydb` database.
 
 The file must be owned by the operating system user [**pgagroal**](https://github.com/agroal/pgagroal).
 
 The `max_size` value is mandatory, while the `initial_size` and `min_size` are optional and if not explicitly set are assumed to be `0`.
+
 See [the `pgagroal_databases.conf` file documentation](https://github.com/agroal/pgagroal/blob/master/doc/CONFIGURATION.md#pgagroal_databases-configuration) for more details.
 
 ### Restart pgagroal
@@ -51,13 +56,12 @@ In order to apply changes to the prefill configuration, you need to restart [**p
 You can do so by stopping it and then re-launch the daemon, as [**pgagroal**](https://github.com/agroal/pgagroal) operating system user:
 
 ```
-pgagroal-cli -c /etc/pgagroal/pgagroal.conf shutdown
-pgagroal -c /etc/pgagroal/pgagroal.conf -a /etc/pgagroal/pgagroal_hba.conf -u /etc/pgagroal/pgagroal_users.conf -l /etc/pgagroal/pgagroal_databases.conf
+pgagroal-cli shutdown
+pgagroal -d
 ```
 
-Note that the limit file `pgagroal_databases.conf` has been specified by means of the `l` command line flag.
-If the file has the standard name `/etc/pgagroal/pgagroal_databases.conf`, you can omit it from the command line.
-
+Since the default configuration files are usually searched into the `/etc/pgagroal/` directory, and have well defined names, you can omit the files
+from the command line if you named them `pgagroal.conf`, `pgagroal_hba.conf`, `pgagroal_users.conf` and `pgagroal_databases.conf`.
 
 ### Check the prefill
 
@@ -69,7 +73,6 @@ Status:              Running
 Active connections:  0
 Total connections:   1
 Max connections:     100
-
 ```
 
 where the `Total connections` is set by the *initial* connection specified in the limit file.

doc/tutorial/03_remote_management.md

@@ -9,11 +9,10 @@ and make it to connect to the pooler machine via *remote management*.
 
 ## Preface
 
-This tutorial assumes that you have already an installation of PostgreSQL 12 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
+This tutorial assumes that you have already an installation of [PostgreSQL](https://www.postgresql.org) 13 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
 
 In particular, this tutorial refers to the configuration done in [Install pgagroal](https://github.com/pgagroal/pgagroal/blob/master/doc/tutorial/01_install.md).
 
-
 ### Enable remote management
 
 On the pooler machine, you need to enable the remote management. In order to do so,
@@ -41,6 +40,7 @@ See [the pgagroal configuration settings](https://github.com/agroal/pgagroal/blo
 ### Add remote admin user
 
 Remote management is done via a specific admin user, that has to be created within the pooler vault.
+
 As the [**pgagroal**](https://github.com/agroal/pgagroal) operating system user, run the following command:
 
 ```
@@ -49,20 +49,20 @@ pgagroal-admin -f pgagroal_admins.conf -U admin -P admin1234 add-user
 ```
 
 The above will create the `admin` username with the `admin1234` password.
-**We strongly encourage you to choose non trivial usernames and passwords!**
 
+**We strongly encourage you to choose non trivial usernames and passwords!**
 
 ### Restart pgagroal
 
 In order to make the changes available, and therefore activate the remote management, you have to restart [**pgagroal**](https://github.com/agroal/pgagroal), for example by issuing the following commands from the [**pgagroal**](https://github.com/agroal/pgagroal) operatng system user:
 
 ```
-pgagroal-cli -c /etc/pgagroal/pgagroal.conf shutdown
-pgagroal -c /etc/pgagroal/pgagroal.conf -a /etc/pgagroal/pgagroal_hba.conf -u /etc/pgagroal/pgagroal_users.conf -A /etc/pgagroal/pgagroal_admins.conf
+pgagroal-cli shutdown
+pgagroal -d
 ```
 
-Please note the presence of the `-A` flag that indicates to the pooler which file use to authenticate remote management users.
-If the file has the standard name `/etc/pgagroal/pgagroal_admins.conf` you can omit it from the command line.
+Since the default configuration files are usually searched into the `/etc/pgagroal/` directory, and have well defined names, you can omit the files from the command line
+if you named them `pgagroal.conf`, `pgagroal_hba.conf`, `pgagroal_users.conf` and `pgagroal_admins.conf`.
 
 ### Connect via remote administration interface
 

doc/tutorial/04_prometheus.md

@@ -1,13 +1,13 @@
 ## Prometheus metrics for pgagroal
 
-This tutorial will show you how to do basic  [Prometheus](https://prometheus.io/){:target="_blank"} setup  for [**pgagroal**](https://github.com/agroal/pgagroal).
+This tutorial will show you how to do basic  [Prometheus](https://prometheus.io/) setup  for [**pgagroal**](https://github.com/agroal/pgagroal).
 
 [**pgagroal**](https://github.com/agroal/pgagroal) is able to provide a set of metrics about what it is happening within the pooler,
 so that a Prometheus instance can collect them and help you monitor the pooler.
 
 ### Preface
 
-This tutorial assumes that you have already an installation of PostgreSQL 12 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
+This tutorial assumes that you have already an installation of [PostgreSQL](https://www.postgresql.org) 13 (or higher) and [**pgagroal**](https://github.com/agroal/pgagroal).
 
 In particular, this tutorial refers to the configuration done in [Install pgagroal](https://github.com/pgagroal/pgagroal/blob/master/doc/tutorial/01_install.md).
 
@@ -39,8 +39,8 @@ In order to apply changes, you need to restart [**pgagroal**](https://github.com
 as the [**pgagroal**](https://github.com/agroal/pgagroal) operating system user:
 
 ```
-pgagroal-cli -c /etc/pgagroal/pgagroal.conf shutdown
-pgagroal -c /etc/pgagroal/pgagroal.conf -a /etc/pgagroal/pgagroal_hba.conf
+pgagroal-cli shutdown
+pgagroal -d
 ```
 
 If you need to specify other configuration files, for example for remote management (see [the related tutorial](https://github.com/pgagroal/pgagroal/blob/master/doc/tutorial/03_remote_management.md)), add them on the [**pgagroal**](https://github.com/agroal/pgagroal) command line.
@@ -61,7 +61,8 @@ http://localhost:2346/
 ```
 
 ## Prometheus metrics for pgagroal-vault
-This tutorial will show you how to do basic  [Prometheus](https://prometheus.io/){:target="_blank"} setup  for [**pgagroal-vault**](https://github.com/agroal/pgagroal).
+
+This tutorial will show you how to do basic  [Prometheus](https://prometheus.io/) setup  for [**pgagroal-vault**](https://github.com/agroal/pgagroal).
 
 **pgagroal-vault** is able to provide a set of metrics about what it is happening within the vault, so that a Prometheus instance can collect them and help you monitor the vault activities.
 
@@ -99,4 +100,4 @@ It is also possible to get an explaination of what is the meaning of each metric
 
 ```
 http://localhost:2501/
-```
+```