doc: better document required postgres users

Add some docs to explain the stolon required postgres users, the reasons
and how to define them.

Author: sgotti

cmd/keeper/keeper.go

@@ -111,12 +111,12 @@ func init() {
 	cmdKeeper.PersistentFlags().StringVar(&cfg.pgListenAddress, "pg-listen-address", "localhost", "postgresql instance listening address")
 	cmdKeeper.PersistentFlags().StringVar(&cfg.pgPort, "pg-port", "5432", "postgresql instance listening port")
 	cmdKeeper.PersistentFlags().StringVar(&cfg.pgBinPath, "pg-bin-path", "", "absolute path to postgresql binaries. If empty they will be searched in the current PATH")
-	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplUsername, "pg-repl-username", "", "postgres replication user name. Required. It'll be created on db initialization. Requires --pg-repl-password or --pg-repl-passwordfile. Must be the same for all keepers.")
-	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplPassword, "pg-repl-password", "", "postgres replication user password. Required. Only one of --pg-repl-password or --pg-repl-passwordfile is required. Must be the same for all keepers.")
-	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplPasswordFile, "pg-repl-passwordfile", "", "postgres replication user password file. Only one of --pg-repl-password or --pg-repl-passwordfile is required. Must be the same for all keepers.")
+	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplUsername, "pg-repl-username", "", "postgres replication user name. Required. It'll be created on db initialization. Must be the same for all keepers.")
+	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplPassword, "pg-repl-password", "", "postgres replication user password. Only one of --pg-repl-password or --pg-repl-passwordfile must be provided. Must be the same for all keepers.")
+	cmdKeeper.PersistentFlags().StringVar(&cfg.pgReplPasswordFile, "pg-repl-passwordfile", "", "postgres replication user password file. Only one of --pg-repl-password or --pg-repl-passwordfile must be provided. Must be the same for all keepers.")
 	cmdKeeper.PersistentFlags().StringVar(&cfg.pgSUUsername, "pg-su-username", user, "postgres superuser user name. Used for keeper managed instance access and pg_rewind based synchronization. It'll be created on db initialization. Defaults to the name of the effective user running stolon-keeper. Must be the same for all keepers.")
-	cmdKeeper.PersistentFlags().StringVar(&cfg.pgSUPassword, "pg-su-password", "", "postgres superuser password. Needed for pg_rewind based synchronization. If provided it'll be configured on db initialization. Only one of --pg-su-password or --pg-su-passwordfile is required. Must be the same for all keepers.")
-	cmdKeeper.PersistentFlags().StringVar(&cfg.pgSUPasswordFile, "pg-su-passwordfile", "", "postgres superuser password file. Requires --pg-su-username. Must be the same for all keepers)")
+	cmdKeeper.PersistentFlags().StringVar(&cfg.pgSUPassword, "pg-su-password", "", "postgres superuser password. Only one of --pg-su-password or --pg-su-passwordfile must be provided. Must be the same for all keepers.")
+	cmdKeeper.PersistentFlags().StringVar(&cfg.pgSUPasswordFile, "pg-su-passwordfile", "", "postgres superuser password file. Only one of --pg-su-password or --pg-su-passwordfile must be provided. Must be the same for all keepers)")
 	cmdKeeper.PersistentFlags().StringVar(&cfg.logLevel, "log-level", "info", "debug, info (default), warn or error")
 	cmdKeeper.PersistentFlags().BoolVar(&cfg.debug, "debug", false, "enable debug logging")
 

doc/README.md

@@ -3,6 +3,7 @@
 We suggest that you first read the [Stolon Architecture and Requirements](architecture.md) to understand the primary concepts and avoid possible mistakes.
 
 * [Stolon Architecture and Requirements](architecture.md)
+* [Commands Invocation](commands_invocation.md)
 * [Cluster Specification](cluster_spec.md)
 * [Cluster Initialization](initialization.md)
 * [Setting instance parameters](postgres_parameters.md)
