diff options
| -rw-r--r-- | doc/src/sgml/client-auth.sgml | 154 | ||||
| -rw-r--r-- | 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 616867fbd38..af603a62e83 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -1,25 +1,24 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.8 2000/10/21 01:08:34 petere Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.9 2000/11/21 20:44:31 tgl Exp $ --> <chapter id="client-authentication"> <title>Client Authentication</title> <para> - User names from the operating system and from a - <productname>Postgres</productname> 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 + <productname>Postgres</productname> 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 <xref linkend="user-manag"> 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. </para> <para> <firstterm>Authentication</firstterm> 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. </para> @@ -29,14 +28,26 @@ authentication methods available. </para> + <para> + <productname>Postgres</productname> 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. + </para> + <sect1 id="pg-hba.conf"> <title>The <filename>pg_hba.conf</filename> file</title> <para> Client authentication is controlled by the file - <filename>pg_hba.conf</filename> in the data directory, e.g., - <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA = - host-based authentication) A default file is installed when the + <filename>pg_hba.conf</filename> in the $PGDATA directory, e.g., + <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA stands + for host-based authentication.) A default <filename>pg_hba.conf</filename> + file is installed when the data area is initialized by <application>initdb</application>. </para> @@ -84,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable <term><literal>hostssl</literal></term> <listitem> <para> - 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 <option>-l</> option or equivalent configuration @@ -99,8 +110,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable <para> Specifies the database that this record applies to. The value <literal>all</literal> specifies that it applies to all - databases, the value <literal>sameuser</> identifies the - database with the same name as the connecting user. + databases, while the value <literal>sameuser</> identifies the + database with the same name as the connecting user. Otherwise, + this is the name of a specific <productname>Postgres</productname> + database. </para> </listitem> </varlistentry> @@ -140,7 +153,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable <para> 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 <productname>Postgres</productname> user whatsoever. </para> </listitem> </varlistentry> @@ -246,17 +259,18 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable </varlistentry> </variablelist> - The first record that matches a connection attempt is used. There - is no <quote>fall-through</> or <quote>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 <quote>fall-through</> or <quote>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. </para> <para> - The <filename>pg_hba.conf</filename> file is re-read before each - connection attempt. It is therefore easily possible to modify - access permissions while the server is running. + The <filename>pg_hba.conf</filename> 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. </para> <para> @@ -267,42 +281,44 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable <example id="example-pg-hba.conf"> <title>An example <filename>pg_hba.conf</filename> file</title> <programlisting> -#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 </programlisting> </example> </para> @@ -324,7 +340,7 @@ local all trust <command>CREATE USER</command> and <command>ALTER USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret';</userinput>. By default, that is, if no password has - explicitly been set up, the stored password is <quote>NULL</quote> + been set up, the stored password is <literal>NULL</literal> and password authentication will always fail for that user. </para> @@ -336,12 +352,12 @@ local all trust file after the <literal>password</> or <literal>crypt</> keyword, respectively, in <filename>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). </para> <para> - 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 <filename>/etc/passwd</filename>, that is, @@ -401,7 +417,7 @@ local all trust <para> In order to use <productname>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 (<literal>./configure --with-krb4</> or <literal>./configure --with-krb5</> respectively). </para> @@ -411,7 +427,7 @@ local all trust service. The name of the service principal is normally <literal>postgres</literal>, 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 <xref linkend="postgres-user">). The location of the key file is specified with the <varname>krb_server_keyfile</> run time configuration parameter. (See also <xref linkend="runtime-config">.) @@ -553,13 +569,13 @@ local all trust A <filename>pg_ident.conf</filename> file that could be used in conjunction with the <filename>pg_hba.conf</> file in <xref linkend="example-pg-hba.conf"> is shown in <xref - linkend="example-pg-ident.conf">. 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 <quote>bob</quote>, not as <quote>robert</quote> or - anyone else. <quote>ann</quote> would only be allowed to connect - <quote>as herself</>. User bryanh would be allowed to connect as either + connect as Postgres user <quote>bob</quote>, not as <quote>robert</quote> + or anyone else. <quote>ann</quote> would only be allowed to connect as + <quote>ann</>. User bryanh would be allowed to connect as either <quote>bryanh</> himself or as <quote>guest1</>. </para> diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample index 44010c7b9c5..66b0252c0f1 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. |