From c1257d4c5c9f9632eda42a8660af587bf9712a3a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 21 Nov 2000 20:44:32 +0000 Subject: [PATCH] Improve comments in pg_hba.conf.sample and the associated SGML documentation. --- doc/src/sgml/client-auth.sgml | 154 ++++++++++++++------------ src/backend/libpq/pg_hba.conf.sample | 157 ++++++++++++++++----------- 2 files changed, 179 insertions(+), 132 deletions(-) diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 616867fbd3..af603a62e8 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,25 +1,24 @@ - + Client Authentication - User names from the operating system and from a - Postgres database installation are - logically separate. When a client application connects, it specifies - which database user name it wants to connect as, similar to how one - logs into a Unix computer. Within the SQL environment the active - database user name determines various access privileges to database + When a client application connects to the database server, it specifies which + Postgres user name it wants to connect as, + much the same way one logs into a Unix computer as a particular user. + Within the SQL environment the active + database user name determines access privileges to database objects -- see for more information - about that. It is therefore obviously essential to restrict what - database user name a given client can connect as. + about that. It is therefore obviously essential to restrict which + database user name(s) a given client can connect as. Authentication is the process by which the database server establishes the identity of the client, and by extension determines whether the client application (or the user - which runs the client application) is permitted to connect with the + who runs the client application) is permitted to connect with the user name that was requested. @@ -29,14 +28,26 @@ authentication methods available. + + Postgres database user names are logically + separate from user names of the operating system in which the server + runs. If all the users of a particular server also have accounts on + the server's machine, it makes sense to assign database user names + that match their Unix user ids. However, a server that accepts remote + connections may have many users who have no local account, and in such + cases there need be no connection between database usernames and Unix + usernames. + + The <filename>pg_hba.conf</filename> file Client authentication is controlled by the file - pg_hba.conf in the data directory, e.g., - /usr/local/pgsql/data/pg_hba.conf. (HBA = - host-based authentication) A default file is installed when the + pg_hba.conf in the $PGDATA directory, e.g., + /usr/local/pgsql/data/pg_hba.conf. (HBA stands + for host-based authentication.) A default pg_hba.conf + file is installed when the data area is initialized by initdb. @@ -84,7 +95,7 @@ hostssl database IP-addresshostssl - This record pertains to connection attemps with SSL over + This record pertains to connection attempts with SSL over TCP/IP. To make use of this option the server must be built with SSL support enabled. Furthermore, SSL must be enabled with the @@ -140,7 +153,7 @@ hostssl database IP-address The connection is allowed unconditionally. This method allows any user that has login access to the client host to connect as - any user whatsoever. + any Postgres user whatsoever. @@ -246,17 +259,18 @@ hostssl database IP-address - The first record that matches a connection attempt is used. There - is no fall-through or backup, that means, if + The first record that matches a connection attempt's client IP address + and requested database name is used to do the authentication step. + There is no fall-through or backup: if one record is chosen and the authentication fails, the following records are not considered. If no record matches, the access will be denied. - The pg_hba.conf file is re-read before each - connection attempt. It is therefore easily possible to modify - access permissions while the server is running. + The pg_hba.conf file is re-read during each + connection attempt. It is therefore trivial to modify access + permissions while the server is running: just edit the file. @@ -267,42 +281,44 @@ hostssl database IP-address An example <filename>pg_hba.conf</filename> file -#TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG - -# Allow any user on the local system to connect to any database under -# any user name. -# -host all 127.0.0.1 255.255.255.255 trust - -# Allow any user from any host with IP address 192.168.93.x to connect -# to database "template1" as the same user name that ident on that -# host identifies him as (typically his Unix user name). -# -host template1 192.168.93.0 255.255.255.0 ident sameuser - -# Allow a user from host 192.168.12.10 to connect to database -# "template1" if the user's password in pg_shadow is supplied. -# -host template1 192.168.12.10 255.255.255.255 crypt - -# In absence of the other records, this would allow anyone anywhere -# except from 192.168.54.1 to connect to any database under any user -# name. -# -host all 192.168.54.1 255.255.255.255 reject -host all 0.0.0.0 0.0.0.0 trust - -# Allow users from 192.168.77.x hosts to connect to any database, but if, -# for example, ident says the user is "bryanh" and he requests to -# connect as PostgreSQL user "guest1", the connection is only allowed if -# there is an entry for map "omicron" in `pg_ident.conf' that says -# "bryanh" is allowed to connect as "guest1". -# -host all 192.168.77.0 255.255.255.0 ident omicron - -# Allow all users to connect to all databases via Unix sockets. -# -local all trust +# TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP + +# Allow any user on the local system to connect to any +# database under any username, but only via an IP connection: + +host all 127.0.0.1 255.255.255.255 trust + +# The same, over Unix-socket connections: + +local all trust + +# Allow any user from any host with IP address 192.168.93.x to +# connect to database "template1" as the same username that ident on that +# host identifies him as (typically his Unix username): + +host template1 192.168.93.0 255.255.255.0 ident sameuser + +# Allow a user from host 192.168.12.10 to connect to database "template1" +# if the user's password in pg_shadow is correctly supplied: + +host template1 192.168.12.10 255.255.255.255 crypt + +# In the absence of preceding "host" lines, these two lines will reject +# all connection attempts from 192.168.54.1 (since that entry will be +# matched first), but allow Kerberos V5-validated connections from anywhere +# else on the Internet. The zero mask means that no bits of the host IP +# address are considered, so it matches any host: + +host all 192.168.54.1 255.255.255.255 reject +host all 0.0.0.0 0.0.0.0 krb5 + +# Allow users from 192.168.x.x hosts to connect to any database, if they +# pass the ident check. If, for example, ident says the user is "bryanh" +# and he requests to connect as PostgreSQL user "guest1", the connection +# is allowed if there is an entry in pg_ident.conf for map "omicron" that +# says "bryanh" is allowed to connect as "guest1": + +host all 192.168.0.0 255.255.0.0 ident omicron @@ -324,7 +340,7 @@ local all trust CREATE USER and ALTER USER, e.g., CREATE USER foo WITH PASSWORD 'secret';. By default, that is, if no password has - explicitly been set up, the stored password is NULL + been set up, the stored password is NULL and password authentication will always fail for that user. @@ -336,12 +352,12 @@ local all trust file after the password or crypt keyword, respectively, in pg_hba.conf. If you do not use this feature, then any user that is known to the database system can - connect to any database (as long as he passes password + connect to any database (so long as he passes password authentication, of course). - These files can also be used a apply a different set of passwords + These files can also be used to apply a different set of passwords to a particular database or set thereof. In that case, the files have a format similar to the standard Unix password file /etc/passwd, that is, @@ -401,7 +417,7 @@ local all trust In order to use Kerberos, support for it must be - enable at build time. Both Kerberos 4 and 5 are supported + enabled at build time. Both Kerberos 4 and 5 are supported (./configure --with-krb4 or ./configure --with-krb5 respectively). @@ -411,7 +427,7 @@ local all trust service. The name of the service principal is normally postgres, unless it was changed during the build. Make sure that your server key file is readable (and - preferrably only readable) by the Postgres server account (see + preferably only readable) by the Postgres server account (see ). The location of the key file is specified with the krb_server_keyfile run time configuration parameter. (See also .) @@ -553,13 +569,13 @@ local all trust A pg_ident.conf file that could be used in conjunction with the pg_hba.conf file in is shown in . In that example setup, anyone - logged in to a machine on the 192.168.77 network that does not have - the a user name bryanh, ann, or robert would not be granted access. + linkend="example-pg-ident.conf">. In this example setup, anyone + logged in to a machine on the 192.168 network that does not have + the Unix user name bryanh, ann, or robert would not be granted access. Unix user robert would only be allowed access when he tries to - connect as bob, not as robert or - anyone else. ann would only be allowed to connect - as herself. User bryanh would be allowed to connect as either + connect as Postgres user bob, not as robert + or anyone else. ann would only be allowed to connect as + ann. User bryanh would be allowed to connect as either bryanh himself or as guest1. diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample index 44010c7b9c..66b0252c0f 100644 --- a/src/backend/libpq/pg_hba.conf.sample +++ b/src/backend/libpq/pg_hba.conf.sample @@ -1,28 +1,23 @@ # -# # PostgreSQL HOST ACCESS CONTROL FILE # # # This file controls what hosts are allowed to connect to what databases -# and specifies some options on how users on a particular host are -# identified. It is read each time a host tries to make a connection to a -# database. +# and specifies how users on a particular host are identified. It is read +# by the PostgreSQL postmaster each time a host tries to make a connection +# to a database. # # Each line (terminated by a newline character) is a record. A record # cannot be continued across two lines. # # There are 3 kinds of records: -# # 1) comment: Starts with #. -# # 2) empty: Contains nothing excepting spaces and tabs. -# # 3) record: anything else. -# # Only record lines are significant. # # A record consists of tokens separated by spaces or tabs. Spaces and -# tabs at the beginning and end of a record are ignored as are extra +# tabs at the beginning and end of a record are ignored, as are extra # spaces and tabs between two tokens. # # The first token in a record is the record type. The interpretation of @@ -33,21 +28,29 @@ # ------------------ # # This record identifies a set of network hosts that are permitted to -# connect to databases. No network hosts are permitted to connect except -# as specified by a "host" record. See the record type "local" to specify -# permitted connections for local users via UNIX domain sockets. +# connect to databases via IP connections. No hosts are permitted to connect +# over IP except as specified by a "host" record. # # Format: # -# host DBNAME IP_ADDRESS ADDRESS_MASK AUTHTYPE [AUTH_ARGUMENT] +# host DBNAME IP_ADDRESS ADDRESS_MASK AUTHTYPE [AUTH_ARGUMENT] # -# DBNAME is the name of a PostgreSQL database, "all" to indicate all +# DBNAME is the name of a PostgreSQL database, or "all" to indicate all # databases, or "sameuser" to restrict a user's access to a database with -# the same user name. +# the same name as the user. # # IP_ADDRESS and ADDRESS_MASK are a standard dotted decimal IP address # and mask to identify a set of hosts. These hosts are allowed to connect -# to Database DBNAME. There is a separate section about AUTHTYPE below. +# to the database(s) identified by DBNAME. Note that the IP address must +# be specified numerically, not as a domain name. +# +# AUTHTYPE and AUTH_ARGUMENT are described below. +# +# There can be multiple "host" records, possibly with overlapping sets of +# host addresses. The postmaster scans to find the first entry that matches +# the connecting host IP address and the requested database name. This +# entry's AUTHTYPE will then be used to verify or reject the connection. +# If no entry matches the host+database, the connection is rejected. # Record type "hostssl" @@ -55,26 +58,31 @@ # # The format of this record is identical to that of "host". # -# This record identifies the authentication to use when connecting to a -# particular database via TCP/IP sockets over SSL. Note that normal -# "host" records are also matched - "hostssl" records can be used to -# require a SSL connection. This keyword is only available if the server -# is compiled with SSL support enabled. +# This record identifies a set of network hosts that are permitted to +# connect to databases over secure SSL IP connections. Note that a "host" +# record will also allow SSL connections; write "hostssl" if you want to +# accept *only* SSL-secured connections from this host or hosts. +# +# This keyword is only available if the server was compiled with SSL +# support enabled. # Record type "local" # ------------------ # -# This record identifies the authentication to use when connecting to a -# particular database via a local UNIX socket. +# This record identifies the authentication to use when connecting to +# the server via a local UNIX socket. UNIX-socket connections will be +# allowed only if this record type appears. # # Format: # -# local DBNAME AUTHTYPE [AUTH_ARGUMENT] +# local DBNAME AUTHTYPE [AUTH_ARGUMENT] # # The format is the same as that of the "host" record type except that -# the IP_ADDRESS and ADDRESS_MASK are omitted. Local supports only -# AUTHTYPEs "trust", "password", "crypt", and "reject". +# the IP_ADDRESS and ADDRESS_MASK are omitted. +# +# As with "host" records, the first "local" record matching the requested +# database name controls whether the connection is allowed. # Authentication Types (AUTHTYPE) @@ -82,7 +90,8 @@ # # AUTHTYPE is a keyword indicating the method used to authenticate the # user, i.e. to determine that the user is authorized to connect under -# the PostgreSQL username supplied in his connection parameters. +# the PostgreSQL username supplied in the connection request. A +# different AUTHTYPE can be specified for each record in the file. # # trust: No authentication is done. Trust that the user has the # authority to use whatever username he specifies. @@ -90,68 +99,90 @@ # password: Authentication is done by matching a password supplied # in clear by the host. If AUTH_ARGUMENT is specified then # the password is compared with the user's entry in that -# file (in the $PGDATA directory). See pg_passwd(1). If it -# is omitted then the password is compared with the user's -# entry in the pg_shadow table. +# file (in the $PGDATA directory). These per-host password +# files can be maintained with the pg_passwd(1) utility. +# If no AUTH_ARGUMENT appears then the password is compared +# with the user's entry in the pg_shadow table. # # crypt: Same as 'password', but authentication is done by # encrypting the password sent over the network. # # ident: Authentication is done by the ident server on the remote -# host, via the ident (RFC 1413) protocol. AUTH_ARGUMENT, -# if specified, is a map name to be found in the -# pg_ident.conf file. That table maps from ident usernames -# to PostgreSQL usernames. The special map name "sameuser" -# indicates an implied map (not found in pg_ident.conf) -# that maps every ident username to the identical -# PostgreSQL username. +# host, via the ident (RFC 1413) protocol. An AUTH_ARGUMENT +# is required: it is a map name to be found in the +# $PGDATA/pg_ident.conf file. The connection is accepted +# if pg_ident.conf contains an entry for this map name with +# the ident-supplied username and the requested PostgreSQL +# username. The special map name "sameuser" indicates an +# implied map (not sought in pg_ident.conf) that maps every +# ident username to the identical PostgreSQL username. # # krb4: Kerberos V4 authentication is used. # # krb5: Kerberos V5 authentication is used. # # reject: Reject the connection. +# +# Local (UNIX socket) connections support only AUTHTYPEs "trust", +# "password", "crypt", and "reject". # Examples # -------- # -# TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP +# TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP # -#host all 127.0.0.1 255.255.255.255 trust -# -# The above allows any user on the local system to connect to any -# database under any username. +# Allow any user on the local system to connect to any +# database under any username, but only via an IP connection: # -#host template1 192.168.93.0 255.255.255.0 ident sameuser -# -# The above allows any user from any host with IP address 192.168.93.x to -# connect to database template1 as the same username that ident on that -# host identifies him as (typically his Unix username). +# host all 127.0.0.1 255.255.255.255 trust +# +# The same, over Unix-socket connections: +# +# local all trust +# +# Allow any user from any host with IP address 192.168.93.x to +# connect to database "template1" as the same username that ident on that +# host identifies him as (typically his Unix username): # -#host template1 192.168.12.10 255.255.255.255 crypt +# host template1 192.168.93.0 255.255.255.0 ident sameuser # -# The above allows a user from host 192.168.12.10 to connect to -# database template1 if the user's password in pg_shadow is -# supplied. User passwords are optionally assigned when a -# user is created. +# Allow a user from host 192.168.12.10 to connect to database "template1" +# if the user's password in pg_shadow is correctly supplied: # -#host all 192.168.54.1 255.255.255.255 reject -#host all 0.0.0.0 0.0.0.0 trust +# host template1 192.168.12.10 255.255.255.255 crypt # -# The above would allow anyone anywhere except from 192.168.54.1 to -# connect to any database under any username. +# In the absence of preceding "host" lines, these two lines will reject +# all connection attempts from 192.168.54.1 (since that entry will be +# matched first), but allow Kerberos V5-validated connections from anywhere +# else on the Internet. The zero mask means that no bits of the host IP +# address are considered, so it matches any host: # -#host all 192.168.77.0 255.255.255.0 ident omicron +# host all 192.168.54.1 255.255.255.255 reject +# host all 0.0.0.0 0.0.0.0 krb5 # -# The above would allow users from 192.168.77.x hosts to connect to any -# database, but if Ident says the user is "bryanh" and he requests to -# connect as PostgreSQL user "guest1", the connection is only allowed if -# there is an entry for map "omicron" in pg_ident.conf that says "bryanh" -# is allowed to connect as "guest1". +# Allow users from 192.168.x.x hosts to connect to any database, if they +# pass the ident check. If, for example, ident says the user is "bryanh" +# and he requests to connect as PostgreSQL user "guest1", the connection +# is allowed if there is an entry in pg_ident.conf for map "omicron" that +# says "bryanh" is allowed to connect as "guest1": # +# host all 192.168.0.0 255.255.0.0 ident omicron +# + + +# Put your actual configuration here +# ---------------------------------- +# This default configuration allows any local user to connect as any +# PostgreSQL username, over either UNIX domain sockets or IP: -# By default, allow anything over UNIX domain sockets and localhost. local all trust host all 127.0.0.1 255.255.255.255 trust + +# If you want to allow non-local connections, you will need to add more +# "host" records (and don't forget to start the postmaster with "-i"!). + +# CAUTION: if you are on a multiple-user machine, the above default +# configuration is probably too liberal for you --- change it to use +# something other than "trust" authentication. -- 2.40.0