mirror of https://github.com/postgres/postgres
reference page to new configuration system. Big update to administrator's guide, chapters Runtime environment, Client authentication, and User management, the latter two were part of the old Security chapter.REL7_1_STABLE
Peter Eisentraut
26 years ago
parent
b4e906f191
commit
2c0edb3c86
@ -0,0 +1,502 @@ |
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.1 2000/06/18 21:24:51 petere 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 |
||||
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. |
||||
</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 |
||||
user name that was requested. |
||||
</para> |
||||
|
||||
<para> |
||||
<productname>Postgres</productname> offers client authentication by |
||||
(client) host and by database, with a number of different |
||||
authentication methods available. |
||||
</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 |
||||
data area is initialized by <application>initdb</application>. |
||||
</para> |
||||
|
||||
<para> |
||||
The general format of the <filename>pg_hba.conf</filename> file is |
||||
of a set of records, one per line. Blank lines and lines beginning |
||||
with a hash character (<quote>#</quote>) are ignored. A record is |
||||
made up of a number of fields which are separated by spaces and/or |
||||
tabs. |
||||
</para> |
||||
|
||||
<para> |
||||
A record may have one of the two formats |
||||
<synopsis> |
||||
local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ] |
||||
host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ] |
||||
</synopsis> |
||||
The meaning of the fields is as follows: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term><literal>local</literal></term> |
||||
<listitem> |
||||
<para> |
||||
This record pertains to connection attempts over Unix domain |
||||
sockets. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term><literal>host</literal></term> |
||||
<listitem> |
||||
<para> |
||||
This record pertains to connection attempts over TCP/IP |
||||
networks. Note that TCP/IP connections are completely disabled |
||||
unless the server is started with the <option>-i</option> or |
||||
the equivalent configuration parameter is set. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term><replaceable>database</replaceable></term> |
||||
<listitem> |
||||
<para> |
||||
Specifies the database that this record applies to. The value |
||||
<literal>all</literal> specifies that it applies to all |
||||
databases. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term><replaceable>IP address</replaceable></term> |
||||
<term><replaceable>IP mask</replaceable></term> |
||||
<listitem> |
||||
<para> |
||||
These two fields control to which hosts a |
||||
<literal>host</literal> record applies, based on their IP |
||||
address. (Of course IP addresses can be spoofed but this |
||||
consideration is beyond the scope of |
||||
<productname>Postgres</productname>.) The precise logic is that |
||||
<blockquote> |
||||
<informalfigure> |
||||
<programlisting>(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable></programlisting> |
||||
</informalfigure> |
||||
</blockquote> |
||||
must be zero for the record to match. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term><replaceable>authentication method</replaceable></term> |
||||
<listitem> |
||||
<para> |
||||
Specifies the method a user must use to authenticate themselves |
||||
when connecting to that database. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term><replaceable>authentication option</replaceable></term> |
||||
<listitem> |
||||
<para> |
||||
This field is interpreted differently depending on the |
||||
authentication method. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
|
||||
The first record that matches a connection attempt is used. Note |
||||
that there is no <quote>fall-through</quote> or |
||||
<quote>backup</quote>, that is, 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. |
||||
</para> |
||||
|
||||
<para> |
||||
An example of a <filename>pg_hba.conf</filename> file is shown in |
||||
<xref linkend="example-pg-hba.conf">. See below for details on the |
||||
different authentication methods. |
||||
|
||||
<example id="example-pg-hba.conf"> |
||||
<title>An example <filename>pg_hba.conf</filename> file</title> |
||||
<programlisting> |
||||
# Trust any connection via Unix domain sockets. |
||||
local trust |
||||
# Trust any connection via TCP/IP from this machine. |
||||
host all 127.0.0.1 255.255.255.255 trust |
||||
# We don't like this machine. |
||||
host all 192.168.0.10 255.255.255.0 reject |
||||
# This machine can't encrypt so we ask for passwords in clear. |
||||
host all 192.168.0.3 255.255.255.0 password |
||||
# The rest of this group of machines should provide encrypted passwords. |
||||
host all 192.168.0.0 255.255.255.0 crypt |
||||
# Authenticate these networks using ident |
||||
host all 192.168.1.0 255.255.255.0 ident usermap |
||||
host all 192.168.2.0 255.255.255.0 ident othermap |
||||
</programlisting> |
||||
</example> |
||||
</para> |
||||
</sect1> |
||||
|
||||
<sect1 id="auth-methods"> |
||||
<title>Authentication methods</title> |
||||
<para> |
||||
The following authentication methods are supported. They are |
||||
descibed in detail below. |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>trust</term> |
||||
<listitem> |
||||
<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. Use with care. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>reject</term> |
||||
<listitem> |
||||
<para> |
||||
The connection is rejected unconditionally. This is mostly |
||||
useful to <quote>filter out</quote> certain hosts from a group. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>password</term> |
||||
<listitem> |
||||
<para> |
||||
The client is required to supply a password for the connection |
||||
attempt which is required to match the password that was set up |
||||
for the user. (These passwords are separate from any operating |
||||
sytem password.) |
||||
</para> |
||||
<para> |
||||
An optional password file may be specified after the |
||||
<literal>password</literal> keyword to obtain the password from |
||||
that file rather than the pg_shadow system catalog. |
||||
</para> |
||||
<para> |
||||
The password is sent over the wire in clear text. For better |
||||
protection, use the <literal>crypt</literal> method. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>crypt</term> |
||||
<listitem> |
||||
<para> |
||||
Like the <literal>password</literal> method, but the password |
||||
is sent over the wire encrypted using a simple |
||||
challenge-response protocol. Note that this is still not |
||||
cryptographically secure but it protects against incidental |
||||
wire-sniffing. Interestingly enough, the |
||||
<literal>crypt</literal> does not support secondary password |
||||
files. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>krb4</term> |
||||
<listitem> |
||||
<para> |
||||
Kerberos V4 is used to authenticate the user. This is only |
||||
available for TCP/IP connections. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>krb5</term> |
||||
<listitem> |
||||
<para> |
||||
Kerberos V5 is used to authenticate the user. This is only |
||||
available for TCP/IP connections. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>ident</term> |
||||
<listitem> |
||||
<para> |
||||
The ident server on the client host is asked for the identity |
||||
of the connecting user. <productname>Postgres</productname> |
||||
then verifies whether the so identified operating system user |
||||
is allowed to connect as the database user that is requested. |
||||
The <replaceable>authentication option</replaceable> following |
||||
the <literal>ident</> keyword specifies the name of an |
||||
<firstterm>ident map</firstterm> that specifies which operating |
||||
system users equate with which database users. See below for |
||||
details. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
|
||||
<sect2> |
||||
<title>Password authentication</title> |
||||
<para> |
||||
Ordinarily, the password for each database user is stored in the |
||||
pg_shadow system catalog table. Passwords can be managed with the |
||||
query language commands <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> and password authentication will always fail |
||||
for that user. |
||||
</para> |
||||
|
||||
<para> |
||||
Secondary password files can be used if a given set of passwords |
||||
should only apply to a particular database or set thereof. |
||||
Secondary password files have a format similar to the standard |
||||
Unix password file <filename>/etc/passwd</filename>, that is, |
||||
<synopsis> |
||||
<replaceable>username</replaceable>:<replaceable>password</replaceable> |
||||
</synopsis> |
||||
Any extra colon separated fields following the password are |
||||
ignored. The password is expected to be encrypted using the |
||||
system's <function>crypt()</function> function. The utility |
||||
program <application>pg_passwd</application> that is installed |
||||
with <productname>Postgres</productname> can be used to manage |
||||
these password files. |
||||
</para> |
||||
|
||||
<para> |
||||
Secondary password files can also be used to restrict certain |
||||
users from connecting to certain databases at all. This is |
||||
currently not possible to achieve using the normal password |
||||
mechanism (because users and passwords are global across all |
||||
databases). If a user is not listed in the applicable password |
||||
file the connection will be refused. |
||||
</para> |
||||
|
||||
<para> |
||||
Note that using secondary password files means that one can no |
||||
longer use <command>ALTER USER</command> to change one's password. |
||||
It will still appear to work but the password one is actually |
||||
changing is not the password that the system will end up using. |
||||
</para> |
||||
</sect2> |
||||
|
||||
<sect2> |
||||
<title>Kerberos authentication</title> |
||||
|
||||
<para> |
||||
<productname>Kerberos</productname> is an industry-standard secure |
||||
authentication system suitable for distributed computing over a |
||||
public network. A description of the |
||||
<productname>Kerberos</productname> system is far beyond the scope |
||||
of this document; in all generality it can be quite complex. The |
||||
<ulink url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos <acronym>FAQ</></ulink> |
||||
can be a good starting point for exploration. |
||||
</para> |
||||
|
||||
<para> |
||||
In order to use <productname>Kerberos</>, support for it must be |
||||
enable at build time. Both Kerberos 4 and 5 are supported. |
||||
</para> |
||||
|
||||
<para> |
||||
<productname>Postgres</> should operate like a normal Kerberos |
||||
service. The name of the service principal is normally |
||||
<literal>postgres</literal>, unless it was changed during the |
||||
build. Make sure that your server keytab file is readable (and |
||||
preferrably only readable) by the Postgres server account (see |
||||
<xref linkend="postgres-user">). The location of the keytab file |
||||
is specified at build time. By default it is |
||||
<filename>/etc/srvtab</filename> in Kerberos 4 and |
||||
<filename>FILE:/usr/local/postgres/krb5.keytab</filename> in |
||||
Kerberos 5. |
||||
</para> |
||||
<!-- Note from Peter E.: Some of the Kerberos usage information is |
||||
still in config.sgml and some in doc/README.kerberos. It should be |
||||
integrated here. --> |
||||
</sect2> |
||||
|
||||
<sect2> |
||||
<title>Ident-based authentication</title> |
||||
|
||||
<para> |
||||
The <quote>Identification Protocol</quote> is described in |
||||
<citetitle>RFC 1413</citetitle>. Virtually every Unix-like |
||||
operating systems ships with an ident server that listens on TCP |
||||
port 113 by default. The basic functionality of the ident server |
||||
is to answer questions like <quote>What user initiated the |
||||
connection that goes out of your port <replaceable>X</replaceable> |
||||
and connects to my port <replaceable>Y</replaceable>?</quote>. |
||||
Since both <replaceable>X</replaceable> and |
||||
<replaceable>Y</replaceable> are known, |
||||
<productname>Postgres</productname> could theoretically determine |
||||
the operating system user for any given connection this way. |
||||
</para> |
||||
|
||||
<para> |
||||
The drawback of this procedure is that it depends on the integrity |
||||
of the client: if the client machine is untrusted or compromised |
||||
an attacker could run just about any program on port 113 and |
||||
return any user name he chooses. This authentication method is |
||||
therefore only appropriate for closed networks where each client |
||||
machine is under tight control and where the database and system |
||||
administrators operate in close contact. Heed the warning: |
||||
<blockquote> |
||||
<attribution>RFC 1413</attribution> |
||||
<para> |
||||
The Identification Protocol is not intended as an authorization |
||||
or access control protocol. |
||||
</para> |
||||
</blockquote> |
||||
</para> |
||||
|
||||
<para> |
||||
When using ident-based authentication, after having determined the |
||||
operating system user that initiated the connection, |
||||
<productname>Postgres</productname> determines as what database |
||||
system user he may connect. This is controlled by the ident map |
||||
argument that follows the <literal>ident</> keyword in the |
||||
<filename>pg_hba.conf</filename> file. The simplest ident map is |
||||
<literal>sameuser</literal>, which allows any operating system |
||||
user to connect as the database user of the same name (if the |
||||
latter exists). Other maps must be created manually. |
||||
</para> |
||||
|
||||
<para> |
||||
Ident maps are held in the file <filename>pg_ident.conf</filename> |
||||
in the data directory, which contains lines of the general form: |
||||
<synopsis> |
||||
<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</> |
||||
</synopsis> |
||||
Comments and whitespace are handled in the usual way. |
||||
The <replaceable>map-name</> is an arbitrary name that will be |
||||
used to refer to this mapping in <filename>pg_hba.conf</filename>. |
||||
The other two fields specify which operating system user is |
||||
allowed to connect as which database user. The same |
||||
<replaceable>map-name</> can be used repeatedly to specify more |
||||
user-mappings. There is also no restriction regarding how many |
||||
database users a given operating system may correspond to and vice |
||||
versa. |
||||
</para> |
||||
|
||||
<para> |
||||
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.1 network that does not have |
||||
the a user name joe, robert, or ann 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> and <quote>joe</quote> would only |
||||
be allowed to connect <quote>as themselves</quote>. On the |
||||
192.168.2 network, however, a user <quote>ann</quote> would not be |
||||
allowed to connect at all, only the user <quote>bob</> can connect |
||||
as <quote>bob</> and some user <quote>karl</> can connect as |
||||
<quote>joe</> as well. |
||||
</para> |
||||
|
||||
<example id="example-pg-ident.conf"> |
||||
<title>An example <filename>pg_ident.conf</> file</title> |
||||
<programlisting> |
||||
usermap joe joe |
||||
# bob has username robert on these machines |
||||
usermap robert bob |
||||
usermap ann ann |
||||
|
||||
othermap joe joe |
||||
othermap bob bob |
||||
othermap karl joe |
||||
</programlisting> |
||||
</example> |
||||
</sect2> |
||||
</sect1> |
||||
|
||||
<sect1 id="client-authentication-problems"> |
||||
<title>Authentication problems</title> |
||||
|
||||
<para> |
||||
Genuine authentication failures and related problems generally |
||||
manifest themselves through error messages like the following. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb |
||||
</ProgramListing> |
||||
This is what you are most likely to get if you succeed in |
||||
contacting the server, but it doesn't want to talk to you. As the |
||||
message suggests, the server refused the connection request |
||||
because it found no authorizing entry in its <filename>pg_hba.conf</filename> |
||||
configuration file. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
Password authentication failed for user 'joeblow' |
||||
</ProgramListing> |
||||
Messages like this indicate that you contacted the server, and |
||||
it's willing to talk to you, but not until you pass the |
||||
authorization method specified in the |
||||
<filename>pg_hba.conf</filename> file. Check the password you're |
||||
providing, or check your Kerberos or IDENT software if the |
||||
complaint mentions one of those authentication types. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow' |
||||
</ProgramListing> |
||||
This is the fancy way of saying that the user doesn't exist at all. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
FATAL 1: Database testdb does not exist in pg_database |
||||
</ProgramListing> |
||||
The database you're trying to connect to doesn't exist. Note that |
||||
if you don't specify a database name, it defaults to the database |
||||
user name, which may or may not be the right thing. |
||||
</para> |
||||
</sect1> |
||||
|
||||
</chapter> |
||||
|
||||
@ -1,240 +0,0 @@ |
||||
<!-- |
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/pg_options.sgml,v 1.5 2000/03/31 03:27:41 thomas Exp $ |
||||
--> |
||||
|
||||
<Chapter Id="pg-options-dev"> |
||||
<DocInfo> |
||||
<AuthorGroup> |
||||
<Author> |
||||
<FirstName>Massimo</FirstName> |
||||
<Surname>Dal Zotto</Surname> |
||||
</Author> |
||||
</AuthorGroup> |
||||
<Date>Transcribed 1998-10-16</Date> |
||||
</DocInfo> |
||||
|
||||
<Title>pg_options</Title> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
<Para> |
||||
The optional file <filename>data/pg_options</filename> contains runtime |
||||
options used by the backend to control trace messages and other backend |
||||
tunable parameters. |
||||
What makes this file interesting is the fact that it is re-read by a backend |
||||
when it receives a SIGHUP signal, making thus possible to change run-time |
||||
options on the fly without needing to restart |
||||
<productname>Postgres</productname>. |
||||
The options specified in this file may be debugging flags used by the trace |
||||
package (<filename>backend/utils/misc/trace.c</filename>) or numeric |
||||
parameters which can be used by the backend to control its behaviour. |
||||
New options and parameters must be defined in |
||||
<filename>backend/utils/misc/trace.c</filename> and |
||||
<filename>backend/include/utils/trace.h</filename>. |
||||
</para> |
||||
<Para> |
||||
For example suppose we want to add conditional trace messages and a tunable |
||||
numeric parameter to the code in file <filename>foo.c</filename>. |
||||
All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into |
||||
<filename>backend/include/utils/trace.h</filename>: |
||||
|
||||
<programlisting> |
||||
/* file trace.h */ |
||||
enum pg_option_enum { |
||||
... |
||||
TRACE_FOO, /* trace foo functions */ |
||||
OPT_FOO_PARAM, /* foo tunable parameter */ |
||||
|
||||
NUM_PG_OPTIONS /* must be the last item of enum */ |
||||
}; |
||||
</programlisting> |
||||
|
||||
and a corresponding line in <filename>backend/utils/misc/trace.c</filename>: |
||||
|
||||
<programlisting> |
||||
/* file trace.c */ |
||||
static char *opt_names[] = { |
||||
... |
||||
"foo", /* trace foo functions */ |
||||
"fooparam" /* foo tunable parameter */ |
||||
}; |
||||
</programlisting> |
||||
|
||||
Options in the two files must be specified in exactly the same order. |
||||
In the foo source files we can now reference the new flags with: |
||||
|
||||
<programlisting> |
||||
/* file foo.c */ |
||||
#include "trace.h" |
||||
#define foo_param pg_options[OPT_FOO_PARAM] |
||||
|
||||
int |
||||
foo_function(int x, int y) |
||||
{ |
||||
TPRINTF(TRACE_FOO, "entering foo_function, foo_param=%d", foo_param); |
||||
if (foo_param > 10) { |
||||
do_more_foo(x, y); |
||||
} |
||||
} |
||||
</programlisting> |
||||
</para> |
||||
<para> |
||||
Existing files using private trace flags can be changed by simply adding |
||||
the following code: |
||||
|
||||
<programlisting> |
||||
#include "trace.h" |
||||
/* int my_own_flag = 0; -- removed */ |
||||
#define my_own_flag pg_options[OPT_MY_OWN_FLAG] |
||||
</programlisting> |
||||
</para> |
||||
<para> |
||||
All pg_options are initialized to zero at backend startup. If we need a |
||||
different default value we must add some initialization code at the beginning |
||||
of <function>PostgresMain</function>. |
||||
|
||||
Now we can set the foo_param and enable foo trace by writing values into the |
||||
<filename>data/pg_options</filename> file: |
||||
|
||||
<programlisting> |
||||
# file pg_options |
||||
... |
||||
foo=1 |
||||
fooparam=17 |
||||
</programlisting> |
||||
</para> |
||||
<para> |
||||
The new options will be read by all new backends when they are started. |
||||
To make effective the changes for all running backends we need to send a |
||||
SIGHUP to the postmaster. The signal will be automatically sent to all the |
||||
backends. We can also activate the changes only for a specific backend by |
||||
sending the SIGHUP directly to it. |
||||
</para> |
||||
<para> |
||||
pg_options can also be specified with the <option>-T</option> switch of |
||||
<productname>Postgres</productname>: |
||||
|
||||
<programlisting> |
||||
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-" |
||||
</programlisting> |
||||
</para> |
||||
<Para> |
||||
The functions used for printing errors and debug messages can now make use |
||||
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout |
||||
or stderr are prefixed by a timestamp containing also the backend pid: |
||||
|
||||
<programlisting> |
||||
#timestamp #pid #message |
||||
980127.17:52:14.173 [29271] StartTransactionCommand |
||||
980127.17:52:14.174 [29271] ProcessUtility: drop table t; |
||||
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full |
||||
980127.17:52:14.186 [29286] Async_NotifyHandler |
||||
980127.17:52:14.186 [29286] Waking up sleeping backend process |
||||
980127.19:52:14.292 [29286] Async_NotifyFrontEnd |
||||
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done |
||||
980127.19:52:14.466 [29286] Async_NotifyHandler done |
||||
</programlisting> |
||||
</para> |
||||
<para> |
||||
This format improves readability of the logs and allows people to understand |
||||
exactly which backend is doing what and at which time. It also makes |
||||
easier to write simple awk or perl scripts which monitor the log to |
||||
detect database errors or problem, or to compute transaction time statistics. |
||||
</para> |
||||
<para> |
||||
Messages printed to syslog use the log facility LOG_LOCAL0. |
||||
The use of syslog can be controlled with the syslog pg_option. |
||||
Unfortunately many functions call directly <function>printf()</function> |
||||
to print their messages to stdout or stderr and this output can't be |
||||
redirected to syslog or have timestamps in it. |
||||
It would be advisable that all calls to printf would be replaced with the |
||||
PRINTF macro and output to stderr be changed to use EPRINTF instead so that |
||||
we can control all output in a uniform way. |
||||
</Para> |
||||
|
||||
<Para> |
||||
The new pg_options mechanism is more convenient than defining new backend |
||||
option switches because: |
||||
|
||||
<ItemizedList Mark="bullet" Spacing="compact"> |
||||
<ListItem> |
||||
<Para> |
||||
we don't have to define a different switch for each thing we want to control. |
||||
All options are defined as keywords in an external file stored in the data |
||||
directory. |
||||
</Para> |
||||
</ListItem> |
||||
|
||||
<ListItem> |
||||
<Para> |
||||
we don't have to restart <productname>Postgres</productname> to change |
||||
the setting of some option. |
||||
Normally backend options are specified to the postmaster and passed to each |
||||
backend when it is started. Now they are read from a file. |
||||
</Para> |
||||
</ListItem> |
||||
|
||||
<ListItem> |
||||
<Para> |
||||
we can change options on the fly while a backend is running. We can thus |
||||
investigate some problem by activating debug messages only when the problem |
||||
appears. We can also try different values for tunable parameters. |
||||
</Para> |
||||
</ListItem> |
||||
</ItemizedList> |
||||
|
||||
The format of the <filename>pg_options</filename> file is as follows: |
||||
|
||||
<programlisting> |
||||
# <replaceable>comment</replaceable> |
||||
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable> |
||||
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0 |
||||
</programlisting> |
||||
|
||||
Note that <replaceable class="parameter">keyword</replaceable> can also be |
||||
an abbreviation of the option name defined in |
||||
<filename>backend/utils/misc/trace.c</filename>. |
||||
</Para> |
||||
|
||||
<para> |
||||
Refer to <citetitle>The Administrator's Guide</citetitle> chapter |
||||
on runtime options for a complete list of currently supported |
||||
options. |
||||
</para> |
||||
|
||||
<Para> |
||||
Some of the existing code using private variables and option switches has |
||||
been changed to make use of the pg_options feature, mainly in |
||||
<filename>postgres.c</filename>. It would be advisable to modify |
||||
all existing code |
||||
in this way, so that we can get rid of many of the switches on |
||||
the <productname>Postgres</productname> command line |
||||
and can have more tunable options |
||||
with a unique place to put option values. |
||||
</Para> |
||||
|
||||
</Chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode:sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:("/usr/lib/sgml/catalog") |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,53 @@ |
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_constraints.sgml,v 1.1 2000/06/18 21:24:54 petere Exp $ --> |
||||
<refentry id="SQL-SET-CONSTRAINTS"> |
||||
<refmeta> |
||||
<refentrytitle id="SQL-SET-CONSTRAINTS-title">SET CONSTRAINTS</refentrytitle> |
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo> |
||||
</refmeta> |
||||
<refnamediv> |
||||
<refname>SET CONSTRAINTS</refname> |
||||
<refpurpose>Set the constraint mode of the current SQL-transaction</refpurpose> |
||||
</refnamediv> |
||||
<refsynopsisdiv> |
||||
<refsynopsisdivinfo> |
||||
<date>2000-06-01</date> |
||||
</refsynopsisdivinfo> |
||||
<synopsis> |
||||
SET CONSTRAINTS { ALL | <replaceable class="parameter">constraint</replaceable> [, ...] } { DEFERRED | IMMEDIATE } |
||||
</synopsis> |
||||
</refsynopsisdiv> |
||||
|
||||
<refsect1> |
||||
<title>Description</title> |
||||
|
||||
<para> |
||||
<command>SET CONSTRAINTS</command> sets the behavior of constraint |
||||
evaluation in the current transaction. In |
||||
<option>IMMEDIATE</option> mode, constraints are checked at the end |
||||
of each statement. In <option>DEFERRED</option> mode, constraints |
||||
are not checked until transaction commit. |
||||
</para> |
||||
|
||||
<para> |
||||
Upon creation, a constraint is always give one of three |
||||
characteristics: <option>INITIALLY DEFERRED</option>, |
||||
<option>INITIALLY IMMEDIATE DEFERRABLE</option>, or |
||||
<option>INITIALLY IMMEDIATE NOT DEFERRABLE</option>. The third |
||||
class is not affected by the <command>SET CONSTRAINTS</command> |
||||
command. |
||||
</para> |
||||
|
||||
<para> |
||||
Currently, only foreign key constraints are affected by this |
||||
setting. Check and unique constraints are always effectively |
||||
initially immediate not deferrable. |
||||
</para> |
||||
</refsect1> |
||||
|
||||
<refsect1> |
||||
<title>Compatibility</title> |
||||
<para> |
||||
SQL92, SQL99 |
||||
</para> |
||||
</refsect1> |
||||
</refentry> |
||||
@ -0,0 +1,93 @@ |
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.1 2000/06/18 21:24:54 petere Exp $ --> |
||||
<refentry id="SQL-SET-TRANSACTION"> |
||||
<refmeta> |
||||
<refentrytitle id="SQL-SET-TRANSACTION-title">SET TRANSACTION</refentrytitle> |
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo> |
||||
</refmeta> |
||||
<refnamediv> |
||||
<refname>SET TRANSACTION</refname> |
||||
<refpurpose>Set the characteristics of the current SQL-transaction</refpurpose> |
||||
</refnamediv> |
||||
<refsynopsisdiv> |
||||
<refsynopsisdivinfo> |
||||
<date>2000-06-01</date> |
||||
</refsynopsisdivinfo> |
||||
<synopsis> |
||||
SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } |
||||
</synopsis> |
||||
</refsynopsisdiv> |
||||
|
||||
<refsect1> |
||||
<title>Description</title> |
||||
|
||||
<para> |
||||
The <command>SET TRANSACTION</command> command sets the |
||||
characteristics for the current SQL-transaction. It has no effect |
||||
on any subsequent transactions. This command cannot be used after |
||||
the first DML statement (<command>SELECT</command>, |
||||
<command>INSERT</command>, <command>DELETE</command>, |
||||
<command>UPDATE</command>, <command>FETCH</command>, |
||||
<command>COPY</command>) of a transaction has been executed. |
||||
</para> |
||||
|
||||
<para> |
||||
The isolation level of a transaction determines what data the |
||||
transaction can see when other transactions are running concurrently. |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>READ COMMITTED</term> |
||||
<listitem> |
||||
<para> |
||||
A statement can only see rows committed before it began. This |
||||
is the default. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>SERIALIZABLE</term> |
||||
<listitem> |
||||
<para> |
||||
The current transaction can only see rows committed before |
||||
first DML statement was executed in this transaction. |
||||
</para> |
||||
<tip> |
||||
<para> |
||||
Intuitively, serializable means that two concurrent |
||||
transactions will leave the database in the same state as if |
||||
the two has been executed strictly after one another in either |
||||
order. |
||||
</para> |
||||
</tip> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
</refsect1> |
||||
|
||||
<refsect1> |
||||
<title>Compatibility</title> |
||||
|
||||
<para> |
||||
SQL92, SQL99 |
||||
</para> |
||||
|
||||
<para> |
||||
SERIALIZABLE is the default level in <acronym>SQL</acronym>. |
||||
Postgres does not provide the isolation levels <option>READ |
||||
UNCOMMITTED</option> and <option>REPEATABLE READ</option>. Because |
||||
of multi-version concurrency control, the serializable level is not |
||||
truly serializable. See the <citetitle>User's Guide</citetitle> for |
||||
details. |
||||
</para> |
||||
|
||||
<para> |
||||
In <acronym>SQL</acronym> there are two other transaction |
||||
characteristics that can be set with this command: whether the |
||||
transaction is read-only and the size of the diagnostics area. |
||||
Neither of these concepts are supported in Postgres. |
||||
</para> |
||||
</refsect1> |
||||
</refentry> |
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,627 +0,0 @@ |
||||
<!-- |
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/security.sgml,v 1.9 2000/05/25 15:32:03 momjian Exp $ |
||||
--> |
||||
|
||||
<chapter id="security"> |
||||
<Title>Security</Title> |
||||
|
||||
<Para> |
||||
Database security is addressed at several levels: |
||||
|
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
Data base file protection. All files stored within the database |
||||
are protected from reading by any account other than the |
||||
<productname>Postgres</productname> superuser account. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Connections from a client to the database server are, by |
||||
default, allowed only via a local Unix socket, not via TCP/IP |
||||
sockets. The backend must be started with the |
||||
<literal>-i</literal> option to allow non-local clients to connect. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Client connections can be restricted by IP address and/or user |
||||
name via the <filename>pg_hba.conf</filename> file in <envar>PG_DATA</envar>. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Client connections may be authenticated via other external packages. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Each user in <productname>Postgres</productname> is assigned a |
||||
username and (optionally) a password. By default, users do not |
||||
have write access to databases they did not create. |
||||
</para> |
||||
</listitem> |
||||
<listitem> |
||||
<para> |
||||
Users may be assigned to <firstterm>groups</firstterm>, and |
||||
table access may be restricted based on group privileges. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</para> |
||||
|
||||
<Sect1> |
||||
<Title>User Authentication</Title> |
||||
|
||||
<Para> |
||||
<firstterm>Authentication</firstterm> |
||||
is the process by which the backend server and |
||||
<application>postmaster</application> |
||||
ensure that the user requesting access to data is in fact who he/she |
||||
claims to be. |
||||
All users who invoke <Productname>Postgres</Productname> are checked against the |
||||
contents of the <literal>pg_user</literal> class to ensure that they are |
||||
authorized to do so. However, verification of the user's actual |
||||
identity is performed in a variety of ways: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
From the user shell |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
A backend server started from a user shell notes the user's (effective) |
||||
user-id before performing a |
||||
<function>setuid</function> |
||||
to the user-id of user <replaceable>postgres</replaceable>. |
||||
The effective user-id is used |
||||
as the basis for access control checks. No other authentication is |
||||
conducted. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
From the network |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
If the <Productname>Postgres</Productname> system is built as distributed, |
||||
access to the Internet TCP port of the |
||||
<application>postmaster</application> |
||||
process is available to anyone. The DBA configures the pg_hba.conf file |
||||
in the PGDATA directory to specify what authentication system is to be used |
||||
according to the host making the connection and which database it is |
||||
connecting to. See <citetitle>pg_hba.conf(5)</citetitle> |
||||
for a description of the authentication |
||||
systems available. Of course, host-based authentication is not fool-proof in |
||||
Unix, either. It is possible for determined intruders to also |
||||
masquerade the origination host. Those security issues are beyond the |
||||
scope of <Productname>Postgres</Productname>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
|
||||
<Sect2> |
||||
<Title>Host-Based Access Control</Title> |
||||
|
||||
<Para> |
||||
<firstterm>Host-based access control</firstterm> |
||||
is the name for the basic controls PostgreSQL |
||||
exercises on what clients are allowed to access a database and how |
||||
the users on those clients must authenticate themselves. |
||||
</para> |
||||
|
||||
<para> |
||||
Each database system contains a file named |
||||
<filename>pg_hba.conf</filename>, in its <envar>PGDATA</envar> |
||||
directory, which controls who can connect to each database. |
||||
</para> |
||||
|
||||
<para> |
||||
Every client accessing a database |
||||
<emphasis>must</emphasis> |
||||
be covered by one of |
||||
the entries in <filename>pg_hba.conf</filename>. |
||||
Otherwise all attempted connections from that |
||||
client will be rejected with a "User authentication failed" error |
||||
message. |
||||
</para> |
||||
|
||||
<para> |
||||
The general format of the <filename>pg_hba.conf</filename> |
||||
file is of a set of records, one per |
||||
line. Blank lines and lines beginning with a hash character |
||||
("#") are ignored. A record is |
||||
made up of a number of fields which are separated by spaces and/or tabs. |
||||
</para> |
||||
|
||||
<para> |
||||
Connections from clients can be made using Unix domain sockets or Internet |
||||
domain sockets (ie. TCP/IP). Connections made using Unix domain sockets |
||||
are controlled using records of the following format: |
||||
|
||||
<synopsis> |
||||
local <replaceable>database</replaceable> <replaceable>authentication method</replaceable> |
||||
</synopsis> |
||||
|
||||
where |
||||
|
||||
<simplelist> |
||||
<member> |
||||
<replaceable>database</replaceable> |
||||
specifies the database that this record applies to. The value |
||||
<literal>all</literal> |
||||
specifies that it applies to all databases. |
||||
</member> |
||||
<member> |
||||
<replaceable>authentication method</replaceable> |
||||
specifies the method a user must use to authenticate themselves when |
||||
connecting to that database using Unix domain sockets. The different methods |
||||
are described below. |
||||
</member> |
||||
</simplelist> |
||||
</para> |
||||
|
||||
<para> |
||||
Connections made using Internet domain sockets are controlled using records |
||||
of the following format. |
||||
|
||||
<synopsis> |
||||
host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceable> <replaceable>TCP/IP mask</replaceable> <replaceable>authentication method</replaceable> |
||||
</synopsis> |
||||
</para> |
||||
|
||||
<para> |
||||
The <replaceable>TCP/IP address</replaceable> |
||||
is logically anded to both the specified |
||||
<replaceable>TCP/IP mask</replaceable> |
||||
and the TCP/IP address |
||||
of the connecting client. |
||||
If the two resulting values are equal then the |
||||
record is used for this connection. If a connection matches more than one |
||||
record then the earliest one in the file is used. |
||||
Both the |
||||
<replaceable>TCP/IP address</replaceable> |
||||
and the |
||||
<replaceable>TCP/IP mask</replaceable> |
||||
are specified in dotted decimal notation. |
||||
</para> |
||||
|
||||
<para> |
||||
If a connection fails to match any record then the |
||||
<firstterm>reject</firstterm> |
||||
authentication method is applied (see below). |
||||
</para> |
||||
|
||||
<sect3> |
||||
<title>Authentication Methods</title> |
||||
|
||||
<para> |
||||
The following authentication methods are supported for both Unix and TCP/IP |
||||
domain sockets: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>trust</term> |
||||
<listitem> |
||||
<para> |
||||
The connection is allowed unconditionally. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>reject</term> |
||||
<listitem> |
||||
<para> |
||||
The connection is rejected unconditionally. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>crypt</term> |
||||
<listitem> |
||||
<para> |
||||
The client is asked for a password for the user. This is sent encrypted |
||||
(using <citetitle>crypt(3)</citetitle>) |
||||
and compared against the password held in the |
||||
<filename>pg_shadow</filename> table. |
||||
If the passwords match, the connection is allowed. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>password</term> |
||||
<listitem> |
||||
<para> |
||||
The client is asked for a password for the user. This is sent in clear |
||||
and compared against the password held in the |
||||
<filename>pg_shadow</filename> table. |
||||
If the passwords match, the connection is allowed. An optional password file |
||||
may be specified after the |
||||
<literal>password</literal> |
||||
keyword which is used to match the supplied password rather than the pg_shadow |
||||
table. See |
||||
<citerefentry><refentrytitle>pg_passwd</refentrytitle></citerefentry>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
|
||||
<para> |
||||
The following authentication methods are supported for TCP/IP |
||||
domain sockets only: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>krb4</term> |
||||
<listitem> |
||||
<para> |
||||
Kerberos V4 is used to authenticate the user. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>krb5</term> |
||||
<listitem> |
||||
<para> |
||||
Kerberos V5 is used to authenticate the user. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>ident</term> |
||||
<listitem> |
||||
<para> |
||||
The ident server on the client is used to authenticate the user (RFC 1413). |
||||
An optional map name may be specified after the |
||||
<literal>ident</literal> |
||||
keyword which allows ident user names to be mapped onto |
||||
<productname>Postgres</productname> user names. |
||||
Maps are held in the file |
||||
<filename>$<envar>PGDATA</envar>/pg_ident.conf</filename>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
</sect3> |
||||
|
||||
<sect3> |
||||
<title>Examples</title> |
||||
|
||||
<para> |
||||
<programlisting> |
||||
# Trust any connection via Unix domain sockets. |
||||
local trust |
||||
# Trust any connection via TCP/IP from this machine. |
||||
host all 127.0.0.1 255.255.255.255 trust |
||||
# We don't like this machine. |
||||
host all 192.168.0.10 255.255.255.0 reject |
||||
# This machine can't encrypt so we ask for passwords in clear. |
||||
host all 192.168.0.3 255.255.255.0 password |
||||
# The rest of this group of machines should provide encrypted passwords. |
||||
host all 192.168.0.0 255.255.255.0 crypt |
||||
</programlisting> |
||||
</para> |
||||
</sect3> |
||||
</sect2> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>User Names and Groups</title> |
||||
|
||||
<para> |
||||
To define a new user, run the |
||||
<application>createuser</application> utility program. |
||||
</para> |
||||
|
||||
<para> |
||||
To assign a user or set of users to a new group, one must |
||||
define the group itself, and assign users to that group. In |
||||
<application>Postgres</application> these steps are not currently |
||||
supported with a <command>create group</command> command. Instead, |
||||
the groups are defined by inserting appropriate values into the |
||||
<literal>pg_group</literal> system table, and then using the |
||||
<command>grant</command> command to assign privileges to the |
||||
group. |
||||
</para> |
||||
|
||||
<sect2> |
||||
<title>Creating Users</title> |
||||
|
||||
<para> |
||||
</para> |
||||
</sect2> |
||||
|
||||
<sect2> |
||||
<title>Creating Groups</title> |
||||
|
||||
<para> |
||||
Currently, there is no easy interface to set up user groups. You |
||||
have to explicitly insert/update the <literal>pg_group table</literal>. |
||||
For example: |
||||
|
||||
<programlisting> |
||||
jolly=> insert into pg_group (groname, grosysid, grolist) |
||||
jolly=> values ('posthackers', '1234', '{5443, 8261}'); |
||||
INSERT 548224 |
||||
jolly=> grant insert on foo to group posthackers; |
||||
CHANGE |
||||
jolly=> |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<para> |
||||
The fields in <filename>pg_group</filename> are: |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>groname</term> |
||||
<listitem> |
||||
<para> |
||||
The group name. This a name and should be purely |
||||
alphanumeric. Do not include underscores or other punctuation. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>grosysid</term> |
||||
<listitem> |
||||
<para> |
||||
The group id. This is an int4. This should be unique for |
||||
each group. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>grolist</term> |
||||
<listitem> |
||||
<para> |
||||
The list of pg_user id's that belong in the group. This |
||||
is an int4[]. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
</sect2> |
||||
|
||||
<sect2> |
||||
<title>Assigning Users to Groups</title> |
||||
|
||||
<para> |
||||
</para> |
||||
</sect2> |
||||
|
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Access Control</Title> |
||||
|
||||
<Para> |
||||
<Productname>Postgres</Productname> provides mechanisms to allow users |
||||
to limit the access to their data that is provided to other users. |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term> |
||||
Database superusers |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Database super-users (i.e., users who have <literal>pg_user.usesuper</literal> |
||||
set) silently bypass all of the access controls described below with |
||||
two exceptions: manual system catalog updates are not permitted if the |
||||
user does not have <literal>pg_user.usecatupd</literal> set, and destruction of |
||||
system catalogs (or modification of their schemas) is never allowed. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
Access Privilege |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
The use of access privilege to limit reading, writing and setting |
||||
of rules on classes is covered in |
||||
<citetitle>grant/revoke(l)</citetitle>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term> |
||||
Class removal and schema modification |
||||
</term> |
||||
<listitem> |
||||
<para> |
||||
Commands that destroy or modify the structure of an existing class, |
||||
such as <command>alter</command>, |
||||
<command>drop table</command>, |
||||
and |
||||
<command>drop index</command>, |
||||
only operate for the owner of the class. As mentioned above, these |
||||
operations are <emphasis>never</emphasis> |
||||
permitted on system catalogs. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
</para> |
||||
</sect1> |
||||
|
||||
<Sect1> |
||||
<Title>Functions and Rules</Title> |
||||
|
||||
<Para> |
||||
Functions and rules allow users to insert code into the backend server |
||||
that other users may execute without knowing it. Hence, both |
||||
mechanisms permit users to <firstterm>trojan horse</firstterm> |
||||
others with relative impunity. The only real protection is tight |
||||
control over who can define functions (e.g., write to relations with |
||||
SQL fields) and rules. Audit trails and alerters on |
||||
<literal>pg_class</literal>, <literal>pg_user</literal> |
||||
and <literal>pg_group</literal> are also recommended. |
||||
</para> |
||||
|
||||
<Sect2> |
||||
<Title>Functions</Title> |
||||
|
||||
<Para> |
||||
Functions written in any language except SQL |
||||
run inside the backend server |
||||
process with the permissions of the user <replaceable>postgres</replaceable> (the |
||||
backend server runs with its real and effective user-id set to |
||||
<replaceable>postgres</replaceable>. It is possible for users to change the server's |
||||
internal data structures from inside of trusted functions. Hence, |
||||
among many other things, such functions can circumvent any system |
||||
access controls. This is an inherent problem with user-defined C functions. |
||||
</para> |
||||
</sect2> |
||||
|
||||
<Sect2> |
||||
<Title>Rules</Title> |
||||
|
||||
<Para> |
||||
Like SQL functions, rules always run with the identity and |
||||
permissions of the user who invoked the backend server. |
||||
</para> |
||||
</sect2> |
||||
|
||||
<sect2> |
||||
<title>Caveats</title> |
||||
|
||||
<para> |
||||
There are no plans to explicitly support encrypted data inside of |
||||
<Productname>Postgres</Productname> |
||||
(though there is nothing to prevent users from encrypting |
||||
data within user-defined functions). There are no plans to explicitly |
||||
support encrypted network connections, either, pending a total rewrite |
||||
of the frontend/backend protocol. |
||||
</para> |
||||
<para> |
||||
User names, group names and associated system identifiers (e.g., the |
||||
contents of <literal>pg_user.usesysid</literal>) are assumed to be unique |
||||
throughout a database. Unpredictable results may occur if they are |
||||
not. |
||||
</para> |
||||
</sect2> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Secure TCP/IP Connection</title> |
||||
|
||||
<para> |
||||
<note> |
||||
<title>Author</title> |
||||
<para> |
||||
From e-mail by |
||||
<ulink url="selkovjr@mcs.anl.gov">Gene Selkov, Jr.</ulink> |
||||
written on 1999-09-08 in response to a |
||||
question from Eric Marsden. |
||||
</para> |
||||
</note> |
||||
</para> |
||||
|
||||
<para> |
||||
One can use <productname>ssh</productname> to encrypt the network |
||||
connection between clients and a |
||||
<productname>Postgres</productname> server. Done properly, this |
||||
should lead to an adequately secure network connection. |
||||
</para> |
||||
|
||||
<para> |
||||
The documentation for <productname>ssh</productname> provides most |
||||
of the information to get started. |
||||
Please refer to |
||||
<ulink url="http://www.heimhardt.de/htdocs/ssh.html">http://www.heimhardt.de/htdocs/ssh.html</ulink> |
||||
for better insight. |
||||
</para> |
||||
|
||||
<para> |
||||
A step-by-step explanation can be done in just two steps. |
||||
</para> |
||||
|
||||
<procedure> |
||||
<title>Running a secure tunnel via ssh</title> |
||||
|
||||
<para> |
||||
A step-by-step explanation can be done in just two steps. |
||||
</para> |
||||
|
||||
<step performance="required" id="establish-tunnel"> |
||||
<para> |
||||
Establish a tunnel to the backend machine, like this: |
||||
|
||||
<programlisting> |
||||
ssh -L 3333:wit.mcs.anl.gov:5432 postgres@wit.mcs.anl.gov |
||||
</programlisting> |
||||
|
||||
The first number in the -L argument, 3333, is the port number of |
||||
your end of the tunnel. The second number, 5432, is the remote |
||||
end of the tunnel -- the port number your backend is using. The |
||||
name or the address in between the port numbers belongs to the |
||||
server machine, as does the last argument to ssh that also includes |
||||
the optional user name. Without the user name, ssh will try the |
||||
name you are currently logged on as on the client machine. You can |
||||
use any user name the server machine will accept, not necessarily |
||||
those related to postgres. |
||||
</para> |
||||
</step> |
||||
|
||||
<step performance="required"> |
||||
<para> |
||||
Now that you have a running ssh session, you can connect a |
||||
postgres client to your local host at the port number you |
||||
specified in the previous step. If it's |
||||
<application>psql</application>, you will need another shell |
||||
because the shell session you used in |
||||
<xref linkend="establish-tunnel"> is now occupied with |
||||
<application>ssh</application>. |
||||
|
||||
<programlisting> |
||||
psql -h localhost -p 3333 -d mpw |
||||
</programlisting> |
||||
|
||||
Note that you have to specify the <option>-h</option> argument |
||||
to cause your client to use the TCP socket instead of the Unix |
||||
socket. You can omit the port argument if you chose 5432 as your |
||||
end of the tunnel. |
||||
</para> |
||||
</step> |
||||
</procedure> |
||||
</sect1> |
||||
</chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode:sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:("/usr/lib/sgml/catalog") |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
@ -1,266 +0,0 @@ |
||||
<chapter id="signals"> |
||||
<DocInfo> |
||||
<AuthorGroup> |
||||
<Author> |
||||
<FirstName>Massimo</FirstName> |
||||
<Surname>Dal Zotto</Surname> |
||||
</Author> |
||||
</AuthorGroup> |
||||
<Date>Transcribed 1998-10-16</Date> |
||||
</DocInfo> |
||||
|
||||
<title><productname>Postgres</productname> Signals</title> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
|
||||
<para> |
||||
<productname>Postgres</productname> uses the following signals for |
||||
communication between the postmaster and backends: |
||||
</para> |
||||
|
||||
<para> |
||||
<table tocentry="1"> |
||||
<title><productname>Postgres</productname> Signals</title> |
||||
<titleabbrev>Signals</titleabbrev> |
||||
|
||||
<tgroup cols="2"> |
||||
<thead> |
||||
<row> |
||||
<entry> |
||||
Signal |
||||
</entry> |
||||
<entry> |
||||
<application>postmaster</application> Action |
||||
</entry> |
||||
<entry> |
||||
Server Action |
||||
</entry> |
||||
</row> |
||||
</thead> |
||||
|
||||
<tbody> |
||||
<row> |
||||
<entry> |
||||
SIGHUP |
||||
</entry> |
||||
<entry> |
||||
kill(*,sighup) |
||||
</entry> |
||||
<entry> |
||||
read_pg_options |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGINT |
||||
</entry> |
||||
<entry> |
||||
die |
||||
</entry> |
||||
<entry> |
||||
cancel query |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGQUIT |
||||
</entry> |
||||
<entry> |
||||
kill(*,sigterm) |
||||
</entry> |
||||
<entry> |
||||
handle_warn |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGTERM |
||||
</entry> |
||||
<entry> |
||||
kill(*,sigterm), kill(*,9), die |
||||
</entry> |
||||
<entry> |
||||
die |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGPIPE |
||||
</entry> |
||||
<entry> |
||||
ignored |
||||
</entry> |
||||
<entry> |
||||
die |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGUSR1 |
||||
</entry> |
||||
<entry> |
||||
kill(*,sigusr1), die |
||||
</entry> |
||||
<entry> |
||||
quickdie |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGUSR2 |
||||
</entry> |
||||
<entry> |
||||
kill(*,sigusr2) |
||||
</entry> |
||||
<entry> |
||||
async notify (SI flush) |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGCHLD |
||||
</entry> |
||||
<entry> |
||||
reaper |
||||
</entry> |
||||
<entry> |
||||
ignored (alive test) |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGTTIN |
||||
</entry> |
||||
<entry> |
||||
ignored |
||||
</entry> |
||||
<entry> |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGTTOU |
||||
</entry> |
||||
<entry> |
||||
ignored |
||||
</entry> |
||||
<entry> |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGCONT |
||||
</entry> |
||||
<entry> |
||||
dumpstatus |
||||
</entry> |
||||
<entry> |
||||
</entry> |
||||
</row> |
||||
|
||||
<row> |
||||
<entry> |
||||
SIGFPE |
||||
</entry> |
||||
<entry> |
||||
</entry> |
||||
<entry> |
||||
FloatExceptionHandler |
||||
</entry> |
||||
</row> |
||||
|
||||
</tbody> |
||||
</tgroup> |
||||
</table> |
||||
|
||||
<note> |
||||
<para> |
||||
"<literal>kill(*,signal)</literal>" means sending a signal to all backends. |
||||
</para> |
||||
</note> |
||||
</para> |
||||
|
||||
<para> |
||||
The main changes to the old signal handling are the use of SIGQUIT instead |
||||
of SIGHUP to handle warns, SIGHUP to re-read the pg_options file and the |
||||
redirection to all active backends of SIGHUP, SIGTERM, SIGUSR1 and SIGUSR2 |
||||
sent to the postmaster. |
||||
In this way these signals sent to the postmaster can be sent |
||||
automatically to all the backends without need to know their pids. |
||||
To shut down postgres one needs only to send a SIGTERM to postmaster |
||||
and it will stop automatically all the backends. |
||||
</para> |
||||
|
||||
<para> |
||||
The SIGUSR2 signal is also used to prevent SI cache table overflow |
||||
which happens when some backend doesn't process SI cache for a long period. |
||||
When a backend detects the SI table full at 70% it simply sends a signal |
||||
to the postmaster which will wake up all idle backends and make them flush |
||||
the cache. |
||||
</para> |
||||
|
||||
<para> |
||||
The typical use of signals by programmers could be the following: |
||||
|
||||
<programlisting> |
||||
# stop postgres |
||||
kill -TERM $postmaster_pid |
||||
</programlisting> |
||||
|
||||
<programlisting> |
||||
# kill all the backends |
||||
kill -QUIT $postmaster_pid |
||||
</programlisting> |
||||
|
||||
<programlisting> |
||||
# kill only the postmaster |
||||
kill -INT $postmaster_pid |
||||
</programlisting> |
||||
|
||||
<programlisting> |
||||
# change pg_options |
||||
cat new_pg_options > $DATA_DIR/pg_options |
||||
kill -HUP $postmaster_pid |
||||
</programlisting> |
||||
|
||||
<programlisting> |
||||
# change pg_options only for a backend |
||||
cat new_pg_options > $DATA_DIR/pg_options |
||||
kill -HUP $backend_pid |
||||
cat old_pg_options > $DATA_DIR/pg_options |
||||
</programlisting> |
||||
</para> |
||||
</chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode:sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:("/usr/lib/sgml/catalog") |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
@ -1,289 +0,0 @@ |
||||
<!-- |
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/trouble.sgml,v 2.6 2000/04/08 23:32:34 tgl Exp $ |
||||
--> |
||||
|
||||
<Chapter Id="trouble"> |
||||
<Title>Troubleshooting</Title> |
||||
|
||||
<sect1> |
||||
<title>Postmaster Startup Failures</title> |
||||
|
||||
<para> |
||||
There are several common reasons for the postmaster to fail to start up. |
||||
Check the postmaster's log file, or start it by hand (without redirecting |
||||
standard output or standard error) to see what complaint messages appear. |
||||
Some of the possible error messages are reasonably self-explanatory, |
||||
but here are some that are not: |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
FATAL: StreamServerPort: bind() failed: Address already in use |
||||
Is another postmaster already running on that port? |
||||
</ProgramListing> |
||||
This usually means just what it suggests: you accidentally started a |
||||
second postmaster on the same port where one is already running. |
||||
However, if the kernel error |
||||
message is not "Address already in use" or some variant of that wording, |
||||
there may be a different problem. For example, trying to start a |
||||
postmaster on a reserved port number may draw something like |
||||
<ProgramListing> |
||||
$ postmaster -i -p 666 |
||||
FATAL: StreamServerPort: bind() failed: Permission denied |
||||
Is another postmaster already running on that port? |
||||
</ProgramListing> |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
IpcMemoryCreate: shmget failed (Invalid argument) key=5440001, size=83918612, permission=600 |
||||
FATAL 1: ShmemCreate: cannot create region |
||||
</ProgramListing> |
||||
A message like this probably means that your kernel's limit on the size |
||||
of shared memory areas is smaller than the buffer area that Postgres |
||||
is trying to create. (Or it could mean that you don't have SysV-style |
||||
shared memory support configured into your kernel at all.) As a temporary |
||||
workaround, you can try starting the postmaster with a smaller-than-normal |
||||
number of buffers (-B switch). You will eventually want to reconfigure |
||||
your kernel to increase the allowed shared memory size, however. |
||||
You may see this message when trying to start multiple postmasters on |
||||
the same machine, if their total space requests exceed the kernel limit. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
IpcSemaphoreCreate: semget failed (No space left on device) key=5440026, num=16, permission=600 |
||||
</ProgramListing> |
||||
A message like this does <emphasis>not</emphasis> mean that you've run out |
||||
of disk space; it means that your kernel's limit on the number of SysV |
||||
semaphores is smaller than the number Postgres wants to create. As above, |
||||
you may be able to work around the problem by starting the postmaster with |
||||
a reduced number of backend processes (-N switch), but you'll eventually |
||||
want to increase the kernel limit. |
||||
</para> |
||||
|
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Client Connection Problems</title> |
||||
|
||||
<para> |
||||
Once you have a running postmaster, trying to connect to it with |
||||
client applications can fail for a variety of reasons. The sample |
||||
error messages shown here are for clients based on recent versions |
||||
of libpq --- clients based on other interface libraries may produce |
||||
other messages with more or less information. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
connectDB() -- connect() failed: Connection refused |
||||
Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'? |
||||
</ProgramListing> |
||||
This is the generic "I couldn't find a postmaster to talk to" failure. |
||||
It looks like the above when TCP/IP communication is attempted, or like |
||||
this when attempting Unix-socket communication to a local postmaster: |
||||
<ProgramListing> |
||||
connectDB() -- connect() failed: No such file or directory |
||||
Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'? |
||||
</ProgramListing> |
||||
The last line is useful in verifying that the client is trying to connect |
||||
where it is supposed to. If there is in fact no postmaster |
||||
running there, the kernel error message will typically be either |
||||
"Connection refused" or "No such file or directory", as illustrated. |
||||
(It is particularly important to realize that "Connection refused" in |
||||
this context does <emphasis>not</emphasis> mean that the postmaster |
||||
got your connection request and rejected it --- that case will produce |
||||
a different message, as shown below.) |
||||
Other error messages such as "Connection timed out" may indicate more |
||||
fundamental problems, like lack of network connectivity. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb |
||||
</ProgramListing> |
||||
This is what you are most likely to get if you succeed in contacting |
||||
a postmaster, but it doesn't want to talk to you. As the message |
||||
suggests, the postmaster refused the connection request because it |
||||
found no authorizing entry in its pg_hba.conf configuration file. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
Password authentication failed for user 'joeblow' |
||||
</ProgramListing> |
||||
Messages like this indicate that you contacted the postmaster, and it's |
||||
willing to talk to you, but not until you pass the authorization method |
||||
specified in the pg_hba.conf file. Check the password you're providing, |
||||
or check your Kerberos or IDENT software if the complaint mentions |
||||
one of those authentication types. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow' |
||||
</ProgramListing> |
||||
This is another variant of authentication failure: no Postgres create_user |
||||
command has been executed for the given username. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
FATAL 1: Database testdb does not exist in pg_database |
||||
</ProgramListing> |
||||
There's no database by that name under the control of this postmaster. |
||||
Note that if you don't specify a database name, it defaults to your |
||||
Postgres username, which may or may not be the right thing. |
||||
</para> |
||||
|
||||
<para> |
||||
<ProgramListing> |
||||
NOTICE: Unrecognized variable client_encoding |
||||
</ProgramListing> |
||||
This isn't an error; in fact, it's quite harmless. You'll see this |
||||
message at startup if you use a client compiled with MULTIBYTE support |
||||
to connect to a server compiled without it. (The client is trying |
||||
to tell the server what character set encoding it wants, but the |
||||
server has no idea what it's talking about.) If the message bothers |
||||
you, use a client compiled with the same options as the server. |
||||
</para> |
||||
|
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Debugging Messages</title> |
||||
|
||||
<para> |
||||
The <Application>postmaster</Application> occasionally prints out |
||||
messages which |
||||
are often helpful during troubleshooting. If you wish |
||||
to view debugging messages from the <Application>postmaster</Application>, |
||||
you can |
||||
start it with the -d option and redirect the output to |
||||
the log file: |
||||
|
||||
<ProgramListing> |
||||
% postmaster -d > pm.log 2>&1 & |
||||
</ProgramListing> |
||||
|
||||
If you do not wish to see these messages, you can type |
||||
<ProgramListing> |
||||
% postmaster -S |
||||
</ProgramListing> |
||||
and the <Application>postmaster</Application> will be "S"ilent. |
||||
No ampersand ("&") is required in this case, since the postmaster |
||||
automatically detaches from the terminal when -S is specified. |
||||
</Para> |
||||
|
||||
<sect2 Id="pg-options-trouble"> |
||||
<Title>pg_options</Title> |
||||
|
||||
<Para> |
||||
<Note> |
||||
<Para> |
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink> |
||||
</Para> |
||||
</Note> |
||||
</para> |
||||
<Para> |
||||
The optional file <filename>data/pg_options</filename> contains runtime |
||||
options used by the backend to control trace messages and other backend |
||||
tunable parameters. |
||||
What makes this file interesting is the fact that it is re-read by a backend |
||||
when it receives a SIGHUP signal, making thus possible to change run-time |
||||
options on the fly without needing to restart |
||||
<productname>Postgres</productname>. |
||||
The options specified in this file may be debugging flags used by the trace |
||||
package (<filename>backend/utils/misc/trace.c</filename>) or numeric |
||||
parameters which can be used by the backend to control its behaviour. |
||||
New options and parameters must be defined in |
||||
<filename>backend/utils/misc/trace.c</filename> and |
||||
<filename>backend/include/utils/trace.h</filename>. |
||||
</para> |
||||
|
||||
<para> |
||||
pg_options can also be specified with the <option>-T</option> switch of |
||||
<productname>Postgres</productname>: |
||||
|
||||
<programlisting> |
||||
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-" |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<Para> |
||||
The functions used for printing errors and debug messages can now make use |
||||
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout |
||||
or stderr are prefixed by a timestamp containing also the backend pid: |
||||
|
||||
<programlisting> |
||||
#timestamp #pid #message |
||||
980127.17:52:14.173 [29271] StartTransactionCommand |
||||
980127.17:52:14.174 [29271] ProcessUtility: drop table t; |
||||
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full |
||||
980127.17:52:14.186 [29286] Async_NotifyHandler |
||||
980127.17:52:14.186 [29286] Waking up sleeping backend process |
||||
980127.19:52:14.292 [29286] Async_NotifyFrontEnd |
||||
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done |
||||
980127.19:52:14.466 [29286] Async_NotifyHandler done |
||||
</programlisting> |
||||
</para> |
||||
|
||||
<para> |
||||
This format improves readability of the logs and allows people to understand |
||||
exactly which backend is doing what and at which time. It also makes |
||||
easier to write simple awk or perl scripts which monitor the log to |
||||
detect database errors or problem, or to compute transaction time statistics. |
||||
</para> |
||||
|
||||
<para> |
||||
Messages printed to syslog use the log facility LOG_LOCAL0. |
||||
The use of syslog can be controlled with the syslog pg_option. |
||||
Unfortunately many functions call directly <function>printf()</function> |
||||
to print their messages to stdout or stderr and this output can't be |
||||
redirected to syslog or have timestamps in it. |
||||
It would be advisable that all calls to printf would be replaced with the |
||||
PRINTF macro and output to stderr be changed to use EPRINTF instead so that |
||||
we can control all output in a uniform way. |
||||
</Para> |
||||
|
||||
<para> |
||||
The format of the <filename>pg_options</filename> file is as follows: |
||||
|
||||
<programlisting> |
||||
# <replaceable>comment</replaceable> |
||||
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable> |
||||
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1 |
||||
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0 |
||||
</programlisting> |
||||
|
||||
Note that <replaceable class="parameter">keyword</replaceable> can also be |
||||
an abbreviation of the option name defined in |
||||
<filename>backend/utils/misc/trace.c</filename>. |
||||
</Para> |
||||
|
||||
<Para> |
||||
Refer to <xref linkend="pg-options-title" endterm="pg-options-title"> |
||||
for a complete list of option keywords and possible values. |
||||
</para> |
||||
</sect2> |
||||
</sect1> |
||||
</Chapter> |
||||
|
||||
<!-- Keep this comment at the end of the file |
||||
Local variables: |
||||
mode:sgml |
||||
sgml-omittag:nil |
||||
sgml-shorttag:t |
||||
sgml-minimize-attributes:nil |
||||
sgml-always-quote-attributes:t |
||||
sgml-indent-step:1 |
||||
sgml-indent-data:t |
||||
sgml-parent-document:nil |
||||
sgml-default-dtd-file:"./reference.ced" |
||||
sgml-exposed-tags:nil |
||||
sgml-local-catalogs:("/usr/lib/sgml/catalog") |
||||
sgml-local-ecat-files:nil |
||||
End: |
||||
--> |
||||
@ -0,0 +1,202 @@ |
||||
<Chapter id="user-manag"> |
||||
<title>Database User and Permission Management</title> |
||||
|
||||
<para> |
||||
Managing database users and their privileges is in concept similar |
||||
to that of Unix operating systems, but then again not identical |
||||
enough to not warrant explanation. |
||||
</para> |
||||
|
||||
<sect1> |
||||
<title>Database Users</title> |
||||
|
||||
<para> |
||||
Database users are conceptually completely separate from any |
||||
operating system users. In practice it might be convenient to |
||||
maintain a correspondence, but this is not required. Database user |
||||
names are global across a database cluster installation (and not |
||||
per individual database). To create a user use the <command>CREATE |
||||
USER</command> SQL command: |
||||
<synopsis> |
||||
CREATE USER <replaceable>name</replaceable> |
||||
</synopsis> |
||||
<replaceable>name</replaceable> follows the rules for SQL |
||||
identifiers: either unadorned without special characters, or |
||||
double-quoted. To remove an existing user, use the analog |
||||
<command>DROP USER</command> command. |
||||
</para> |
||||
|
||||
<para> |
||||
For convenience, the shell scripts <filename>createuser</filename> |
||||
and <filename>dropuser</filename> are wrappers around these SQL |
||||
commands. |
||||
</para> |
||||
|
||||
<para> |
||||
In order to bootstrap the database system, a freshly initialized |
||||
system always contains one predefined user. This user will have |
||||
the same name as the operating system user that initialized the |
||||
area (and is presumably being used as the user that runs the |
||||
server). Thus, often an initial user <quote>postgres</quote> |
||||
exists. In order to create more users you have to first connect as |
||||
this initial user. |
||||
</para> |
||||
|
||||
<para> |
||||
The user name to use for a particular database connection is |
||||
indicated by the client that is initiating the connection request |
||||
in an application-specific fashion. For example, the |
||||
<command>psql</command> program uses the <option>-U</option> |
||||
command line option to indicate the user to connect as. The set of |
||||
database users a given client connection may connect as is |
||||
determined by the client authentication setup, as explained in |
||||
<xref linkend="client-authentication">. (Thus, a client is not |
||||
necessarily limited to connect as the user with the same name as |
||||
its operating system user in the same way a person is not |
||||
constrained in its login name by her real name.) |
||||
</para> |
||||
|
||||
<sect2> |
||||
<title>User attributes</title> |
||||
|
||||
<para> |
||||
A database user may have a number of attributes that define its |
||||
privileges and interact with the client authentication system. |
||||
|
||||
<variablelist> |
||||
<varlistentry> |
||||
<term>superuser</term> |
||||
<listitem> |
||||
<para> |
||||
A database superuser bypasses all permission checks. Also, |
||||
only a superuser can create new users. To create a database |
||||
superuser, use <literal>CREATE USER name |
||||
CREATEUSER</literal>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>database creation</term> |
||||
<listitem> |
||||
<para> |
||||
A user must be explicitly given permission to create databases |
||||
(except for superusers, since those bypass all permission |
||||
checks). To create such a user, use <literal>CREATE USER name |
||||
CREATEDB</literal>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
|
||||
<varlistentry> |
||||
<term>password</term> |
||||
<listitem> |
||||
<para> |
||||
A password is only significant if password authentication is |
||||
used for client authentication. Database passwords a separate |
||||
from any operating system passwords. Specify a password upon |
||||
user creating as in <literal>CREATE USER name WITH PASSWORD |
||||
'string'</literal>. |
||||
</para> |
||||
</listitem> |
||||
</varlistentry> |
||||
</variablelist> |
||||
|
||||
See the reference pages for <command>CREATE USER</command> and |
||||
<command>ALTER USER</command> for details. |
||||
</para> |
||||
</sect2> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Groups</title> |
||||
|
||||
<para> |
||||
As in Unix, groups are a way of logically grouping users. To create |
||||
a group, use |
||||
<synopsis> |
||||
CREATE GROUP <replaceable>name</replaceable> |
||||
</synopsis> |
||||
To add users to or remove users from a group, respectively, user |
||||
<synopsis> |
||||
ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ... |
||||
ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ... |
||||
</synopsis> |
||||
</para> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Privileges</title> |
||||
|
||||
<para> |
||||
When a database object is created, it is assigned an owner. The |
||||
owner is the user that executed the creation statement. There is |
||||
currenty no polished interface for changing the owner of a database |
||||
object. By default, only an owner (or a superuser) can do anything |
||||
with the object. In order to allow other users to use it, |
||||
<firstterm>privileges</firstterm> must be granted. |
||||
</para> |
||||
|
||||
<para> |
||||
Currently, there are four different privileges: select (read), |
||||
insert (append), and update/delete (write), as well as |
||||
<literal>RULE</literal>, the permission to create a rewrite rule on |
||||
a table. The right to modify or destroy an object is always the |
||||
privilege of the owner only. To assign privileges, the |
||||
<command>GRANT</command> command is used. So, if |
||||
<literal>joe</literal> is an existing user, and |
||||
<literal>accounts</literal> is an existing table, write access can |
||||
be granted with |
||||
<programlisting> |
||||
GRANT UPDATE ON accounts TO joe; |
||||
</programlisting> |
||||
The user executing this command must be the owner of the table. To |
||||
grant a privilege to a group, use |
||||
<programlisting> |
||||
GRANT SELECT ON accounts TO GROUP staff; |
||||
</programlisting> |
||||
The special <quote>user</quote> name <literal>PUBLIC</literal> can |
||||
be used to grant a privilege to every user on the system. Using |
||||
<literal>ALL</literal> in place of a privilege specifies that all |
||||
privileges will be granted. |
||||
</para> |
||||
|
||||
<para> |
||||
To revoke a privilege, use the fittingly named |
||||
<command>REVOKE</command> command: |
||||
<programlisting> |
||||
REVOKE ALL ON accounts FROM PUBLIC; |
||||
</programlisting> |
||||
The set of privileges held by the table owner is always implicit |
||||
and is never revokable. |
||||
</para> |
||||
</sect1> |
||||
|
||||
<sect1> |
||||
<title>Functions and Triggers</title> |
||||
|
||||
<para> |
||||
Functions and triggers allow users to insert code into the backend |
||||
server that other users may execute without knowing it. Hence, both |
||||
mechanisms permit users to <firstterm>trojan horse</firstterm> |
||||
others with relative impunity. The only real protection is tight |
||||
control over who can define functions (e.g., write to relations |
||||
with SQL fields) and triggers. Audit trails and alerters on the |
||||
system catalogs <literal>pg_class</literal>, |
||||
<literal>pg_user</literal> and <literal>pg_group</literal> are also |
||||
possible. |
||||
</para> |
||||
|
||||
<para> |
||||
Functions written in any language except SQL run inside the backend |
||||
server process with the operating systems permissions of the |
||||
database server daemon process. It is possible to change the |
||||
server's internal data structures from inside of trusted functions. |
||||
Hence, among many other things, such functions can circumvent any |
||||
system access controls. This is an inherent problem with |
||||
user-defined C functions. |
||||
</para> |
||||
|
||||
</sect1> |
||||
|
||||
</Chapter> |
||||
Loading…
Reference in new issue