@@ -15,7 +16,6 @@ We suggest that you first read the [Stolon Architecture and Requirements](archit
 ### Misc topics
   * [Enabling pg_rewind](pg_rewind.md)
   * [Enabling synchronous replication](syncrepl.md)
-  * [Commands Invocation](commands_invocation.md)
 
 ### Recipes
   * [Manual switchover without transactions loss](manual_switchover.md)

doc/architecture.md

@@ -38,8 +38,37 @@ When this happens the stolon components not able to read or write to a quorate p
 In addition, the stolon-proxy, if not able to talk with the store, to avoid sending client connections to a paritioned master, will drop all the connections since it cannot know if the cluster data has changed (for example if the proxy has problems reading from the store but the sentinel can write to it).
 
 
-#### Handling permanent loss of the store.
+##### Handling permanent loss of the store.
 ed up
 If you have permanently lost your store you can create a new one BUT don't restore its contents (at least the stolon ones) from a backup since the backed up data could be older than the current real state and this could cause different problems. For example if you restore a stolon cluster data where the elected master was different than the current one, you can end up with this old master becoming the new master.
 
 The cleaner way is to reinitialize the stolon cluster using the `existing` `initMode` (see [Cluster Initialization](initialization.md)).
+
+
+#### PostgreSQL Users
+
+Stolon requires two kind of users:
+
+* a superuser
+* a replication user
+
+The superuser is used for:
+* managing/querying the keepers' controlled instances
+* execute (if enabled) pg_rewind based resync
+
+The replication user is used for:
+* managing/querying the keepers' controlled instances
+* replication between postgres instances
+
+Currently only md5 password based authentication is supported. In future different authentication mechanism will be added.
+
+To avoid security problems (user credentials cannot be globally defined in the cluster specification since if not correctly secured it could be read by anyone accessing the cluster store) these users and their related passwords must be provided as options to the stolon keepers and their values MUST be the same for all the keepers (or different things will break). These options are `--pg-su-username`, `--pg-su-password/--pg-su-passwordfile`, `--pg-repl-username` and `--pg-repl-password/--pg-repl-passwordfile`
+
+When a keeper initializes a new pg db cluster, the provided superuser and replication user will be created.
+
+#### Exceeding postgres max_connections
+
+When external clients exceeds the number of postgres max connections, new replication connection will fail blocking standbys from syncing. So always ensure to avoid this case or increase the max_connections postgres parameter value.
+
+Superuser connections will instead continue working until exceeding the `superuser_reserved_connections` value.
+For this reason external connections to the db as superuser should be avoided or they can exhaust the `superuser_reserved_connections` blocking the keeper from correctly managing and querying the instance status (reporting the instance as not healthy).

doc/pg_rewind.md

@@ -12,16 +12,4 @@ stolonctl [cluster options] update --patch '{ "usePgrewind" : true }'
 
 This will also enable the `wal_log_hints` postgresql parameter. If previously `wal_log_hints` wasn't enabled you should restart the postgresql instances (you can do so restarting the `stolon-keeper`)
 
-pg_rewind needs to connect to the master database with a superuser role.
-Currently only password authentication is supported. In future different authentication mechanism will be added.
-
-* It'll use the superuser role provided with `--pg-su-username` (if not specified it'll default to the os user name running the stolon-keeper). This superuser role (if not existing) needs to be created on the master database.
-* The superuser credentials need to be provided to the `stolon-keeper`.
-
-To avoid security problems (superuser credential cannot be globally defined in the cluster specification since currently it can be read by anyone accessing the cluster store) you have to set the superuser name and password when executing the `stolon-keeper`:
-* Providing the `--pg-su-username` and `--pg-su-passwordfile` (preferred) or `--pg-su-password` options (discouraged since every user accessing the system can read the password with a simple `ps`)
-* Exporting the `STKEEPER_PG_SU_USERNAME` and `STKEEPER_PG_SU_PASSWORD` environment variables.
-
-
-
-
+pg_rewind needs to connect to the master database with a superuser role (see the [Stolon Architecture and Requirements](architecture.md)).