From 1e87d363fc699dc583a04349d3d2074246d44e3b Mon Sep 17 00:00:00 2001 From: Marko Kreen Date: Wed, 5 Aug 2015 17:50:13 +0300 Subject: [PATCH] doc: consistent ws spacing for deflists --- doc/config.rst | 82 +++++++-------- doc/usage.rst | 264 ++++++++++++++++++++++++------------------------- 2 files changed, 173 insertions(+), 173 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index 7cac210..b7013a6 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -74,7 +74,7 @@ Default: not set user ---- -If set, specifies the Unix user to change to after startup. Works only if +If set, specifies the Unix user to change to after startup. Works only if PgBouncer is started as root or if it's already running as given user. Note: Not supported on Windows machines. @@ -106,33 +106,33 @@ auth_type How to authenticate users. ``hba`` - Actual auth type is loaded from `auth_hba_file`_. This allows different - authentication methods different access paths. Example: connection - over unix socket use ``peer`` auth method, connection over TCP - must use TLS. + Actual auth type is loaded from `auth_hba_file`_. This allows different + authentication methods different access paths. Example: connection + over unix socket use ``peer`` auth method, connection over TCP + must use TLS. ``cert`` - Client must connect over TLS connection with valid client cert. - Username is then taken from CommonName field from certificate. + Client must connect over TLS connection with valid client cert. + Username is then taken from CommonName field from certificate. ``md5`` - Use MD5-based password check. `auth_file`_ may contain both MD5-encrypted - or plain-text passwords. This is the default authentication method. + Use MD5-based password check. `auth_file`_ may contain both MD5-encrypted + or plain-text passwords. This is the default authentication method. ``crypt`` - Use crypt(3) based password check. `auth_file`_ must contain plain-text - passwords. Deprecated, removed in PostgreSQL 8.4. + Use crypt(3) based password check. `auth_file`_ must contain plain-text + passwords. Deprecated, removed in PostgreSQL 8.4. ``plain`` - Clear-text password is sent over wire. Deprecated. + Clear-text password is sent over wire. Deprecated. ``trust`` - No authentication is done. Username must still exist in `auth_file`_. + No authentication is done. Username must still exist in `auth_file`_. ``any`` - Like the ``trust`` method, but the username given is ignored. Requires that all - databases are configured to log in as specific user. Additionally, the console - database allows any user to log in as admin. + Like the ``trust`` method, but the username given is ignored. Requires that all + databases are configured to log in as specific user. Additionally, the console + database allows any user to log in as admin. auth_query ---------- @@ -147,14 +147,14 @@ pool_mode Specifies when a server connection can be reused by other clients. ``session`` - Server is released back to pool after client disconnects. Default. + Server is released back to pool after client disconnects. Default. ``transaction`` - Server is released back to pool after transaction finishes. + Server is released back to pool after transaction finishes. ``statement`` - Server is released back to pool after query finishes. Long transactions - spanning multiple statements are disallowed in this mode. + Server is released back to pool after query finishes. Long transactions + spanning multiple statements are disallowed in this mode. max_client_conn --------------- @@ -520,24 +520,24 @@ and `client_tls_cert_file`_ must be also configured to set up key and cert PgBouncer uses to accept client connections. ``disabled`` - Plain TCP. If client requests TLS, it's ignored. Default. + Plain TCP. If client requests TLS, it's ignored. Default. ``allow`` - If client requests TLS, it is used. If not, plain TCP is used. - If client uses client-certificate, it is not validated. + If client requests TLS, it is used. If not, plain TCP is used. + If client uses client-certificate, it is not validated. ``prefer`` - Same as ``allow``. + Same as ``allow``. ``require`` - Client must use TLS. If not, client connection is rejected. - If client uses client-certificate, it is not validated. + Client must use TLS. If not, client connection is rejected. + If client uses client-certificate, it is not validated. ``verify-ca`` - Client must use TLS with valid client certificate. + Client must use TLS with valid client certificate. ``verify-full`` - Same as ``verify-ca``. + Same as ``verify-ca``. client_tls_key_file ------------------- @@ -598,29 +598,29 @@ TLS mode to use for connections to PostgreSQL servers. TLS connections are disabled by default. ``disabled`` - Plain TCP. TCP is not event requested from server. Default. + Plain TCP. TCP is not event requested from server. Default. ``allow`` - FIXME: if server rejects plain, try TLS? + FIXME: if server rejects plain, try TLS? ``prefer`` - TLS connection is always requested first from PostgreSQL, - when refused connection will be establised over plain TCP. - Server certificate is not validated. + TLS connection is always requested first from PostgreSQL, + when refused connection will be establised over plain TCP. + Server certificate is not validated. ``require`` - Connection must go over TLS. If server rejects it, - plain TCP is not attempted. Server certificate is not validated. + Connection must go over TLS. If server rejects it, + plain TCP is not attempted. Server certificate is not validated. ``verify-ca`` - Connection must go over TLS and server certificate must be valid - according to `server_tls_ca_file`_. Server hostname is not checked - against certificate. + Connection must go over TLS and server certificate must be valid + according to `server_tls_ca_file`_. Server hostname is not checked + against certificate. ``verify-full`` - Connection must go over TLS and server certificate must be valid - according to `server_tls_ca_file`_. Server hostname must match - certificate info. + Connection must go over TLS and server certificate must be valid + according to `server_tls_ca_file`_. Server hostname must match + certificate info. server_tls_ca_file ------------------ diff --git a/doc/usage.rst b/doc/usage.rst index 64347e8..b0ea243 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -25,7 +25,7 @@ DESCRIPTION +pgbouncer+ is a PostgreSQL connection pooler. Any target application can be connected to +pgbouncer+ as if it were a PostgreSQL server, -and +pgbouncer+ will create a connection to the actual server, or it +and +pgbouncer+ will create a connection to the actual server, or it will reuse one of its existing connections. The aim of +pgbouncer+ is to lower the performance impact of opening @@ -36,20 +36,20 @@ pooling, +pgbouncer+ supports several types of pooling when rotating connections: Session pooling - Most polite method. When client connects, a server connection will - be assigned to it for the whole duration the client stays connected. When - the client disconnects, the server connection will be put back into the pool. - This is the default method. + Most polite method. When client connects, a server connection will + be assigned to it for the whole duration the client stays connected. When + the client disconnects, the server connection will be put back into the pool. + This is the default method. Transaction pooling - A server connection is assigned to client only during a transaction. - When PgBouncer notices that transaction is over, the server connection - will be put back into the pool. + A server connection is assigned to client only during a transaction. + When PgBouncer notices that transaction is over, the server connection + will be put back into the pool. Statement pooling - Most aggressive method. The server connection will be put back into - pool immediately after a query completes. Multi-statement - transactions are disallowed in this mode as they would break. + Most aggressive method. The server connection will be put back into + pool immediately after a query completes. Multi-statement + transactions are disallowed in this mode as they would break. The administration interface of +pgbouncer+ consists of some new +SHOW+ commands available when connected to a special 'virtual' @@ -73,7 +73,7 @@ Basic setup and usage as following. logfile = pgbouncer.log pidfile = pgbouncer.pid admin_users = someuser - + 2. Create a users.txt file:: "someuser" "same_password_as_in_server" @@ -110,45 +110,45 @@ Command line switches ===================== ``-d`` - Run in background. Without it the process will run in foreground. - Note: Does not work on Windows, +pgbouncer+ need to run as service there. + Run in background. Without it the process will run in foreground. + Note: Does not work on Windows, +pgbouncer+ need to run as service there. ``-R`` - Do an online restart. That means connecting to the running process, - loading the open sockets from it, and then using them. If there - is no active process, boot normally. - Note: Works only if OS supports Unix sockets and the `unix_socket_dir` - is not disabled in config. Does not work on Windows machines. - Does not work with TLS connections, they are dropped. + Do an online restart. That means connecting to the running process, + loading the open sockets from it, and then using them. If there + is no active process, boot normally. + Note: Works only if OS supports Unix sockets and the `unix_socket_dir` + is not disabled in config. Does not work on Windows machines. + Does not work with TLS connections, they are dropped. ``-u user`` - Switch to the given user on startup. + Switch to the given user on startup. ``-v`` - Increase verbosity. Can be used multiple times. + Increase verbosity. Can be used multiple times. ``-q`` - Be quiet - do not log to stdout. Note this does not affect - logging verbosity, only that stdout is not to be used. - For use in init.d scripts. + Be quiet - do not log to stdout. Note this does not affect + logging verbosity, only that stdout is not to be used. + For use in init.d scripts. ``-V`` - Show version. + Show version. ``-h`` - Show short help. + Show short help. ``--regservice`` - Win32: Register pgbouncer to run as Windows service. The +service_name+ - config parameter value is used as name to register under. + Win32: Register pgbouncer to run as Windows service. The +service_name+ + config parameter value is used as name to register under. ``--unregservice`` - Win32: Unregister Windows service. + Win32: Unregister Windows service. Admin console ============= -The console is available by connecting as normal to the +The console is available by connecting as normal to the database +pgbouncer+:: $ psql -p 6543 pgbouncer @@ -172,125 +172,125 @@ SHOW STATS; Shows statistics. ``database`` - Statistics are presented per database. + Statistics are presented per database. ``total_requests`` - Total number of +SQL+ requests pooled by +pgbouncer+. + Total number of +SQL+ requests pooled by +pgbouncer+. ``total_received`` - Total volume in bytes of network traffic received by +pgbouncer+. + Total volume in bytes of network traffic received by +pgbouncer+. ``total_sent`` - Total volume in bytes of network traffic sent by +pgbouncer+. + Total volume in bytes of network traffic sent by +pgbouncer+. ``total_query_time`` - Total number of microseconds spent by +pgbouncer+ when actively - connected to PostgreSQL. + Total number of microseconds spent by +pgbouncer+ when actively + connected to PostgreSQL. ``avg_req`` - Average requests per second in last stat period. + Average requests per second in last stat period. ``avg_recv`` - Average received (from clients) bytes per second. + Average received (from clients) bytes per second. ``avg_sent`` - Average sent (to clients) bytes per second. + Average sent (to clients) bytes per second. ``avg_query`` - Average query duration in microseconds. + Average query duration in microseconds. SHOW SERVERS; ------------- ``type`` - S, for server. + S, for server. ``user`` - Username +pgbouncer+ uses to connect to server. + Username +pgbouncer+ uses to connect to server. ``database`` - Database name. + Database name. ``state`` - State of the pgbouncer server connection, one of +active+, +used+ or - +idle+. + State of the pgbouncer server connection, one of +active+, +used+ or + +idle+. ``addr`` IP address of PostgreSQL server. ``port`` - Port of PostgreSQL server. + Port of PostgreSQL server. ``local_addr`` - Connection start address on local machine. + Connection start address on local machine. ``local_port`` - Connection start port on local machine. + Connection start port on local machine. ``connect_time`` - When the connection was made. + When the connection was made. ``request_time`` - When last request was issued. + When last request was issued. ``ptr`` - Address of internal object for this connection. - Used as unique ID. + Address of internal object for this connection. + Used as unique ID. ``link`` - Address of client connection the server is paired with. + Address of client connection the server is paired with. ``remote_pid`` - Pid of backend server process. In case connection is made over - unix socket and OS supports getting process ID info, it's - OS pid. Otherwise it's extracted from cancel packet server sent, - which should be PID in case server is Postgres, but it's a random - number in case server it another PgBouncer. + Pid of backend server process. In case connection is made over + unix socket and OS supports getting process ID info, it's + OS pid. Otherwise it's extracted from cancel packet server sent, + which should be PID in case server is Postgres, but it's a random + number in case server it another PgBouncer. SHOW CLIENTS; ------------- ``type`` - C, for client. + C, for client. ``user`` - Client connected user. + Client connected user. ``database`` - Database name. + Database name. ``state`` - State of the client connection, one of +active+, +used+, +waiting+ - or +idle+. + State of the client connection, one of +active+, +used+, +waiting+ + or +idle+. ``addr`` - IP address of client. + IP address of client. ``port`` - Port client is connected to. + Port client is connected to. ``local_addr`` - Connection end address on local machine. + Connection end address on local machine. ``local_port`` - Connection end port on local machine. + Connection end port on local machine. ``connect_time`` - Timestamp of connect time. + Timestamp of connect time. ``request_time`` - Timestamp of latest client request. + Timestamp of latest client request. ``ptr`` - Address of internal object for this connection. - Used as unique ID. + Address of internal object for this connection. + Used as unique ID. ``link`` - Address of server connection the client is paired with. + Address of server connection the client is paired with. ``remote_pid`` - Process ID, in case client connects over UNIX socket - and OS supports getting it. + Process ID, in case client connects over UNIX socket + and OS supports getting it. SHOW POOLS; ----------- @@ -298,42 +298,42 @@ SHOW POOLS; A new pool entry is made for each couple of (database, user). ``database`` - Database name. + Database name. ``user`` - User name. + User name. ``cl_active`` - Client connections that are linked to server connection and can process queries. + Client connections that are linked to server connection and can process queries. ``cl_waiting`` - Client connections have sent queries but have not yet got a server connection. + Client connections have sent queries but have not yet got a server connection. ``sv_active`` - Server connections that linked to client. + Server connections that linked to client. ``sv_idle`` - Server connections that unused and immediately usable for client queries. + Server connections that unused and immediately usable for client queries. ``sv_used`` - Server connections that have been idle more than `server_check_delay`, - so they needs `server_check_query` to run on it before it can be used. + Server connections that have been idle more than `server_check_delay`, + so they needs `server_check_query` to run on it before it can be used. ``sv_tested`` - Server connections that are currently running either `server_reset_query` - or `server_check_query`. + Server connections that are currently running either `server_reset_query` + or `server_check_query`. ``sv_login`` - Server connections currently in logging in process. + Server connections currently in logging in process. ``maxwait`` - How long the first (oldest) client in queue has waited, in seconds. - If this starts increasing, then the current pool of servers does - not handle requests quick enough. Reason may be either overloaded - server or just too small of a +pool_size+ setting. + How long the first (oldest) client in queue has waited, in seconds. + If this starts increasing, then the current pool of servers does + not handle requests quick enough. Reason may be either overloaded + server or just too small of a +pool_size+ setting. ``pool_mode`` - The pooling mode in use. + The pooling mode in use. SHOW LISTS; ----------- @@ -341,63 +341,63 @@ SHOW LISTS; Show following internal information, in columns (not rows): ``databases`` - Count of databases. + Count of databases. ``users`` - Count of users. + Count of users. ``pools`` - Count of pools. + Count of pools. ``free_clients`` - Count of free clients. + Count of free clients. ``used_clients`` - Count of used clients. + Count of used clients. ``login_clients`` - Count of clients in +login+ state. + Count of clients in +login+ state. ``free_servers`` - Count of free servers. + Count of free servers. ``used_servers`` - Count of used servers. + Count of used servers. SHOW USERS; ----------- ``name`` - The user name + The user name ``pool_mode`` - The user's override pool_mode, or NULL if the default will be used instead. + The user's override pool_mode, or NULL if the default will be used instead. SHOW DATABASES; --------------- ``name`` - Name of configured database entry. + Name of configured database entry. ``host`` - Host pgbouncer connects to. + Host pgbouncer connects to. ``port`` - Port pgbouncer connects to. + Port pgbouncer connects to. ``database`` - Actual database name pgbouncer connects to. + Actual database name pgbouncer connects to. ``force_user`` - When user is part of the connection string, the connection between - pgbouncer and PostgreSQL is forced to the given user, whatever the - client user. + When user is part of the connection string, the connection between + pgbouncer and PostgreSQL is forced to the given user, whatever the + client user. ``pool_size`` - Maximum number of server connections. + Maximum number of server connections. ``pool_mode`` - The database's override pool_mode, or NULL if the default will be used instead. + The database's override pool_mode, or NULL if the default will be used instead. SHOW FDS; --------- @@ -413,29 +413,29 @@ This command also blocks internal event loop, so it should not be used while PgBouncer is in use. ``fd`` - File descriptor numeric value. + File descriptor numeric value. ``task`` - One of +pooler+, +client+ or +server+. + One of +pooler+, +client+ or +server+. ``user`` - User of the connection using the FD. + User of the connection using the FD. ``database`` - Database of the connection using the FD. + Database of the connection using the FD. ``addr`` - IP address of the connection using the FD, +unix+ if a unix socket - is used. + IP address of the connection using the FD, +unix+ if a unix socket + is used. ``port`` - Port used by the connection using the FD. + Port used by the connection using the FD. ``cancel`` - Cancel key for this connection. + Cancel key for this connection. ``link`` - fd for corresponding server/client. NULL if idle. + fd for corresponding server/client. NULL if idle. SHOW CONFIG; ------------ @@ -444,14 +444,14 @@ Show the current configuration settings, one per row, with following columns: ``key`` - Configuration variable name + Configuration variable name ``value`` - Configuration value + Configuration value ``changeable`` - Either +yes+ or +no+, shows if the variable can be changed while running. - If +no+, the variable can be changed only boot-time. + Either +yes+ or +no+, shows if the variable can be changed while running. + If +no+, the variable can be changed only boot-time. SHOW DNS_HOSTS; --------------- @@ -459,13 +459,13 @@ SHOW DNS_HOSTS; Show hostnames in DNS cache. ``hostname`` - Host name. + Host name. ``ttl`` - How meny seconds until next lookup. + How meny seconds until next lookup. ``addrs`` - Comma separated list of addresses. + Comma separated list of addresses. SHOW DNS_ZONES -------------- @@ -473,13 +473,13 @@ SHOW DNS_ZONES Show DNS zones in cache. ``zonename`` - Zone name. + Zone name. ``serial`` - Current serial. + Current serial. ``count`` - Hostnames belonging to this zone. + Hostnames belonging to this zone. Process controlling commands @@ -536,13 +536,13 @@ Signals ~~~~~~~ ``SIGHUP`` - Reload config. Same as issuing command +RELOAD;+ on console. + Reload config. Same as issuing command +RELOAD;+ on console. ``SIGINT`` - Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console. + Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console. ``SIGTERM`` - Immediate shutdown. Same as issuing +SHUTDOWN;+ on console. + Immediate shutdown. Same as issuing +SHUTDOWN;+ on console. Libevent settings ~~~~~~~~~~~~~~~~~ -- 2.39.5