Separated set constraints and set transaction reference pages, revised set
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.
This commit is contained in:
parent
b4e906f191
commit
2c0edb3c86
19 changed files with 2259 additions and 3186 deletions
|
@ -8,7 +8,7 @@
|
|||
#
|
||||
#
|
||||
# IDENTIFICATION
|
||||
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.14 2000/05/02 20:01:51 thomas Exp $
|
||||
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.15 2000/06/18 21:24:51 petere Exp $
|
||||
#
|
||||
#----------------------------------------------------------------------------
|
||||
|
||||
|
@ -104,7 +104,7 @@ COMMANDS= abort.sgml alter_group.sgml alter_table.sgml alter_user.sgml \
|
|||
insert.sgml listen.sgml load.sgml lock.sgml move.sgml \
|
||||
notify.sgml \
|
||||
reindex.sgml reset.sgml revoke.sgml rollback.sgml \
|
||||
select.sgml select_into.sgml set.sgml show.sgml \
|
||||
select.sgml select_into.sgml set.sgml set_constraints.sgml set_transaction.sgml show.sgml \
|
||||
truncate.sgml unlisten.sgml update.sgml vacuum.sgml
|
||||
|
||||
FUNCTIONS= current_date.sgml current_time.sgml current_timestamp.sgml current_user.sgml
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.22 2000/05/02 20:01:51 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.23 2000/06/18 21:24:51 petere Exp $
|
||||
|
||||
Postgres Administrator's Guide.
|
||||
Derived from postgres.sgml.
|
||||
|
@ -27,7 +27,8 @@ Derived from postgres.sgml.
|
|||
<!entity regress SYSTEM "regress.sgml">
|
||||
<!entity release SYSTEM "release.sgml">
|
||||
<!entity runtime SYSTEM "runtime.sgml">
|
||||
<!entity security SYSTEM "security.sgml">
|
||||
<!entity client-auth SYSTEM "client-auth.sgml">
|
||||
<!entity user-manag SYSTEM "user-manag.sgml">
|
||||
<!entity start-ag SYSTEM "start-ag.sgml">
|
||||
<!entity trouble SYSTEM "trouble.sgml">
|
||||
|
||||
|
@ -111,10 +112,10 @@ Your name here...
|
|||
&install;
|
||||
&installw;
|
||||
&runtime;
|
||||
&security;
|
||||
&client-auth;
|
||||
&user-manag;
|
||||
&start-ag;
|
||||
&manage-ag;
|
||||
&trouble;
|
||||
&recovery;
|
||||
®ress;
|
||||
&release;
|
||||
|
|
502
doc/src/sgml/client-auth.sgml
Normal file
502
doc/src/sgml/client-auth.sgml
Normal file
|
@ -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:
|
||||
-->
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.37 2000/06/18 21:24:51 petere Exp $
|
||||
-->
|
||||
|
||||
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
|
||||
|
@ -58,9 +58,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th
|
|||
<!entity regress SYSTEM "regress.sgml">
|
||||
<!entity release SYSTEM "release.sgml">
|
||||
<!entity runtime SYSTEM "runtime.sgml">
|
||||
<!entity security SYSTEM "security.sgml">
|
||||
<!entity client-auth SYSTEM "client-auth.sgml">
|
||||
<!entity user-manag SYSTEM "user-manag.sgml">
|
||||
<!entity start-ag SYSTEM "start-ag.sgml">
|
||||
<!entity trouble SYSTEM "trouble.sgml">
|
||||
|
||||
<!-- programmer's guide -->
|
||||
<!entity arch-pg SYSTEM "arch-pg.sgml">
|
||||
|
@ -100,10 +100,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th
|
|||
<!entity docguide SYSTEM "docguide.sgml">
|
||||
<!entity geqo SYSTEM "geqo.sgml">
|
||||
<!entity index SYSTEM "index.sgml">
|
||||
<!entity options SYSTEM "pg_options.sgml">
|
||||
<!entity page SYSTEM "page.sgml">
|
||||
<!entity protocol SYSTEM "protocol.sgml">
|
||||
<!entity signals SYSTEM "signals.sgml">
|
||||
<!entity sources SYSTEM "sources.sgml">
|
||||
]>
|
||||
<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc -->
|
||||
|
@ -225,10 +223,10 @@ Your name here...
|
|||
&install;
|
||||
&installw;
|
||||
&runtime;
|
||||
&security;
|
||||
&client-auth;
|
||||
&user-manag;
|
||||
&start-ag;
|
||||
&manage-ag;
|
||||
&trouble;
|
||||
&recovery;
|
||||
®ress;
|
||||
&release;
|
||||
|
@ -292,7 +290,6 @@ Your name here...
|
|||
</partintro>
|
||||
&sources;
|
||||
&arch-dev;
|
||||
&options;
|
||||
&geqo;
|
||||
<!--
|
||||
This listing of Postgres catalogs is currently just a copy of the old
|
||||
|
@ -301,7 +298,6 @@ Your name here...
|
|||
&catalogs;
|
||||
-->
|
||||
&protocol;
|
||||
&signals;
|
||||
&compiler;
|
||||
&bki;
|
||||
&page;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.26 2000/05/02 20:01:52 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.27 2000/06/18 21:24:51 petere Exp $
|
||||
|
||||
Postgres Programmer's Guide.
|
||||
-->
|
||||
|
@ -50,10 +50,8 @@ Postgres Programmer's Guide.
|
|||
<!entity cvs SYSTEM "cvs.sgml">
|
||||
<!entity docguide SYSTEM "docguide.sgml">
|
||||
<!entity geqo SYSTEM "geqo.sgml">
|
||||
<!entity options SYSTEM "pg_options.sgml">
|
||||
<!entity page SYSTEM "page.sgml">
|
||||
<!entity protocol SYSTEM "protocol.sgml">
|
||||
<!entity signals SYSTEM "signals.sgml">
|
||||
<!entity sources SYSTEM "sources.sgml">
|
||||
]>
|
||||
|
||||
|
@ -165,7 +163,6 @@ Disable it until we put in some info.
|
|||
|
||||
&sources;
|
||||
&arch-dev;
|
||||
&options;
|
||||
&geqo;
|
||||
<!--
|
||||
This listing of Postgres catalogs is currently just a copy of the old
|
||||
|
@ -174,7 +171,6 @@ Disable it until we put in some info.
|
|||
&catalogs;
|
||||
-->
|
||||
&protocol;
|
||||
&signals;
|
||||
&compiler;
|
||||
&bki;
|
||||
&page;
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.18 2000/04/14 15:17:28 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.19 2000/06/18 21:24:51 petere Exp $
|
||||
Postgres documentation
|
||||
Complete list of usable sgml source files in this directory.
|
||||
-->
|
||||
|
@ -98,6 +98,8 @@ Complete list of usable sgml source files in this directory.
|
|||
<!entity select system "select.sgml">
|
||||
<!entity selectInto system "select_into.sgml">
|
||||
<!entity set system "set.sgml">
|
||||
<!entity setConstraints system "set_constraints.sgml">
|
||||
<!entity setTransaction system "set_transaction.sgml">
|
||||
<!entity show system "show.sgml">
|
||||
<!entity truncate system "truncate.sgml">
|
||||
<!entity unlisten system "unlisten.sgml">
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/commands.sgml,v 1.25 2000/04/14 15:17:28 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/commands.sgml,v 1.26 2000/06/18 21:24:51 petere Exp $
|
||||
Postgres documentation
|
||||
-->
|
||||
|
||||
|
@ -72,6 +72,8 @@ Postgres documentation
|
|||
&select;
|
||||
&selectInto;
|
||||
&set;
|
||||
&setConstraints;
|
||||
&setTransaction;
|
||||
&show;
|
||||
&truncate;
|
||||
&unlisten;
|
||||
|
|
|
@ -1,47 +1,32 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.8 2000/04/08 02:39:02 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.9 2000/06/18 21:24:51 petere Exp $
|
||||
Postgres documentation
|
||||
-->
|
||||
|
||||
<refentry id="SQL-RESET">
|
||||
<refmeta>
|
||||
<refentrytitle id="SQL-RESET-TITLE">
|
||||
RESET
|
||||
</refentrytitle>
|
||||
<refentrytitle id="SQL-RESET-TITLE">RESET</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>
|
||||
RESET
|
||||
</refname>
|
||||
<refpurpose>
|
||||
Restores run-time parameters for session to default values
|
||||
</refpurpose>
|
||||
<refname>RESET</refname>
|
||||
<refpurpose>Restores run-time parameters to default values</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
RESET <replaceable class="PARAMETER">variable</replaceable>
|
||||
</synopsis>
|
||||
|
||||
<refsect2 id="R2-SQL-RESET-1">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Inputs
|
||||
</title>
|
||||
<title>Inputs</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">variable</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Refer to
|
||||
<xref linkend="sql-set-title" endterm="sql-set-title">
|
||||
for more information on available variables.
|
||||
The name of a run-time parameter. See <xref
|
||||
linkend="sql-set-title" endterm="sql-set-title"> for a list.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -49,107 +34,55 @@ RESET <replaceable class="PARAMETER">variable</replaceable>
|
|||
</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2 id="R2-SQL-RESET-2">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Outputs
|
||||
</title>
|
||||
<para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><computeroutput>
|
||||
RESET VARIABLE
|
||||
</computeroutput></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Message returned if
|
||||
<replaceable class="PARAMETER">variable</replaceable> is successfully reset
|
||||
to its default value.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-RESET-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para>
|
||||
<command>RESET</command> restores variables to their
|
||||
default values.
|
||||
Refer to
|
||||
<command>RESET</command> restores run-time parameters to their
|
||||
default values. Refer to
|
||||
<xref linkend="sql-set-title" endterm="sql-set-title">
|
||||
for details on allowed values and defaults.
|
||||
<command>RESET</command> is an alternate form for
|
||||
for details. <command>RESET</command> is an alternate form for
|
||||
|
||||
<synopsis>
|
||||
SET <replaceable class="parameter">variable</replaceable> = DEFAULT
|
||||
SET <replaceable class="parameter">variable</replaceable> TO DEFAULT
|
||||
</synopsis>
|
||||
</para>
|
||||
|
||||
<refsect2 id="R2-SQL-RESET-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</title>
|
||||
|
||||
<para>
|
||||
See also
|
||||
<xref linkend="sql-set-title" endterm="sql-set-title"> and
|
||||
<xref linkend="sql-show-title" endterm="sql-show-title">
|
||||
to manipulate variable values.
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-RESET-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
|
||||
<refsect1>
|
||||
<title>Diagnostics</title>
|
||||
<para>
|
||||
See under the <xref linkend="sql-set-title"
|
||||
endterm="sql-set-title"> command.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
<para>
|
||||
Set DateStyle to its default value:
|
||||
|
||||
<programlisting>
|
||||
<screen>
|
||||
RESET DateStyle;
|
||||
</programlisting>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Set Geqo to its default value:
|
||||
|
||||
<programlisting>
|
||||
<screen>
|
||||
RESET GEQO;
|
||||
</programlisting>
|
||||
</screen>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-RESET-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<refsect1>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-RESET-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>RESET</command> in <acronym>SQL92</acronym>.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
<command>RESET</command> is a <productname>Postgres</productname> extension.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
|
File diff suppressed because it is too large
Load diff
53
doc/src/sgml/ref/set_constraints.sgml
Normal file
53
doc/src/sgml/ref/set_constraints.sgml
Normal file
|
@ -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>
|
93
doc/src/sgml/ref/set_transaction.sgml
Normal file
93
doc/src/sgml/ref/set_transaction.sgml
Normal file
|
@ -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>
|
||||
|
|
@ -1,48 +1,34 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.9 2000/04/08 02:39:02 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.10 2000/06/18 21:24:54 petere Exp $
|
||||
Postgres documentation
|
||||
-->
|
||||
|
||||
<refentry id="SQL-SHOW">
|
||||
<refmeta>
|
||||
<refentrytitle id="SQL-SHOW-TITLE">
|
||||
SHOW
|
||||
</refentrytitle>
|
||||
<refentrytitle id="SQL-SHOW-TITLE">SHOW</refentrytitle>
|
||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>
|
||||
SHOW
|
||||
</refname>
|
||||
<refpurpose>
|
||||
Shows run-time parameters for session
|
||||
</refpurpose>
|
||||
<refname>SHOW</refname>
|
||||
<refpurpose>Shows run-time parameters</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<refsynopsisdivinfo>
|
||||
<date>1999-07-20</date>
|
||||
</refsynopsisdivinfo>
|
||||
<synopsis>
|
||||
SHOW <replaceable class="PARAMETER">keyword</replaceable>
|
||||
SHOW <replaceable class="PARAMETER">name</replaceable>
|
||||
</synopsis>
|
||||
|
||||
<refsect2 id="R2-SQL-SHOW-1">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Inputs
|
||||
</title>
|
||||
<title>Inputs</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><replaceable class="PARAMETER">keyword</replaceable></term>
|
||||
<term><replaceable class="PARAMETER">name</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Refer to
|
||||
The name of a run-time parameter. See
|
||||
<xref linkend="sql-set-title" endterm="sql-set-title">
|
||||
for more information on available variables.
|
||||
for a list.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -50,41 +36,43 @@ SHOW <replaceable class="PARAMETER">keyword</replaceable>
|
|||
</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2 id="R2-SQL-SHOW-2">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Outputs
|
||||
</title>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-SHOW-1">
|
||||
<title>Description</title>
|
||||
<para>
|
||||
<command>SHOW</command> will display the current setting of a
|
||||
run-time parameter. These variables can be set using the
|
||||
<command>SET</command> statement or are determined at server start.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Diagnostics</title>
|
||||
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><computeroutput>
|
||||
NOTICE: <replaceable class="PARAMETER">variable</replaceable> is <replaceable>value</replaceable>
|
||||
</computeroutput></term>
|
||||
<term><computeroutput>ERROR: not a valid option name: <replaceable>name</replaceable></computeroutput></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Message returned if successful.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><computeroutput>
|
||||
NOTICE: Unrecognized variable <replaceable>value</replaceable>
|
||||
</computeroutput></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Message returned if <returnvalue>variable</returnvalue> does not exist.
|
||||
Message returned if <replaceable>variable</replaceable> does
|
||||
not stand for an existing parameter.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><computeroutput>
|
||||
NOTICE: Time zone is unknown
|
||||
</computeroutput></term>
|
||||
<term><computeroutput>ERROR: permission denied</computeroutput></term>
|
||||
<listitem>
|
||||
<para>
|
||||
You must be a superuser to be allowed to see certain settings.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><computeroutput>NOTICE: Time zone is unknown</computeroutput></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If the <envar>TZ</envar> or <envar>PGTZ</envar> environment
|
||||
|
@ -94,82 +82,35 @@ NOTICE: Time zone is unknown
|
|||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id="R1-SQL-SHOW-1">
|
||||
<refsect1info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect1info>
|
||||
<title>
|
||||
Description
|
||||
</title>
|
||||
<para>
|
||||
<command>SHOW</command> will display the current setting of a
|
||||
run-time parameter during a session.
|
||||
</para>
|
||||
<para>
|
||||
These variables can be set using the <command>SET</command> statement,
|
||||
and
|
||||
can be restored to the default values using the <command>RESET</command>
|
||||
statement.
|
||||
Parameters and values are case-insensitive.
|
||||
</para>
|
||||
|
||||
<refsect2 id="R2-SQL-SHOW-3">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
Notes
|
||||
</title>
|
||||
<para>
|
||||
See also
|
||||
<xref linkend="sql-set-title" endterm="sql-set-title"> and
|
||||
<xref linkend="sql-reset-title" endterm="sql-reset-title">
|
||||
to manipulate variable values.
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-SHOW-2">
|
||||
<title>
|
||||
Usage
|
||||
</title>
|
||||
<title>Examples</title>
|
||||
<para>
|
||||
Show the current <literal>DateStyle</literal> setting:
|
||||
|
||||
<programlisting>
|
||||
<screen>
|
||||
SHOW DateStyle;
|
||||
NOTICE: DateStyle is ISO with US (NonEuropean) conventions
|
||||
</programlisting>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Show the current genetic optimizer (<literal>geqo</literal>) setting:
|
||||
<programlisting>
|
||||
<screen>
|
||||
SHOW GEQO;
|
||||
NOTICE: GEQO is ON beginning with 11 relations
|
||||
</programlisting>
|
||||
NOTICE: geqo = true
|
||||
</screen>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="R1-SQL-SHOW-3">
|
||||
<title>
|
||||
Compatibility
|
||||
</title>
|
||||
<title>Compatibility</title>
|
||||
|
||||
<refsect2 id="R2-SQL-SHOW-4">
|
||||
<refsect2info>
|
||||
<date>1998-09-24</date>
|
||||
</refsect2info>
|
||||
<title>
|
||||
SQL92
|
||||
</title>
|
||||
<para>
|
||||
There is no <command>SHOW</command> defined in <acronym>SQL92</acronym>.
|
||||
</para>
|
||||
</refsect2>
|
||||
<para>
|
||||
The <command>SHOW</command> command is a
|
||||
<productname>Postgres</productname> extension.
|
||||
</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,28 +1,10 @@
|
|||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/start-ag.sgml,v 1.10 2000/03/31 03:27:41 thomas Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/start-ag.sgml,v 1.11 2000/06/18 21:24:51 petere Exp $
|
||||
- This file currently contains several small chapters.
|
||||
- Each chapter should be split off into a separate source file...
|
||||
- - thomas 1998-02-24
|
||||
-->
|
||||
|
||||
<chapter id="newuser">
|
||||
<title>Adding and Deleting Users</title>
|
||||
|
||||
<para>
|
||||
<application>createuser</application> enables specific users to access
|
||||
<productname>Postgres</productname>.
|
||||
<application>dropuser</application> removes users and
|
||||
prevents them from accessing <productname>Postgres</productname>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
These commands only affect users with respect to
|
||||
<productname>Postgres</productname>;
|
||||
they have no effect on a user's other privileges or status with regards
|
||||
to the underlying operating system.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="disk">
|
||||
<title>Disk Management</title>
|
||||
|
||||
|
|
|
@ -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:
|
||||
-->
|
202
doc/src/sgml/user-manag.sgml
Normal file
202
doc/src/sgml/user-manag.sgml
Normal file
|
@ -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 a new issue