sharpetronics/PostgreSQL
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-11-04 00:02:52 -05:00
Code Issues Projects Releases Wiki Activity

Improve comments in pg_hba.conf.sample and the associated SGML

Browse Source 
documentation.
This commit is contained in:
Tom Lane 2000-11-21 20:44:32 +00:00
parent 280a77d3ee
commit c1257d4c5c
2 changed files with 175 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
doc/src/sgml/client-auth.sgml
View File

@ -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"> <chapter id="client-authentication">
<title>Client Authentication</title> <title>Client Authentication</title>
<para> <para>
User names from the operating system and from a When a client application connects to the database server, it specifies which
<productname>Postgres</productname> database installation are <productname>Postgres</productname> user name it wants to connect as,
logically separate. When a client application connects, it specifies much the same way one logs into a Unix computer as a particular user.
which database user name it wants to connect as, similar to how one Within the SQL environment the active
logs into a Unix computer. Within the SQL environment the active database user name determines access privileges to database
database user name determines various access privileges to database
objects -- see <xref linkend="user-manag"> for more information objects -- see <xref linkend="user-manag"> for more information
about that. It is therefore obviously essential to restrict what about that. It is therefore obviously essential to restrict which
database user name a given client can connect as. database user name(s) a given client can connect as.
</para> </para>
<para> <para>
<firstterm>Authentication</firstterm> is the process by which the <firstterm>Authentication</firstterm> is the process by which the
database server establishes the identity of the client, and by database server establishes the identity of the client, and by
extension determines whether the client application (or the user 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. user name that was requested.
</para> </para>
@ -29,14 +28,26 @@
authentication methods available. authentication methods available.
</para> </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"> <sect1 id="pg-hba.conf">
<title>The <filename>pg_hba.conf</filename> file</title> <title>The <filename>pg_hba.conf</filename> file</title>
<para> <para>
Client authentication is controlled by the file Client authentication is controlled by the file
<filename>pg_hba.conf</filename> in the data directory, e.g., <filename>pg_hba.conf</filename> in the $PGDATA directory, e.g.,
<filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA = <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA stands
host-based authentication) A default file is installed when the for host-based authentication.) A default <filename>pg_hba.conf</filename>
file is installed when the
data area is initialized by <application>initdb</application>. data area is initialized by <application>initdb</application>.
</para> </para>
@ -84,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<term><literal>hostssl</literal></term> <term><literal>hostssl</literal></term>
<listitem> <listitem>
<para> <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 TCP/IP. To make use of this option the server must be
built with SSL support enabled. Furthermore, SSL must be built with SSL support enabled. Furthermore, SSL must be
enabled with the <option>-l</> option or equivalent configuration enabled with the <option>-l</> option or equivalent configuration
@ -99,8 +110,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<para> <para>
Specifies the database that this record applies to. The value Specifies the database that this record applies to. The value
<literal>all</literal> specifies that it applies to all <literal>all</literal> specifies that it applies to all
databases, the value <literal>sameuser</> identifies the databases, while the value <literal>sameuser</> identifies the
database with the same name as the connecting user. database with the same name as the connecting user. Otherwise,
this is the name of a specific <productname>Postgres</productname>
database.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -140,7 +153,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<para> <para>
The connection is allowed unconditionally. This method allows The connection is allowed unconditionally. This method allows
any user that has login access to the client host to connect as any user that has login access to the client host to connect as
any user whatsoever. any <productname>Postgres</productname> user whatsoever.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -246,17 +259,18 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
</varlistentry> </varlistentry>
</variablelist> </variablelist>
The first record that matches a connection attempt is used. There The first record that matches a connection attempt's client IP address
is no <quote>fall-through</> or <quote>backup</>, that means, if 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 one record is chosen and the
authentication fails, the following records are not considered. If authentication fails, the following records are not considered. If
no record matches, the access will be denied. no record matches, the access will be denied.
</para> </para>
<para> <para>
The <filename>pg_hba.conf</filename> file is re-read before each The <filename>pg_hba.conf</filename> file is re-read during each
connection attempt. It is therefore easily possible to modify connection attempt. It is therefore trivial to modify access
access permissions while the server is running. permissions while the server is running: just edit the file.
</para> </para>
<para> <para>
@ -267,42 +281,44 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<example id="example-pg-hba.conf"> <example id="example-pg-hba.conf">
<title>An example <filename>pg_hba.conf</filename> file</title> <title>An example <filename>pg_hba.conf</filename> file</title>
<programlisting> <programlisting>
#TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG # TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP
# Allow any user on the local system to connect to any database under # Allow any user on the local system to connect to any
# any user name. # database under any username, but only via an IP connection:
#
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 host all 127.0.0.1 255.255.255.255 trust
# "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 # The same, over Unix-socket connections:
# 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, local all trust
# 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. # 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
local all trust # 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> </programlisting>
</example> </example>
</para> </para>
@ -324,7 +340,7 @@ local all trust
<command>CREATE USER</command> and <command>ALTER USER</command>, <command>CREATE USER</command> and <command>ALTER USER</command>,
e.g., <userinput>CREATE USER foo WITH PASSWORD e.g., <userinput>CREATE USER foo WITH PASSWORD
'secret';</userinput>. By default, that is, if no password has '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. and password authentication will always fail for that user.
</para> </para>
@ -336,12 +352,12 @@ local all trust
file after the <literal>password</> or <literal>crypt</> keyword, file after the <literal>password</> or <literal>crypt</> keyword,
respectively, in <filename>pg_hba.conf</>. If you do not use this respectively, in <filename>pg_hba.conf</>. If you do not use this
feature, then any user that is known to the database system can 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). authentication, of course).
</para> </para>
<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 to a particular database or set thereof. In that case, the files
have a format similar to the standard Unix password file have a format similar to the standard Unix password file
<filename>/etc/passwd</filename>, that is, <filename>/etc/passwd</filename>, that is,
@ -401,7 +417,7 @@ local all trust
<para> <para>
In order to use <productname>Kerberos</>, support for it must be 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 (<literal>./configure --with-krb4</> or <literal>./configure
--with-krb5</> respectively). --with-krb5</> respectively).
</para> </para>
@ -411,7 +427,7 @@ local all trust
service. The name of the service principal is normally service. The name of the service principal is normally
<literal>postgres</literal>, unless it was changed during the <literal>postgres</literal>, unless it was changed during the
build. Make sure that your server key file is readable (and 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 <xref linkend="postgres-user">). The location of the key file
is specified with the <varname>krb_server_keyfile</> run time is specified with the <varname>krb_server_keyfile</> run time
configuration parameter. (See also <xref linkend="runtime-config">.) 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 A <filename>pg_ident.conf</filename> file that could be used in
conjunction with the <filename>pg_hba.conf</> file in <xref conjunction with the <filename>pg_hba.conf</> file in <xref
linkend="example-pg-hba.conf"> is shown in <xref linkend="example-pg-hba.conf"> is shown in <xref
linkend="example-pg-ident.conf">. In that example setup, anyone linkend="example-pg-ident.conf">. In this example setup, anyone
logged in to a machine on the 192.168.77 network that does not have logged in to a machine on the 192.168 network that does not have
the a user name bryanh, ann, or robert would not be granted access. 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 Unix user robert would only be allowed access when he tries to
connect as <quote>bob</quote>, not as <quote>robert</quote> or connect as Postgres user <quote>bob</quote>, not as <quote>robert</quote>
anyone else. <quote>ann</quote> would only be allowed to connect or anyone else. <quote>ann</quote> would only be allowed to connect as
<quote>as herself</>. User bryanh would be allowed to connect as either <quote>ann</>. User bryanh would be allowed to connect as either
<quote>bryanh</> himself or as <quote>guest1</>. <quote>bryanh</> himself or as <quote>guest1</>.
</para> </para>

159
src/backend/libpq/pg_hba.conf.sample
View File

@ -1,28 +1,23 @@
# #
#
# PostgreSQL HOST ACCESS CONTROL FILE # PostgreSQL HOST ACCESS CONTROL FILE
# #
# #
# This file controls what hosts are allowed to connect to what databases # This file controls what hosts are allowed to connect to what databases
# and specifies some options on how users on a particular host are # and specifies how users on a particular host are identified. It is read
# identified. It is read each time a host tries to make a connection to a # by the PostgreSQL postmaster each time a host tries to make a connection
# database. # to a database.
# #
# Each line (terminated by a newline character) is a record. A record # Each line (terminated by a newline character) is a record. A record
# cannot be continued across two lines. # cannot be continued across two lines.
# #
# There are 3 kinds of records: # There are 3 kinds of records:
#
# 1) comment: Starts with #. # 1) comment: Starts with #.
#
# 2) empty: Contains nothing excepting spaces and tabs. # 2) empty: Contains nothing excepting spaces and tabs.
#
# 3) record: anything else. # 3) record: anything else.
#
# Only record lines are significant. # Only record lines are significant.
# #
# A record consists of tokens separated by spaces or tabs. Spaces and # 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. # spaces and tabs between two tokens.
# #
# The first token in a record is the record type. The interpretation of # 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 # This record identifies a set of network hosts that are permitted to
# connect to databases. No network hosts are permitted to connect except # connect to databases via IP connections. No hosts are permitted to connect
# as specified by a "host" record. See the record type "local" to specify # over IP except as specified by a "host" record.
# permitted connections for local users via UNIX domain sockets.
# #
# Format: # 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 # 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 # 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 # 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" # Record type "hostssl"
@ -55,26 +58,31 @@
# #
# The format of this record is identical to that of "host". # The format of this record is identical to that of "host".
# #
# This record identifies the authentication to use when connecting to a # This record identifies a set of network hosts that are permitted to
# particular database via TCP/IP sockets over SSL. Note that normal # connect to databases over secure SSL IP connections. Note that a "host"
# "host" records are also matched - "hostssl" records can be used to # record will also allow SSL connections; write "hostssl" if you want to
# require a SSL connection. This keyword is only available if the server # accept *only* SSL-secured connections from this host or hosts.
# is compiled with SSL support enabled. #
# This keyword is only available if the server was compiled with SSL
# support enabled.
# Record type "local" # Record type "local"
# ------------------ # ------------------
# #
# This record identifies the authentication to use when connecting to a # This record identifies the authentication to use when connecting to
# particular database via a local UNIX socket. # the server via a local UNIX socket. UNIX-socket connections will be
# allowed only if this record type appears.
# #
# Format: # 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 format is the same as that of the "host" record type except that
# the IP_ADDRESS and ADDRESS_MASK are omitted. Local supports only # the IP_ADDRESS and ADDRESS_MASK are omitted.
# AUTHTYPEs "trust", "password", "crypt", and "reject". #
# As with "host" records, the first "local" record matching the requested
# database name controls whether the connection is allowed.
# Authentication Types (AUTHTYPE) # Authentication Types (AUTHTYPE)
@ -82,7 +90,8 @@
# #
# AUTHTYPE is a keyword indicating the method used to authenticate the # AUTHTYPE is a keyword indicating the method used to authenticate the
# user, i.e. to determine that the user is authorized to connect under # 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 # trust: No authentication is done. Trust that the user has the
# authority to use whatever username he specifies. # authority to use whatever username he specifies.
@ -90,68 +99,90 @@
# password: Authentication is done by matching a password supplied # password: Authentication is done by matching a password supplied
# in clear by the host. If AUTH_ARGUMENT is specified then # in clear by the host. If AUTH_ARGUMENT is specified then
# the password is compared with the user's entry in that # the password is compared with the user's entry in that
# file (in the $PGDATA directory). See pg_passwd(1). If it # file (in the $PGDATA directory). These per-host password
# is omitted then the password is compared with the user's # files can be maintained with the pg_passwd(1) utility.
# entry in the pg_shadow table. # 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 # crypt: Same as 'password', but authentication is done by
# encrypting the password sent over the network. # encrypting the password sent over the network.
# #
# ident: Authentication is done by the ident server on the remote # ident: Authentication is done by the ident server on the remote
# host, via the ident (RFC 1413) protocol. AUTH_ARGUMENT, # host, via the ident (RFC 1413) protocol. An AUTH_ARGUMENT
# if specified, is a map name to be found in the # is required: it is a map name to be found in the
# pg_ident.conf file. That table maps from ident usernames # $PGDATA/pg_ident.conf file. The connection is accepted
# to PostgreSQL usernames. The special map name "sameuser" # if pg_ident.conf contains an entry for this map name with
# indicates an implied map (not found in pg_ident.conf) # the ident-supplied username and the requested PostgreSQL
# that maps every ident username to the identical # username. The special map name "sameuser" indicates an
# PostgreSQL username. # implied map (not sought in pg_ident.conf) that maps every
# ident username to the identical PostgreSQL username.
# #
# krb4: Kerberos V4 authentication is used. # krb4: Kerberos V4 authentication is used.
# #
# krb5: Kerberos V5 authentication is used. # krb5: Kerberos V5 authentication is used.
# #
# reject: Reject the connection. # reject: Reject the connection.
#
# Local (UNIX socket) connections support only AUTHTYPEs "trust",
# "password", "crypt", and "reject".
# Examples # 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 # 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
# #
# The above allows any user on the local system to connect to any # Allow a user from host 192.168.12.10 to connect to database "template1"
# database under any username. # if the user's password in pg_shadow is correctly supplied:
# #
#host template1 192.168.93.0 255.255.255.0 ident sameuser # host template1 192.168.12.10 255.255.255.255 crypt
#
# 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 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
# The above allows a user from host 192.168.12.10 to connect to # matched first), but allow Kerberos V5-validated connections from anywhere
# database template1 if the user's password in pg_shadow is # else on the Internet. The zero mask means that no bits of the host IP
# supplied. User passwords are optionally assigned when a # address are considered, so it matches any host:
# user is created.
# #
#host all 192.168.54.1 255.255.255.255 reject # host all 192.168.54.1 255.255.255.255 reject
#host all 0.0.0.0 0.0.0.0 trust # host all 0.0.0.0 0.0.0.0 krb5
# #
# The above would allow anyone anywhere except from 192.168.54.1 to # Allow users from 192.168.x.x hosts to connect to any database, if they
# connect to any database under any username. # 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.77.0 255.255.255.0 ident omicron # host all 192.168.0.0 255.255.0.0 ident omicron
#
# 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".
# #
# By default, allow anything over UNIX domain sockets and localhost. # 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:
local all trust local all trust
host all 127.0.0.1 255.255.255.255 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.