From 2c0edb3c8677831d836fc44eb58ebecb73f747af Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 18 Jun 2000 21:24:54 +0000 Subject: [PATCH] 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. --- doc/src/sgml/Makefile | 4 +- doc/src/sgml/admin.sgml | 9 +- doc/src/sgml/client-auth.sgml | 502 ++++++++ doc/src/sgml/pg_options.sgml | 240 ---- doc/src/sgml/postgres.sgml | 14 +- doc/src/sgml/programmer.sgml | 6 +- doc/src/sgml/ref/allfiles.sgml | 4 +- doc/src/sgml/ref/commands.sgml | 4 +- doc/src/sgml/ref/reset.sgml | 133 +- doc/src/sgml/ref/set.sgml | 1142 ++++------------- doc/src/sgml/ref/set_constraints.sgml | 53 + doc/src/sgml/ref/set_transaction.sgml | 93 ++ doc/src/sgml/ref/show.sgml | 151 +-- doc/src/sgml/runtime.sgml | 1686 ++++++++++++++++--------- doc/src/sgml/security.sgml | 627 --------- doc/src/sgml/signals.sgml | 266 ---- doc/src/sgml/start-ag.sgml | 20 +- doc/src/sgml/trouble.sgml | 289 ----- doc/src/sgml/user-manag.sgml | 202 +++ 19 files changed, 2259 insertions(+), 3186 deletions(-) create mode 100644 doc/src/sgml/client-auth.sgml delete mode 100644 doc/src/sgml/pg_options.sgml create mode 100644 doc/src/sgml/ref/set_constraints.sgml create mode 100644 doc/src/sgml/ref/set_transaction.sgml delete mode 100644 doc/src/sgml/security.sgml delete mode 100644 doc/src/sgml/signals.sgml delete mode 100644 doc/src/sgml/trouble.sgml create mode 100644 doc/src/sgml/user-manag.sgml diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index e99c145723..bb43863c15 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -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 diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 936ce863c6..c8fb66b411 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,5 +1,5 @@ + + + Client Authentication + + + User names from the operating system and from a + Postgres database installation are + logically separate. When a client application connects, it specifies + which database user name it wants to connect as, similar to how one + logs into a Unix computer. Within the SQL environment the active + database user name determines various access privileges to database + objects -- see for more information + about that. It is therefore obviously essential to restrict what + database user name a given client can connect as. + + + + Authentication is the process by which the + database server establishes the identity of the client, and by + extension determines whether the client application (or the user + which runs the client application) is permitted to connect with the + user name that was requested. + + + + Postgres offers client authentication by + (client) host and by database, with a number of different + authentication methods available. + + + + The <filename>pg_hba.conf</filename> file + + + Client authentication is controlled by the file + pg_hba.conf in the data directory, e.g., + /usr/local/pgsql/data/pg_hba.conf. (HBA = + host-based authentication) A default file is installed when the + data area is initialized by initdb. + + + + The general format of the pg_hba.conf 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. + + + + A record may have one of the two formats + +local database authentication-method [ authentication-option ] +host database IP-address IP-mask authentication-method [ authentication-option ] + + The meaning of the fields is as follows: + + + + local + + + This record pertains to connection attempts over Unix domain + sockets. + + + + + + host + + + 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 or + the equivalent configuration parameter is set. + + + + + + database + + + Specifies the database that this record applies to. The value + all specifies that it applies to all + databases. + + + + + + IP address + IP mask + + + These two fields control to which hosts a + host record applies, based on their IP + address. (Of course IP addresses can be spoofed but this + consideration is beyond the scope of + Postgres.) The precise logic is that +
+ + (actual-IP-address xor IP-address-field) and IP-mask-field + +
+ must be zero for the record to match. + + + + + + authentication method + + + Specifies the method a user must use to authenticate themselves + when connecting to that database. + + + + + + authentication option + + + This field is interpreted differently depending on the + authentication method. + + + + + + The first record that matches a connection attempt is used. Note + that there is no fall-through or + backup, 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. + + + + The pg_hba.conf file is re-read before each + connection attempt. It is therefore easily possible to modify + access permissions while the server is running. + + + + An example of a pg_hba.conf file is shown in + . See below for details on the + different authentication methods. + + + An example <filename>pg_hba.conf</filename> file + +# 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 + + + + + + + Authentication methods + + The following authentication methods are supported. They are + descibed in detail below. + + + + trust + + + 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. + + + + + + reject + + + The connection is rejected unconditionally. This is mostly + useful to filter out certain hosts from a group. + + + + + + password + + + 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.) + + + An optional password file may be specified after the + password keyword to obtain the password from + that file rather than the pg_shadow system catalog. + + + The password is sent over the wire in clear text. For better + protection, use the crypt method. + + + + + + crypt + + + Like the password 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 + crypt does not support secondary password + files. + + + + + + krb4 + + + Kerberos V4 is used to authenticate the user. This is only + available for TCP/IP connections. + + + + + + krb5 + + + Kerberos V5 is used to authenticate the user. This is only + available for TCP/IP connections. + + + + + + ident + + + The ident server on the client host is asked for the identity + of the connecting user. Postgres + then verifies whether the so identified operating system user + is allowed to connect as the database user that is requested. + The authentication option following + the ident keyword specifies the name of an + ident map that specifies which operating + system users equate with which database users. See below for + details. + + + + + + + + Password authentication + + 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 CREATE USER and + ALTER USER, e.g., CREATE USER foo + WITH PASSWORD 'secret';. By default, that is, if no + password has explicitly been set up, the stored password is + NULL and password authentication will always fail + for that user. + + + + 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 /etc/passwd, that is, + +username:password + + Any extra colon separated fields following the password are + ignored. The password is expected to be encrypted using the + system's crypt() function. The utility + program pg_passwd that is installed + with Postgres can be used to manage + these password files. + + + + 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. + + + + Note that using secondary password files means that one can no + longer use ALTER USER 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. + + + + + Kerberos authentication + + + Kerberos is an industry-standard secure + authentication system suitable for distributed computing over a + public network. A description of the + Kerberos system is far beyond the scope + of this document; in all generality it can be quite complex. The + Kerberos FAQ + can be a good starting point for exploration. + + + + In order to use Kerberos, support for it must be + enable at build time. Both Kerberos 4 and 5 are supported. + + + + Postgres should operate like a normal Kerberos + service. The name of the service principal is normally + postgres, 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 + ). The location of the keytab file + is specified at build time. By default it is + /etc/srvtab in Kerberos 4 and + FILE:/usr/local/postgres/krb5.keytab in + Kerberos 5. + + + + + + Ident-based authentication + + + The Identification Protocol is described in + RFC 1413. 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 What user initiated the + connection that goes out of your port X + and connects to my port Y?. + Since both X and + Y are known, + Postgres could theoretically determine + the operating system user for any given connection this way. + + + + 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: +
+ RFC 1413 + + The Identification Protocol is not intended as an authorization + or access control protocol. + +
+ + + + When using ident-based authentication, after having determined the + operating system user that initiated the connection, + Postgres determines as what database + system user he may connect. This is controlled by the ident map + argument that follows the ident keyword in the + pg_hba.conf file. The simplest ident map is + sameuser, 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. + + + + Ident maps are held in the file pg_ident.conf + in the data directory, which contains lines of the general form: + +map-name ident-username database-username + + Comments and whitespace are handled in the usual way. + The map-name is an arbitrary name that will be + used to refer to this mapping in pg_hba.conf. + The other two fields specify which operating system user is + allowed to connect as which database user. The same + 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. + + + + A pg_ident.conf file that could be used in + conjunction with the pg_hba.conf file in is shown in . In that example setup, anyone + logged in to a machine on the 192.168.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 bob, not as robert or + anyone else. ann and joe would only + be allowed to connect as themselves. On the + 192.168.2 network, however, a user ann would not be + allowed to connect at all, only the user bob can connect + as bob and some user karl can connect as + joe as well. + + + + An example <filename>pg_ident.conf</> file + +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 + + + + + + + Authentication problems + + + Genuine authentication failures and related problems generally + manifest themselves through error messages like the following. + + + + +No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb + + 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 pg_hba.conf + configuration file. + + + + +Password authentication failed for user 'joeblow' + + 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 + 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. + + + + +FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow' + + This is the fancy way of saying that the user doesn't exist at all. + + + + +FATAL 1: Database testdb does not exist in pg_database + + 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. + + + + + diff --git a/doc/src/sgml/pg_options.sgml b/doc/src/sgml/pg_options.sgml deleted file mode 100644 index 7bb2b0b839..0000000000 --- a/doc/src/sgml/pg_options.sgml +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - Massimo - Dal Zotto - - - Transcribed 1998-10-16 - - - pg_options - - - - - Contributed by Massimo Dal Zotto - - - - - The optional file data/pg_options 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 - Postgres. - The options specified in this file may be debugging flags used by the trace - package (backend/utils/misc/trace.c) or numeric - parameters which can be used by the backend to control its behaviour. - New options and parameters must be defined in - backend/utils/misc/trace.c and - backend/include/utils/trace.h. - - - For example suppose we want to add conditional trace messages and a tunable - numeric parameter to the code in file foo.c. - All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into - backend/include/utils/trace.h: - - -/* 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 */ -}; - - - and a corresponding line in backend/utils/misc/trace.c: - - -/* file trace.c */ -static char *opt_names[] = { - ... - "foo", /* trace foo functions */ - "fooparam" /* foo tunable parameter */ -}; - - - 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: - - -/* 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); - } -} - - - - Existing files using private trace flags can be changed by simply adding - the following code: - - -#include "trace.h" -/* int my_own_flag = 0; -- removed */ -#define my_own_flag pg_options[OPT_MY_OWN_FLAG] - - - - 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 PostgresMain. - - Now we can set the foo_param and enable foo trace by writing values into the - data/pg_options file: - - -# file pg_options -... -foo=1 -fooparam=17 - - - - 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. - - - pg_options can also be specified with the switch of - Postgres: - - -postgres options -T "verbose=2,query,hostlookup-" - - - - The functions used for printing errors and debug messages can now make use - of the syslog(2) facility. Message printed to stdout - or stderr are prefixed by a timestamp containing also the backend pid: - - -#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 - - - - 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. - - - 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 printf() - 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. - - - - The new pg_options mechanism is more convenient than defining new backend - option switches because: - - - - - 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. - - - - - - we don't have to restart Postgres 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. - - - - - - 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. - - - - - The format of the pg_options file is as follows: - - -# comment -option=integer_value # set value for option -option # set option = 1 -option+ # set option = 1 -option- # set option = 0 - - - Note that keyword can also be - an abbreviation of the option name defined in - backend/utils/misc/trace.c. - - - - Refer to The Administrator's Guide chapter - on runtime options for a complete list of currently supported - options. - - - - Some of the existing code using private variables and option switches has - been changed to make use of the pg_options feature, mainly in - postgres.c. 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 Postgres command line - and can have more tunable options - with a unique place to put option values. - - - - - diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 2f7d150264..02abce94f2 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,5 +1,5 @@ - + + - @@ -100,10 +100,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th - - ]> @@ -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... &sources; &arch-dev; - &options; &geqo; &protocol; - &signals; &compiler; &bki; &page; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index fae484a69e..fe1fd3af99 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,5 +1,5 @@ @@ -50,10 +50,8 @@ Postgres Programmer's Guide. - - ]> @@ -165,7 +163,6 @@ Disable it until we put in some info. &sources; &arch-dev; - &options; &geqo; &protocol; - &signals; &compiler; &bki; &page; diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index aef598d8a3..3611943dbe 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,5 +1,5 @@ @@ -98,6 +98,8 @@ Complete list of usable sgml source files in this directory. + + diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index 28f7f0cbde..9f6ba8e70d 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -1,5 +1,5 @@ @@ -72,6 +72,8 @@ Postgres documentation &select; &selectInto; &set; + &setConstraints; + &setTransaction; &show; &truncate; &unlisten; diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index e8f98aba3b..e9f515da7b 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -1,47 +1,32 @@ - - RESET - + RESET SQL - Language Statements - - RESET - - - Restores run-time parameters for session to default values - + RESET + Restores run-time parameters to default values - - 1999-07-20 - RESET variable - - 1998-09-24 - - - Inputs - + Inputs variable - Refer to - - for more information on available variables. + The name of a run-time parameter. See for a list. @@ -49,107 +34,55 @@ RESET variable - - - 1998-09-24 - - - Outputs - - - - - - -RESET VARIABLE - - - - Message returned if - variable is successfully reset - to its default value. - - - - - - - - - 1998-09-24 - - - Description - + + Description - RESET restores variables to their - default values. - Refer to + RESET restores run-time parameters to their + default values. Refer to - for details on allowed values and defaults. - RESET is an alternate form for + for details. RESET is an alternate form for -SET variable = DEFAULT +SET variable TO DEFAULT - - - - 1998-09-24 - - - Notes - - - - See also - and - - to manipulate variable values. - - - - - - Usage - + + + Diagnostics + + See under the command. + + + + + Examples Set DateStyle to its default value: - + RESET DateStyle; - + Set Geqo to its default value: - + RESET GEQO; - + - - - Compatibility - + + Compatibility - - - 1998-09-24 - - - SQL92 - - - There is no RESET in SQL92. - - + + RESET is a Postgres extension. + diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 3d3884dd30..044cf8fd65 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,53 +1,32 @@ - - SET - + SET SQL - Language Statements - - SET - - - Set run-time parameters for session - + SET + Set run-time parameters - - 1999-07-20 - SET variable { TO | = } { value | 'value' | DEFAULT } -SET CONSTRAINTS {ALL | constraintlist} mode SET TIME ZONE { 'timezone' | LOCAL | DEFAULT } -SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } - - 1998-09-24 - - - Inputs - + Inputs - variable - Settable global parameter. + A settable run-time parameter. @@ -64,147 +43,144 @@ SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } + - - The possible variables and allowed values are: - - - - CLIENT_ENCODING | NAMES - - - Sets the multi-byte client encoding. Parameters are: - - - - value - - - Sets the multi-byte client encoding to - value. - The specified encoding must be supported by the backend. - - - - - + + + + Description + + The SET command changes run-time configuration + parameters. The following parameters can be altered: - - This option is only available if MULTIBYTE support was enabled - during the configure step of building Postgres. - - - + + + CLIENT_ENCODING + NAMES + + + Sets the multi-byte client encoding. The specified encoding + must be supported by the backend. + - - DATESTYLE - - - Set the date/time representation style. Affects the output format, - and in some cases it can affect the interpretation of input. + + This option is only available if + Postgres is build with multibyte + support. + + + - - - ISO - - - use ISO 8601-style dates and times - - - - - SQL - - - use Oracle/Ingres-style dates and times - - - - - Postgres - - - use traditional Postgres format - - - - - European - - - use dd/mm/yyyy for numeric date representations. - - - - - NonEuropean - - - use mm/dd/yyyy for numeric date representations. - - - - - German - - - use dd.mm.yyyy for numeric date representations. - - - - - US - - - same as NonEuropean - - - - - DEFAULT - - - restores the default values (ISO) - - - - - + + DATESTYLE + + + Choose the date/time representation style. Two separate + settings are made: the default date/time output and the + interpretation of ambiguous input. + - - Date format initialization may be done by: - - - Setting the PGDATESTYLE environment variable. - If PGDATESTYLE is set in the frontend environment of a client - based on libpq, libpq will automatically set DATESTYLE to the - value of PGDATESTYLE during connection startup. - - - Running postmaster using the option to set - dates to the European convention. - Note that this affects only some combinations of date styles; for example - the ISO style is not affected by this parameter. - - - Changing variables in - src/backend/utils/init/globals.c. - - - - - The variables in globals.c which can be changed are: - - - bool EuroDates = false | true - - - int DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES - - - - - + + The following are date/time output styles: + + + + ISO + + + Use ISO 8601-style dates and times (YYYY-MM-DD + HH:MM:SS). This is the default. + + + + + + SQL + + + Use Oracle/Ingres-style dates and times. Note that this + style has nothing to do with SQL (which mandates ISO 8601 + style), the naming of this option is a historical accident. + + + + + + Postgres + + + Use traditional Postgres format. + + + + + + German + + + Use dd.mm.yyyy for numeric date representations. + + + + + + + + The following two options determine both a substyle of the + SQL and Postgres output formats + and the preferred interpretation of ambiguous date input. + + + + European + + + Use dd/mm/yyyy for numeric date representations. + + + + + + NonEuropean + US + + + Use mm/dd/yyyy for numeric date representations. + + + + + + + + A value for SET DATESTYLE can be one from + the first list (output styles), or one from the second list + (substyles), or one from each separated by a comma. + + + + Date format initialization may be done by: + + + Setting the PGDATESTYLE environment variable. + If PGDATESTYLE is set in the frontend environment of a client + based on libpq, libpq will automatically set DATESTYLE to the + value of PGDATESTYLE during connection startup. + + + Running postmaster using the option to + set dates to the European convention. + + + + + The option is really only intended + for porting applications. To format your date/time values to + choice, use the to_char family of + functions. + + + SEED @@ -237,10 +213,6 @@ SELECT setseed(value); - - This option is only available if MULTIBYTE support was enabled - during the configure step of building Postgres. - @@ -248,71 +220,13 @@ SELECT setseed(value); SERVER_ENCODING - Sets the multi-byte server encoding to: - - - - value - - - The identifying value for the server encoding. - - - - + Sets the multi-byte server encoding. - This option is only available if MULTIBYTE support was enabled - during the configure step of building Postgres. - - - - - - CONSTRAINTS - - - SET CONSTRAINTS affects the behavior of constraint evaluation - in the current transaction. - SET CONSTRAINTS, specified - in SQL3, has these allowed parameters: - - - - constraintlist - - - Comma separated list of deferrable constraint names. - - - - - - mode - - - The constraint mode. Allowed values are - and . - - - - - - - - In mode, foreign key constraints - are checked at the end of each query. - - - - In mode, foreign key constraints - marked as are checked only at - transaction commit or until its mode is explicitly set to - . - This is actually only done for foreign key - constraints, so it does not apply to UNIQUE or other - constraints. + This option is only available if + Postgres was built with multibyte + support. @@ -323,8 +237,9 @@ SELECT setseed(value); The possible values for timezone depends on your operating - system. For example on Linux /usr/lib/zoneinfo contains the - database of timezones. + system. For example, on Linux + /usr/share/zoneinfo contains the database + of time zones. Here are some valid values for timezone: @@ -334,7 +249,7 @@ SELECT setseed(value); PST8PDT - set the timezone for California + Set the time zone for California. @@ -342,7 +257,7 @@ SELECT setseed(value); Portugal - set time zone for Portugal. + Set time zone for Portugal. @@ -350,16 +265,17 @@ SELECT setseed(value); 'Europe/Rome' - set time zone for Italy. + Set time zone for Italy. - DEFAULT + LOCAL + DEFAULT - set time zone to your local timezone - (value of the TZ environment variable). + Set the time zone to your local time zone (the one that + your operating system defaults to). @@ -369,12 +285,6 @@ SELECT setseed(value); If an invalid time zone is specified, the time zone becomes GMT (on most systems anyway). - - The second syntax shown above, allows one to set the timezone - with a syntax similar to SQL92 SET TIME ZONE. - The LOCAL keyword is just an alternate form - of DEFAULT for SQL92 compatibility. - If the PGTZ environment variable is set in the frontend environment of a client based on libpq, libpq will automatically @@ -383,716 +293,112 @@ SELECT setseed(value); - - TRANSACTION ISOLATION LEVEL - - - Sets the isolation level for the current transaction. - - - - READ COMMITTED - - - The current transaction queries read only rows committed - before a query began. READ COMMITTED is the default. - - - - - SQL92 standard requires - SERIALIZABLE to be the default isolation level. - - - - - - - SERIALIZABLE - - - The current transaction queries read only rows committed - before first DML statement - (SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO) - was executed in this transaction. - - - - - - - - - - There are also several internal or optimization - parameters which can be specified - by the SET command: - - - - PG_OPTIONS - - - Sets various backend parameters. - - - - - - RANDOM_PAGE_COST - - - Sets the optimizer's estimate of the cost of a nonsequentially - fetched disk page. This is measured as a multiple of the cost - of a sequential page fetch. - - - - float8 - - - Set the cost of a random page access - to the specified floating-point value. - - - - - - - - - - CPU_TUPLE_COST - - - Sets the optimizer's estimate of the cost of processing each - tuple during a query. This is measured as a fraction of the cost - of a sequential page fetch. - - - - float8 - - - Set the cost of per-tuple CPU processing - to the specified floating-point value. - - - - - - - - - - CPU_INDEX_TUPLE_COST - - - Sets the optimizer's estimate of the cost of processing each - index tuple during an index scan. This is measured as a fraction - of the cost of a sequential page fetch. - - - - float8 - - - Set the cost of per-index-tuple CPU processing - to the specified floating-point value. - - - - - - - - - - CPU_OPERATOR_COST - - - Sets the optimizer's estimate of the cost of processing each - operator in a WHERE clause. This is measured as a fraction - of the cost of a sequential page fetch. - - - - float8 - - - Set the cost of per-operator CPU processing - to the specified floating-point value. - - - - - - - - - - EFFECTIVE_CACHE_SIZE - - - Sets the optimizer's assumption about the effective size of the - disk cache (that is, the portion of the kernel's disk cache that - will be used for Postgres data files). This is measured in disk - pages, which are normally 8Kb apiece. - - - - float8 - - - Set the assumed cache size - to the specified floating-point value. - - - - - - - - - - EXAMINE_SUBCLASS - - - Changes the behaviour of SELECT so that it no longer automatically - examines sub-classes. (See SELECT). By default a SELECT on a table - will also return subclass tuples unless specifying ONLY tablename. - Setting this returns postgres to the traditional behaviour of - only returning subclasses when appending "*" to the tablename. - - - ON - - - Returns SELECT to the behaviour of automatically returning - results from sub-classes. - - - - - - OFF - - - Prevents SELECT from returning sub-classes unless the "*" follows the table name - - - - - - - - - - ENABLE_SEQSCAN - - - Enables or disables the planner's use of sequential scan plan types. - (It's not possible to suppress sequential scans entirely, but turning - this variable OFF discourages the planner from using one if there is - any other method available.) - - - - ON - - - enables use of sequential scans (default setting). - - - - - - OFF - - - disables use of sequential scans. - - - - - - - - - - ENABLE_INDEXSCAN - - - Enables or disables the planner's use of index scan plan types. - - - - ON - - - enables use of index scans (default setting). - - - - - - OFF - - - disables use of index scans. - - - - - - - - - - ENABLE_TIDSCAN - - - Enables or disables the planner's use of TID scan plan types. - - - - ON - - - enables use of TID scans (default setting). - - - - - - OFF - - - disables use of TID scans. - - - - - - - - - - ENABLE_SORT - - - Enables or disables the planner's use of explicit sort steps. - (It's not possible to suppress explicit sorts entirely, but turning - this variable OFF discourages the planner from using one if there is - any other method available.) - - - - ON - - - enables use of sorts (default setting). - - - - - - OFF - - - disables use of sorts. - - - - - - - - - - ENABLE_NESTLOOP - - - Enables or disables the planner's use of nested-loop join plans. - (It's not possible to suppress nested-loop joins entirely, but turning - this variable OFF discourages the planner from using one if there is - any other method available.) - - - - ON - - - enables use of nested-loop joins (default setting). - - - - - - OFF - - - disables use of nested-loop joins. - - - - - - - - - - ENABLE_MERGEJOIN - - - Enables or disables the planner's use of mergejoin plans. - - - - ON - - - enables use of merge joins (default setting). - - - - - - OFF - - - disables use of merge joins. - - - - - - - - - - ENABLE_HASHJOIN - - - Enables or disables the planner's use of hashjoin plans. - - - - ON - - - enables use of hash joins (default setting). - - - - - - OFF - - - disables use of hash joins. - - - - - - - - - - GEQO - - - Sets the threshold for using the genetic optimizer algorithm. - - - - ON - - - enables the genetic optimizer algorithm - for statements with 11 or more tables. - (This is also the DEFAULT setting.) - - - - - - ON=# - - - Takes an integer argument to enable the genetic optimizer algorithm - for statements with # - or more tables in the query. - - - - - - OFF - - - disables the genetic optimizer algorithm. - - - - - - - - See the chapter on GEQO in the Programmer's Guide - for more information about query optimization. - - - If the PGGEQO environment variable is set in the frontend - environment of a client based on libpq, libpq will automatically - set GEQO to the value of PGGEQO during connection startup. - - - - - - KSQO - - - Key Set Query Optimizer causes the query - planner to convert queries whose WHERE clause contains many - OR'ed AND clauses (such as "WHERE (a=1 AND b=2) OR (a=2 AND b=3) ...") - into a UNION query. This method can be faster than the default - implementation, but it doesn't necessarily give exactly the same - results, since UNION implicitly adds a SELECT DISTINCT clause to - eliminate identical output rows. KSQO is commonly used when - working with products like MicroSoft - Access, which tend to generate queries of this form. - - - - ON - - - enables this optimization. - - - - - - OFF - - - disables this optimization (default setting). - - - - - - DEFAULT - - - Equivalent to specifying SET KSQO=OFF. - - - - - - - - The KSQO algorithm used to be absolutely essential for queries - with many OR'ed AND clauses, but in Postgres 7.0 and later - the standard planner handles these queries fairly successfully. - - - - - - MAX_EXPR_DEPTH - - - Sets the maximum expression nesting depth that the parser will - accept. The default value is high enough for any normal query, - but you can raise it if you need to. (But if you raise it too high, - you run the risk of backend crashes due to stack overflow.) - - - - integer - - - Maximum depth. - - - - - - - - - - - - - - - 1998-09-24 - - - Outputs - - - - - - -SET VARIABLE - - - - Message returned if successful. - - - - - - -NOTICE: Bad value for variable (value) - - - - If the command fails to set the specified variable. - - - - - - - - - - - - 1998-09-24 - - - Description - - SET will modify configuration parameters for variable during - a session. + An extended list of other run-time parameters can be found in the + Administrator's Guide. + - Current values can be obtained using SHOW, and values - can be restored to the defaults using RESET. - Parameters and values are case-insensitive. Note that the value - field is always specified as a string, so is enclosed in - single-quotes. - - - SET TIME ZONE changes the session's - default time zone offset. - An SQL-session always begins with an initial default time zone - offset. - The SET TIME ZONE statement is used to change the default - time zone offset for the current SQL session. + Use to show the + current setting of a parameters. - - - 1998-09-24 - - - Notes - - - The SET variable - statement is a Postgres language extension. - - - Refer to SHOW and RESET to - display or reset the current values. - - - - - - Usage - + + + Diagnostics - Set the style of date to ISO (no quotes on the argument is required): + + + + SET VARIABLE + + + Message returned if successful. + + + + + + ERROR: not a valid option name: name + + + The parameter you tried to set does not exist. + + + + + + ERROR: permission denied + + + You must be a superuser to have access to certain settings. + + + + + + ERROR: name can only be set at startup + + + Some parameters are fixed once the server is started. + + + + + + + - -SET DATESTYLE TO ISO; - - - Enable GEQO for queries with 4 or more tables (note the use of - single quotes to handle the equal sign inside the value argument): - - -SET GEQO = 'ON=4'; - - - Set GEQO to default: - - -SET GEQO = DEFAULT; - + + + Examples + + Set the style of date to traditional Postgres with European conventions: + +SET DATESTYLE TO Postgres,European; + Set the timezone for Berkeley, California, using double quotes to - preserve the uppercase - attributes of the time zone specifier: + preserve the uppercase attributes of the time zone specifier (note + that the date/time format is ISO here): - + SET TIME ZONE "PST8PDT"; SELECT CURRENT_TIMESTAMP AS today; today ------------------------ 1998-03-31 07:41:21-08 - + Set the timezone for Italy (note the required single or double quotes to handle the special characters): - + SET TIME ZONE 'Europe/Rome'; SELECT CURRENT_TIMESTAMP AS today; today ------------------------ 1998-03-31 17:41:31+02 - + - - Compatibility - - - - - 1998-09-24 - - - SQL92 - - - There is no general - SET variable - in SQL92 (with the exception of - SET TRANSACTION ISOLATION LEVEL). + Compatibility - The SQL92 syntax for SET TIME ZONE - is slightly different, - allowing only a single integer value for time zone specification: - - -SET TIME ZONE { interval_value_expression | LOCAL } - - - + + The second syntax shown above (SET TIME ZONE) + attempts to mimic SQL92. However, SQL allows + only numeric time zone offsets. All other parameter settings as + well as the first syntax shown above are a + Postgres extension. + diff --git a/doc/src/sgml/ref/set_constraints.sgml b/doc/src/sgml/ref/set_constraints.sgml new file mode 100644 index 0000000000..3cdb5d67a2 --- /dev/null +++ b/doc/src/sgml/ref/set_constraints.sgml @@ -0,0 +1,53 @@ + + + + SET CONSTRAINTS + SQL - Language Statements + + + SET CONSTRAINTS + Set the constraint mode of the current SQL-transaction + + + + 2000-06-01 + + +SET CONSTRAINTS { ALL | constraint [, ...] } { DEFERRED | IMMEDIATE } + + + + + Description + + + SET CONSTRAINTS sets the behavior of constraint + evaluation in the current transaction. In + mode, constraints are checked at the end + of each statement. In mode, constraints + are not checked until transaction commit. + + + + Upon creation, a constraint is always give one of three + characteristics: , + , or + . The third + class is not affected by the SET CONSTRAINTS + command. + + + + Currently, only foreign key constraints are affected by this + setting. Check and unique constraints are always effectively + initially immediate not deferrable. + + + + + Compatibility + + SQL92, SQL99 + + + diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml new file mode 100644 index 0000000000..e5de2e7f5b --- /dev/null +++ b/doc/src/sgml/ref/set_transaction.sgml @@ -0,0 +1,93 @@ + + + + SET TRANSACTION + SQL - Language Statements + + + SET TRANSACTION + Set the characteristics of the current SQL-transaction + + + + 2000-06-01 + + +SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE } + + + + + Description + + + The SET TRANSACTION 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 (SELECT, + INSERT, DELETE, + UPDATE, FETCH, + COPY) of a transaction has been executed. + + + + The isolation level of a transaction determines what data the + transaction can see when other transactions are running concurrently. + + + + READ COMMITTED + + + A statement can only see rows committed before it began. This + is the default. + + + + + + SERIALIZABLE + + + The current transaction can only see rows committed before + first DML statement was executed in this transaction. + + + + 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. + + + + + + + + + + Compatibility + + + SQL92, SQL99 + + + + SERIALIZABLE is the default level in SQL. + Postgres does not provide the isolation levels and . Because + of multi-version concurrency control, the serializable level is not + truly serializable. See the User's Guide for + details. + + + + In SQL 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. + + + + diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 7cacd634e7..fdfc8057f6 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -1,48 +1,34 @@ - - SHOW - + SHOW SQL - Language Statements - - SHOW - - - Shows run-time parameters for session - + SHOW + Shows run-time parameters - - 1999-07-20 - -SHOW keyword +SHOW name - - 1998-09-24 - - - Inputs - + Inputs - keyword + name - Refer to + The name of a run-time parameter. See - for more information on available variables. + for a list. @@ -50,41 +36,43 @@ SHOW keyword - - - 1998-09-24 - - - Outputs - + + + + Description + + SHOW will display the current setting of a + run-time parameter. These variables can be set using the + SET statement or are determined at server start. + + + + + Diagnostics - -NOTICE: variable is value - + ERROR: not a valid option name: name - Message returned if successful. - - - - - -NOTICE: Unrecognized variable value - - - - Message returned if variable does not exist. + Message returned if variable does + not stand for an existing parameter. - -NOTICE: Time zone is unknown - + ERROR: permission denied + + + You must be a superuser to be allowed to see certain settings. + + + + + + NOTICE: Time zone is unknown If the TZ or PGTZ environment @@ -94,82 +82,35 @@ NOTICE: Time zone is unknown - - - - - - 1998-09-24 - - - Description - - - SHOW will display the current setting of a - run-time parameter during a session. - - - These variables can be set using the SET statement, - and - can be restored to the default values using the RESET - statement. - Parameters and values are case-insensitive. - - - - - 1998-09-24 - - - Notes - - - See also - and - - to manipulate variable values. - - - - Usage - + Examples Show the current DateStyle setting: - + SHOW DateStyle; NOTICE: DateStyle is ISO with US (NonEuropean) conventions - + Show the current genetic optimizer (geqo) setting: - + SHOW GEQO; -NOTICE: GEQO is ON beginning with 11 relations - +NOTICE: geqo = true + - - Compatibility - + Compatibility - - - 1998-09-24 - - - SQL92 - - - There is no SHOW defined in SQL92. - - + + The SHOW command is a + Postgres extension. + diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index dbe984c7b3..b92a1cc67b 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,642 +1,1128 @@ - - Runtime Environment + + Server Runtime Environment - - This chapter outlines the interaction between Postgres and - the operating system. + + This chapter discusses how to set up and run the database server + and the interactions with the operating system. + + + + The Postgres user account + + + As with any other server daemon that is connected to the world at + large, it is advisable to run Postgres under a separate user + account. This user account should only own the data itself that is + being managed by the server, and should not be shared with other + daemons. (Thus, using the user nobody is a bad + idea.) It is not advisable to install the executables as owned by + this user account because that runs the risk of user-defined + functions gone astray or any other exploits compromising the + executable programs. - - Using <Productname>Postgres</Productname> from Unix + + To add a user account to your system, look for a command + useradd or adduser. The user + name postgres is often used but by no means + required. + + + + Creating a database cluster + + + Before you can do anything, you must initialize a database storage + area on disk. We call this a database + cluster. (SQL speaks of a catalog + cluster instead.) A database cluster is a collection of databases + that will be accessible through a single instance of a running + database server. After initialization, a database cluster will + contain one database named template1. As the + name suggests, this will be used as a template for any subsequently + created database; it should not be used for actual work. + + + + In file system terms, a database cluster will be a single directory + under which all data will be stored. We call this the + data directory or data + area. It is completely up to you where you choose to + store your data, there is no default, although locations such as + /usr/local/pgsql/data or + /var/lib/pgsql/data are popular. To initialize + a database cluster, use the command initdb, + which is installed with PostgreSQL. The + desired file system location of your database system is indicated + by the option, for example + +> initdb -D /usr/local/pgsql/data + + Note that you must execute this command while being logged in to + the Postgres user account, which is described in the previous + section. + + + - All Postgres commands that are executed - directly from a Unix shell are - found in the directory .../bin. Including this directory in - your search path will make executing the commands easier. + As an alternative to the option, you can set + the environment variable PGDATA. + - - A collection of system catalogs exist at each site. These include a - class (pg_user) that contains an instance for each valid - Postgres user. The instance specifies a set of - Postgres privileges, such as - the ability to act as Postgres super-user, - the ability to create/destroy - databases, and the ability to update the system catalogs. A Unix - user cannot do anything with Postgres - until an appropriate instance is - installed in this class. Further information on the system catalogs - is available by running queries on the appropriate classes. - - + + initdb will attempt to create the directory you + specify if it does not already exist. It is likely that it won't + have the permission to do so (if you followed our advice and + created an unprivileged account). In that case you can create the + directory yourself (as root) and transfer ownership of it or grant + write access to it. Here is how this might work: + +root# mkdir /usr/local/pgsql/data +root# chown postgres /usr/local/pgsql/data +root# su postgres +postgres> initdb -D /usr/local/pgsql/data + + - - Starting <Application>postmaster</Application> + + initdb will refuse to run if the data directory + looks like it belongs to an already initialized installation. + - - Nothing can happen to a database unless the - postmaster - process is running. As the site administrator, there - are a number of things you should remember before - starting the postmaster. - These are discussed in the installation and configuration sections - of this manual. - However, if Postgres has been installed by following - the installation instructions exactly as written, the - following simple command is all you should - need to start the postmaster: + + Because the data directory contains all the data stored in the + database it is essential that it be well secured from unauthorized + access. initdb therefore revokes access + permissions from everyone but the Postgres user account. + + - -% postmaster - - + + Starting the database server - - The postmaster occasionally prints out - messages which - are often helpful during troubleshooting. If you wish - to view debugging messages from the postmaster, - you can - start it with the -d option and redirect the output to - the log file: + + Before anyone can access the database you must start the database + server. The database server is called + postmaster. + The postmaster must know where to find the data it is supposed + to work on. This is done with the option. Thus, + the simplest way to start the server is, for example, + +> postmaster -D /usr/local/pgsql/data + + which will leave the server running in the foreground. This must + again be done while logged in to the Postgres user account. Without + a , the server will try to use the data + directory in the environment variable PGDATA; if + neither of these works it will fail. + - -% postmaster -d > pm.log 2>&1 & - + + To start the postmaster in the + background, use the usual shell syntax: + +> postmaster -D /usr/local/pgsql/data > logfile 1>&2 & + + It is an extremely good idea to keep the server output around + somewhere, as indicated here. It will help both for auditing + purposes and to diagnose problems. + - If you do not wish to see these messages, you can type - -% postmaster -S - - and the postmaster will be "S"ilent. - No ampersand ("&") is required in this case, since the postmaster - automatically detaches from the terminal when -S is specified. - - + + The postmaster also takes a number of other command line options. + For more information see the reference page and below under runtime + configuration. In particular, in order for the postmaster to accept + TCP/IP connections (rather than just Unix domain socket ones), you + must also specify the option. + - - Using pg_options + + Normally, you will want to start the database server when the + computer boots up. This is not required; the + PostgreSQL server can be run + successfully from non-privileged accounts without root + intervention. + - - - - Contributed by Massimo Dal Zotto - - - - - The optional file data/pg_options contains runtime - options used by the backend to control trace messages and other backend - tunable parameters. - The file 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 - Postgres. - The options specified in this file may be debugging flags used by the trace - package (backend/utils/misc/trace.c) or numeric - parameters which can be used by the backend to control its behaviour. - + + Different systems have different conventions for starting up + daemons at boot time, so you are advised to familiarize yourself + with them. Many systems have a file + /etc/rc.local or + /etc/rc.d/rc.local which is almost certainly + no bad place to put such a command. Whatever you do, postmaster + must be run by the Postgres user account + and not by root or any other user. Therefore + you probably always want to form your command lines along the lines + of su -c '...' postgres, for example: + +nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & + + (using the program nohup to prevent the + server from dying when you log out). + - - All pg_options are initialized to zero at backend startup. - New or modified options will be read by all new backends when they are started. - To make effective any 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. - - - pg_options can also be specified with the switch of - Postgres: - - -postgres options -T "verbose=2,query,hostlookup-" - - - - - The functions used for printing errors and debug messages can now make use - of the syslog(2) facility. Message printed to stdout - or stderr are prefixed by a timestamp containing also the backend pid: - - -#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 - - - - 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. - - - 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 printf() - 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. - - - - The format of the pg_options file is as follows: - - -# comment -option=integer_value # set value for option -option # set option = 1 -option+ # set option = 1 -option- # set option = 0 - - - Note that keyword can also be - an abbreviation of the option name defined in - backend/utils/misc/trace.c. - - - pg_options File + + Here are a few more operating system specific suggestions. + + - For example my pg_options file contains the following values: - - -verbose=2 -query -hostlookup -showportnumber - + Edit the file rc.local on + NetBSD or file + rc2.d on Solaris to contain the + following single line: + +su postgres -c "/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data" + - + + + + + On FreeBSD edit + /usr/local/etc/rc.d/pgsql.sh to contain the + following lines and make it chmod 755 and + chown root:bin. + +#!/bin/sh +[ -x /usr/local/pgsql/bin/postmaster ] && { + su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster + -D/usr/local/pgsql/data + -S -o -F > /usr/local/pgsql/errlog' & + echo -n ' pgsql' +} + + You may put the line breaks as shown above. The shell is smart + enough to keep parsing beyond end-of-line if there is an + expression unfinished. The exec saves one layer of shell under + the postmaster process so the parent is init. + + + + + + On RedHat Linux add a file + /etc/rc.d/init.d/postgres.init + which is based on the example in contrib/linux/. + Then make a softlink to this file from + /etc/rc.d/rc5.d/S98postgres.init. + + + - - Recognized Options + + While the postmaster is running, it's + PID is in the file postmaster.pid in the data + directory. This is used as in interlock against multiple running + postmaster on the same data directory and can also be used for + shutting down the postmaster. + - - The options currently defined are: + + The shell script wrapper pg_ctl that + comes with Postgres can also be used to + control starting (and stopping!) of the database server in + intelligent fashion. + - - - - all - - - - Global trace flag. Allowed values are: - + + Server Startup Failures - - - - 0 - - - - Trace messages enabled individually - - - + + 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. + - - - 1 - - - - Enable all trace messages - - - - - - - -1 - - - - Disable all trace messages - - - + + +FATAL: StreamServerPort: bind() failed: Address already in use + Is another postmaster already running on that port? + + 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 + +> postmaster -i -p 666 +FATAL: StreamServerPort: bind() failed: Permission denied + Is another postmaster already running on that port? + + - - - + + A message like + +IpcMemoryCreate: shmget(5440001, 83918612, 01600) failed: Invalid argument +FATAL 1: ShmemCreate: cannot create region + + 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 (83918612 bytes in this example). 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 ( 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. + - - - verbose - - - - Verbosity flag. Allowed values are: - + + An error like + +IpcSemaphoreCreate: semget(5440026, 16, 0600) failed: No space left on device + + does not 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 + ( switch), but you'll eventually want to + increase the kernel limit. + + - - - - 0 - - - - No messages. This is the default. - - - + + Client Connection Problems - - - 1 - - - - Print information messages. - - - + + Although the possible error conditions on the client side are + both virtually infinite and application dependent, a few of them + might be directly related to how the server was started up. + Conditions other than those shown below should be documented with + the respective client application. + - - - 2 - - - - Print more information messages. - - - + + +connectDB() -- connect() failed: Connection refused +Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'? + + This is the generic I couldn't find a server to talk + to failure. It looks like the above when TCP/IP + communication is attempted. A common mistake is to forget the + to the postmaster to allow TCP/IP + connections. + - - - + + Alternatively, you'll get this when attempting + Unix-socket communication to a local postmaster: + +connectDB() -- connect() failed: No such file or directory +Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'? + + - - - query - - - - Query trace flag. Allowed values are: - - - - - - 0 - - - - Don't print query. - - - - - - - 1 - - - - Print a condensed query in one line. - - - - - - - 4 - - - - Print the full query. - - - - - - - - - - - plan - - - - Print query plan. - - - - - - - parse - - - - Print parser output. - - - - - - - rewritten - - - - Print rewritten query. - - - - - - - pretty_plan - - - - Pretty-print query plan. - - - - - - - pretty_parse - - - - Pretty-print parser output. - - - - - - - pretty_rewritten - - - - Pretty-print rewritten query. - - - - - - - parserstats - - - - Print parser statistics. - - - - - - - plannerstats - - - - Print planner statistics. - - - - - - - executorstats - - - - Print executor statistics. - - - - - - - shortlocks - - - - Currently unused but needed to enable features in the future. - - - - - - - locks - - - - Trace locks. - - - - - - - userlocks - - - - Trace user locks. - - - - - - - spinlocks - - - - Trace spin locks. - - - - - - - notify - - - - Trace notify functions. - - - - - - - malloc - - - - Currently unused. - - - - - - - palloc - - - - Currently unused. - - - - - - - lock_debug_oidmin - - - - Minimum relation oid traced by locks. - - - - - - - lock_debug_relid - - - - oid, if not zero, of relation traced by locks. - - - - - - - lock_read_priority - - - - Currently unused. - - - - - - - deadlock_timeout - - - - Deadlock check timer. - - - - - - - syslog - - - - syslog flag. Allowed values are: - - - - - - 0 - - - - Messages to stdout/stderr. - - - - - - - 1 - - - - Messages to stdout/stderr and syslog. - - - - - - - 2 - - - - Messages only to syslog. - - - - - - - - - - - hostlookup - - - - Enable hostname lookup in ps_status. - - - - - - - showportnumber - - - - Show port number in ps_status. - - - - - - - nofsync - - - - Disable fsync on a per-backend basis. - - - - - + + 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 not mean that the postmaster + got your connection request and rejected it -- that case will + produce a different message, as shown in .) Other error messages + such as Connection timed out may + indicate more fundamental problems, like lack of network + connectivity. + + Run-time configuration + + + There are a lot of configuration parameters that affect the + behavior of the database system in some way or other. Here we + describe how to set them and the following subsections will + discuss each of them. + + + + All parameter names are case-insensitive. Every parameter takes a + value of one of the four types boolean, integer, floating point, + string as described below. Boolean values are + ON, OFF, + TRUE, FALSE, + YES, NO, + 1, 0 (case-insensitive) or + any non-ambiguous prefix of these. + + + + One way to set these options is to create a file + postgresql.conf in the data directory (e.g., + /usr/local/pgsql/data). An example of how + this file could look like is this: + +# This is a comment +log_connections = yes +syslog = 2 + + As you see, options are one per line. The equal sign between name + and value is optional. White space is insignificant, blank lines + are ignored. Hash marks (#) introduce comments + anywhere. + + + + The configuration file is reread whenever the postmaster receives + a SIGHUP signal. This signal is also propagated to all running + backend processes, so that running sessions get the new default. + Alternatively, you can send the signal to only one backend process + directly. + + + + A second way to set these configuration parameters is to give them + as a command line option to the postmaster, such as + +postmaster --log-connections=yes --syslog=2 + + which would have the same effect as the previous example. + + + + Occasionally it is also useful to give a command line option to + one particular backend session only. The environment variable + PGOPTIONS can be used for this purpose on the + client side: + +env PGOPTIONS='--geqo=off' psql + + (This works for any client application, not just + psql.) Note that this won't work for + options that are necessarily fixed once the server is started, + such as the port number. + + + + Finally, some options can be changed in individual SQL sessions + with the SET command, for example + +=> SET ENABLE_SEQSCAN TO OFF; + + See the SQL command language reference for details on the syntax. + + + + Planner and Optimizer Tuning + + + + + CPU_INDEX_TUPLE_COST (floating point) + + + Sets the query optimizer's estimate of the cost of processing + each index tuple during an index scan. This is measured as a + fraction of the cost of a sequential page fetch. + + + + + + CPU_OPERATOR_COST (floating point) + + + Sets the optimizer's estimate of the cost of processing each + operator in a WHERE clause. This is measured as a fraction of + the cost of a sequential page fetch. + + + + + + CPU_TUPLE_COST (floating point) + + + Sets the query optimizer's estimate of the cost of processing + each tuple during a query. This is measured as a fraction of + the cost of a sequential page fetch. + + + + + + EFFECTIVE_CACHE_SIZE (floating point) + + + Sets the optimizer's assumption about the effective size of + the disk cache (that is, the portion of the kernel's disk + cache that will be used for + Postgres data files). This is + measured in disk pages, which are normally 8kB apiece. + + + + + + ENABLE_HASHJOIN (boolean) + + + Enables or disables the query planner's use of hash-join plan + types. The default is on. This is mostly useful to debug the + query planner. + + + + + + ENABLE_INDEXSCAN (boolean) + + + Enables or disables the query planner's use of index scan plan + types. The default is on. This is mostly useful to debug the + query planner. + + + + + + ENABLE_MERGEJOIN (boolean) + + + Enables or disables the query planner's use of merge-join plan + types. The default is on. This is mostly useful to debug the + query planner. + + + + + + ENABLE_NESTLOOP (boolean) + + + Enables or disables the query planner's use of nested-loop + join plans. It's not possible to suppress nested-loop joins + entirely, but turning this variable off discourages the + planner from using one if there is any other method available. + The default is on. This is mostly useful to debug the query + planner. + + + + + + ENABLE_SEQSCAN (boolean) + + + Enables or disables the query planner's use of sequential scan + plan types. It's not possible to suppress sequential scans + entirely, but turning this variable off discourages the + planner from using one if there is any other method available. + The default is on. This is mostly useful to debug the query + planner. + + + + + + ENABLE_SORT (boolean) + + + Enables or disables the query planner's use of explicit sort + steps. It's not possible to suppress explicit sorts entirely, + but turning this variable off discourages the planner from + using one if there is any other method available. The default + is on. This is mostly useful to debug the query planner. + + + + + + ENABLE_TIDSCAN (boolean) + + + Enables or disables the query planner's use of TID scan plan + types. The default is on. This is mostly useful to debug the + query planner. + + + + + + GEQO (boolean) + + + Enables or disables genetic query optimization, which is an + algorithm that attempts to do query planning without + exhaustive search. This is on by default. See also the various + other GEQO_ settings. + + + + + + GEQO_EFFORT (integer) + GEQO_GENERATIONS (integer) + GEQO_POOL_SIZE (integer) + GEQO_RANDOM_SEED (integer) + GEQO_SELECTION_BIAS (floating point) + + + Various tuning parameters for the genetic query optimization + algorithm: The pool size is the number of individuals in one + population. Valid values are between 128 and 1024. If it is + set to 0 (the default) a pool size of 2^(QS+1), where QS + is the number of relations in the query, is taken. The effort + is used to calculate a default for generations. Valid values + are between 1 and 80, 40 being the default. Generations + specifies the number of iterations in the algorithm. The + number must be a positive integer. If 0 is specified then + Effort * Log2(PoolSize) is used. The run time of the algorithm + is roughly proportional to the sum of pool size and + generations. The selection bias is the selective pressure + within the population. Values can be from 1.50 to 2.00; the + latter is the default. The random seed can be set to get + reproduceable results from the algorithm. If it is set to -1 + then the algorithm behaves non-deterministically. + + + + + + GEQO_RELS (integer) + + + Only use genetic query optimization for queries with at least + this many relations involved. The default is 11. For less + relations it is probably more efficient to use the + deterministic, exhaustive planner. + + + + + + KSQO (boolean) + + + The Key Set Query Optimizer + (KSQO) causes the query planner to convert + queries whose WHERE clause contains many OR'ed AND clauses + (such as WHERE (a=1 AND b=2) OR (a=2 AND b=3) + ...) into a UNION query. This method can be faster + than the default implementation, but it doesn't necessarily + give exactly the same results, since UNION implicitly adds a + SELECT DISTINCT clause to eliminate identical output rows. + KSQO is commonly used when working with products like + Microsoft Access, which tend to + generate queries of this form. + + + + The KSQO algorithm used to be absolutely essential for queries + with many OR'ed AND clauses, but in + Postgres 7.0 and later the standard + planner handles these queries fairly successfully. Hence the + default is OFF. + + + + + + RANDOM_PAGE_COST (floating point) + + + Sets the query optimizer's estimate of the cost of a + nonsequentially fetched disk page. This is measured as a + multiple of the cost of a sequential page fetch. + + + + + + + + + Unfortunately, there is no well-defined method of determining + ideal values for the family of COST variables that + were just described. You are encouraged to experiment and share + your findings. + + + + + + + Logging and Debugging + + + + + DEBUG_LEVEL (integer) + + + The higher this value is set, the more + debugging output of various sorts is generated + in the server log during operation. This option is 0 by + default, which means no debugging output. Values up to about 4 + currently make sense. + + + + + + DEBUG_PRINT_PARSE (boolean) + DEBUG_PRINT_PLAN (boolean) + DEBUG_PRINT_REWRITTEN (boolean) + DEBUG_PRINT_QUERY (boolean) + DEBUG_PRETTY_PRINT (boolean) + + + For any executed query, prints either the query, the parse + tree, the execution plan, or the query rewriter output to the + server log. selects are + nicer but longer output format. + + + + + + HOSTLOOKUP (boolean) + + + By default, connection logs only show the IP address of the + connecting host. If you want it to show the host name you can + turn this on, but depending on your host name resolution setup + it might impose a non-negligible performance penalty. This + option can only be set at server start. + + + + + + LOG_CONNECTIONS (boolean) + + + Prints a line informing about each successful connection to + the server log. This is off by default, although it is + probably very useful. This option can only be set at server + start. + + + + + + LOG_PID (boolean) + + + Prefixes each server log message with the process id of the + backend process. This is useful to sort out which messages + pertain to which connection. The default is off. + + + + + + LOG_TIMESTAMP (boolean) + + + Prefixes each server log message with a timestamp. The default + is off. + + + + + + SHOW_QUERY_STATS (boolean) + SHOW_PARSER_STATS (boolean) + SHOW_PLANNER_STATS (boolean) + SHOW_EXECUTOR_STATS (boolean) + + + For each query, write performance statistics of the respective + module to the server log. This is a crude profiling + instrument. + + + + + + SHOWPORTNUMBER (boolean) + + + Shows the port number of the connecting host in the connection + log messages. You could trace back the port number to find out + what user initiated the connection. Other than that it's + pretty useless and therefore off by default. This option can + only be set at server start. + + + + + + SYSLOG (integer) + + + Postgres allows the use of + syslog for logging. If this option + is set to 1, messages go both to syslog and the standard + output. A setting of 2 sends output only to syslog. (Some + messages will still go to the standard output/error.) The + default is 0, which means syslog is off. This option must be + set at server start. + + + To use syslog, the build of + Postgres must be configured with + the option. + + + + + + TRACE_NOTIFY (boolean) + + + Generates a great amount of debugging output for the + LISTEN and NOTIFY + commands. + + + + + + + + + General operation + + + + + DEADLOCK_TIMEOUT (integer) + + + Postgres assumes that if + transactions are stuck for this many milliseconds then a + deadlock has occurred. Although it is technically possible to + detect deadlocks properly, the present + optimistic approach is much more efficient in practice. If you get + too many deadlock detected messages when you provably did not + have one, you might want to try raising this value. The + default is 1000 (i.e., one second). This option can only be + set at server start. + + + + + + FSYNC (boolean) + + + When this is on (default), an fsync() + call is done after each transaction. Turning this off + increases performance but an operating system crash or power + outage might cause data corruption. (Note that a crash of + Postgres itself is not affected.) + + + + + + MAX_BACKENDS (integer) + + + Determines how many concurrent connections the database server + will allow. The default is 32. Note that there is also a + compiled-in hard limit on this option, which is currently + 1024. This parameter can only be set at server start. + + + + + + MAX_EXPR_DEPTH (integer) + + + Sets the maximum expression nesting depth that the parser will + accept. The default value is high enough for any normal query, + but you can raise it if you need to. (But if you raise it too + high, you run the risk of backend crashes due to stack + overflow.) + + + + + + NET_SERVER (boolean) + + + If this is true, then the server will accept TCP/IP + connections. Otherwise only local Unix domain socket + connections are accepted. It is off by default. This option + can only be set at server start. + + + + + + PORT (integer) + + + The TCP port the server listens on; 5432 by default. This + option can only be set at server start. + + + + + + SHMEM_BUFFERS (integer) + + + Sets the number of shared memory buffers the database server + will use. The default is 64. Each buffer is typically 8192 + bytes. This option can only be set at server start. + + + + + + SORT_MEM (integer) + + + Specifies the amount of memory to be used by internal sorts + and hashes before resorting to temporary disk files. The value + is specified in kilobytes, and defaults to 512 kilobytes. Note + that for a complex query, several sorts and/or hashes might be + running in parallel, and each one will be allowed to use as + much memory as this value specifies before it starts to put + data into temporary files. + + + + + + + + + Short options + + For convenience there are also single letter option switches + available for many parameters. They are described in the following + table. + + + Short option key + + + + + Short option + Equivalent + Remark + + + + + -B x + shmem_buffers = x + + + + -d x + debug_level = x + + + + -F + fsync = off + + + + -i + net_server = on + + + + -N x + max_backends = x + + + + -p x + port = x + + + + + -fi, -fh, -fm, -fn, -fs, -ft + enable_indexscan=off, enable_hashjoin=off, + enable_mergejoin=off, enable_nestloop=off, enable_seqscan=off, + enable_tidscan=off + * + + + -S x + sort_mem = x + * + + + -s + show_query_stats = on + * + + + -tpa, -tpl, -te + show_parser_stats=on, show_planner_stats=on, show_executor_stats=on + * + + + +
+ For historical reasons, options marked * must be + passed to the individual backend process via the + postmaster option, for example, + +> postmaster -o '-S 1024 -s' + + or via PGOPTIONS from the client side, as explained + above. + + + + + + + Shutting down the server + + + Depending on your needs, there are several ways to shut down the + database server when your work is done. The differentiation is + done by what signal you send to the server process. + + + SIGTERM + + + After receiving SIGTERM, the postmaster disallows new + connections but lets active backend end their work and shuts + down only after all of them terminated (by client request). + This is the Smart Shutdown. + + + + + + SIGINT + + + The postmaster disallows new connections, sends all active + backends SIGTERM (which will cause them to abort immediately), + waits for children to exit and shuts down the data base. This + is the Fast Shutdown. + + + + + + SIGQUIT + + + This is the Immediate Shutdown which + will cause the postmaster to send a SIGUSR1 to all backends and + exit immediately (without properly shutting down the database + system). When WAL is implemented, this will lead to recovery on + startup. Right now it's not recommendable to use this option. + + + + + + + + If at all possible, do not use SIGKILL to shut down the + postmaster. This can cause data corruption and will prevent the + cleaning up of shared memory resources, which you will have to + do yourself in that case. + + + + The PID of the postmaster process can be found using the + ps program, or from the file + postmaster.pid in the data directory. So for + example, to do a fast shutdown: + +> kill -INT `cat /usr/local/pgsql/data/postmaster.pid` + + + + The program pg_ctl is a shell script + wrapper that provides a convenient interface to these functions. + + + + + Secure TCP/IP Connection with SSH + + + Acknowledgement + + Idea taken from an email by Gene Selkov, Jr. + (selkovjr@mcs.anl.gov) written on 1999-09-08 in response + to a question from Eric Marsden. + + + + + One can use ssh to encrypt the network + connection between clients and a + Postgres server. Done properly, this + should lead to an adequately secure network connection. + + + + First make sure that an ssh server is + running properly on the same machine as + Postgres and that you can log in using + ssh as some user. Then you can establish a secure tunnel with a + command like this from the client machine: + +> ssh -L 3333:foo.com:5432 joe@foo.com + + The first number in the argument, 3333, is the + port number of your end of the tunnel; it can be chosen freely. 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 is the host with the database server you are going + to connect to. In order to connect to the database server using + this tunnel, you connect to port 3333 on the local machine: + +psql -h localhost -p 3333 template1 + + To the database server it will then look as though you are really + user joe@foo.com and it will use whatever + authentication procedure was set up for this user. In order for the + tunnel setup to succeed you must be allowed to connect via ssh as + joe@foo.com, just as if you had attempted to use ssh to set up a + terminal session. + + + + - - - Security - - - Database security is addressed at several levels: - - - - - Data base file protection. All files stored within the database - are protected from reading by any account other than the - Postgres superuser account. - - - - - 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 - -i option to allow non-local clients to connect. - - - - - Client connections can be restricted by IP address and/or user - name via the pg_hba.conf file in PG_DATA. - - - - - Client connections may be authenticated via other external packages. - - - - - Each user in Postgres is assigned a - username and (optionally) a password. By default, users do not - have write access to databases they did not create. - - - - - Users may be assigned to groups, and - table access may be restricted based on group privileges. - - - - - - - User Authentication - - - Authentication - is the process by which the backend server and - postmaster - ensure that the user requesting access to data is in fact who he/she - claims to be. - All users who invoke Postgres are checked against the - contents of the pg_user 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: - - - - - From the user shell - - - - A backend server started from a user shell notes the user's (effective) - user-id before performing a - setuid - to the user-id of user postgres. - The effective user-id is used - as the basis for access control checks. No other authentication is - conducted. - - - - - - - From the network - - - - If the Postgres system is built as distributed, - access to the Internet TCP port of the - postmaster - 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 pg_hba.conf(5) - 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 Postgres. - - - - - - - - Host-Based Access Control - - - Host-based access control - 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. - - - - Each database system contains a file named - pg_hba.conf, in its PGDATA - directory, which controls who can connect to each database. - - - - Every client accessing a database - must - be covered by one of - the entries in pg_hba.conf. - Otherwise all attempted connections from that - client will be rejected with a "User authentication failed" error - message. - - - - The general format of the pg_hba.conf - 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. - - - - 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: - - -local database authentication method - - - where - - - - database - specifies the database that this record applies to. The value - all - specifies that it applies to all databases. - - - authentication method - 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. - - - - - - Connections made using Internet domain sockets are controlled using records - of the following format. - - -host database TCP/IP address TCP/IP mask authentication method - - - - - The TCP/IP address - is logically anded to both the specified - TCP/IP mask - 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 - TCP/IP address - and the - TCP/IP mask - are specified in dotted decimal notation. - - - - If a connection fails to match any record then the - reject - authentication method is applied (see below). - - - - Authentication Methods - - - The following authentication methods are supported for both Unix and TCP/IP - domain sockets: - - - - trust - - - The connection is allowed unconditionally. - - - - - - reject - - - The connection is rejected unconditionally. - - - - - - crypt - - - The client is asked for a password for the user. This is sent encrypted - (using crypt(3)) - and compared against the password held in the - pg_shadow table. - If the passwords match, the connection is allowed. - - - - - - password - - - The client is asked for a password for the user. This is sent in clear - and compared against the password held in the - pg_shadow table. - If the passwords match, the connection is allowed. An optional password file - may be specified after the - password - keyword which is used to match the supplied password rather than the pg_shadow - table. See - pg_passwd. - - - - - - - - The following authentication methods are supported for TCP/IP - domain sockets only: - - - - krb4 - - - Kerberos V4 is used to authenticate the user. - - - - - - krb5 - - - Kerberos V5 is used to authenticate the user. - - - - - - ident - - - The ident server on the client is used to authenticate the user (RFC 1413). - An optional map name may be specified after the - ident - keyword which allows ident user names to be mapped onto - Postgres user names. - Maps are held in the file - $PGDATA/pg_ident.conf. - - - - - - - - - Examples - - - -# 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 - - - - - - - - User Names and Groups - - - To define a new user, run the - createuser utility program. - - - - 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 - Postgres these steps are not currently - supported with a create group command. Instead, - the groups are defined by inserting appropriate values into the - pg_group system table, and then using the - grant command to assign privileges to the - group. - - - - Creating Users - - - - - - - Creating Groups - - - Currently, there is no easy interface to set up user groups. You - have to explicitly insert/update the pg_group table. - For example: - - -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=> - - - - - The fields in pg_group are: - - - - groname - - - The group name. This a name and should be purely - alphanumeric. Do not include underscores or other punctuation. - - - - - - grosysid - - - The group id. This is an int4. This should be unique for - each group. - - - - - - grolist - - - The list of pg_user id's that belong in the group. This - is an int4[]. - - - - - - - - - Assigning Users to Groups - - - - - - - - - Access Control - - - Postgres provides mechanisms to allow users - to limit the access to their data that is provided to other users. - - - - - Database superusers - - - - Database super-users (i.e., users who have pg_user.usesuper - 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 pg_user.usecatupd set, and destruction of - system catalogs (or modification of their schemas) is never allowed. - - - - - - - Access Privilege - - - - The use of access privilege to limit reading, writing and setting - of rules on classes is covered in - grant/revoke(l). - - - - - - - Class removal and schema modification - - - - Commands that destroy or modify the structure of an existing class, - such as alter, - drop table, - and - drop index, - only operate for the owner of the class. As mentioned above, these - operations are never - permitted on system catalogs. - - - - - - - - - Functions and Rules - - - 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 trojan horse - 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 - pg_class, pg_user - and pg_group are also recommended. - - - - Functions - - - Functions written in any language except SQL - run inside the backend server - process with the permissions of the user postgres (the - backend server runs with its real and effective user-id set to - postgres. 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. - - - - - Rules - - - Like SQL functions, rules always run with the identity and - permissions of the user who invoked the backend server. - - - - - Caveats - - - There are no plans to explicitly support encrypted data inside of - Postgres - (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. - - - User names, group names and associated system identifiers (e.g., the - contents of pg_user.usesysid) are assumed to be unique - throughout a database. Unpredictable results may occur if they are - not. - - - - - - Secure TCP/IP Connection - - - - Author - - From e-mail by - Gene Selkov, Jr. - written on 1999-09-08 in response to a - question from Eric Marsden. - - - - - - One can use ssh to encrypt the network - connection between clients and a - Postgres server. Done properly, this - should lead to an adequately secure network connection. - - - - The documentation for ssh provides most - of the information to get started. - Please refer to - http://www.heimhardt.de/htdocs/ssh.html - for better insight. - - - - A step-by-step explanation can be done in just two steps. - - - - Running a secure tunnel via ssh - - - A step-by-step explanation can be done in just two steps. - - - - - Establish a tunnel to the backend machine, like this: - - -ssh -L 3333:wit.mcs.anl.gov:5432 postgres@wit.mcs.anl.gov - - - 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. - - - - - - 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 - psql, you will need another shell - because the shell session you used in - is now occupied with - ssh. - - -psql -h localhost -p 3333 -d mpw - - - Note that you have to specify the 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. - - - - - - - diff --git a/doc/src/sgml/signals.sgml b/doc/src/sgml/signals.sgml deleted file mode 100644 index 7f7e597e0b..0000000000 --- a/doc/src/sgml/signals.sgml +++ /dev/null @@ -1,266 +0,0 @@ - - - - -Massimo -Dal Zotto - - -Transcribed 1998-10-16 - - -<productname>Postgres</productname> Signals - - - - -Contributed by Massimo Dal Zotto - - - - - -Postgres uses the following signals for - communication between the postmaster and backends: - - - - -<productname>Postgres</productname> Signals -Signals - - - - - -Signal - - -postmaster Action - - -Server Action - - - - - - - -SIGHUP - - -kill(*,sighup) - - -read_pg_options - - - - - -SIGINT - - -die - - -cancel query - - - - - -SIGQUIT - - -kill(*,sigterm) - - -handle_warn - - - - - -SIGTERM - - -kill(*,sigterm), kill(*,9), die - - -die - - - - - -SIGPIPE - - -ignored - - -die - - - - - -SIGUSR1 - - -kill(*,sigusr1), die - - -quickdie - - - - - -SIGUSR2 - - -kill(*,sigusr2) - - -async notify (SI flush) - - - - - -SIGCHLD - - -reaper - - -ignored (alive test) - - - - - -SIGTTIN - - -ignored - - - - - - - -SIGTTOU - - -ignored - - - - - - - -SIGCONT - - -dumpstatus - - - - - - - -SIGFPE - - - - -FloatExceptionHandler - - - - - -
- - - -"kill(*,signal)" means sending a signal to all backends. - - - - - -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. - - - -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. - - - -The typical use of signals by programmers could be the following: - - -# stop postgres -kill -TERM $postmaster_pid - - - -# kill all the backends -kill -QUIT $postmaster_pid - - - -# kill only the postmaster -kill -INT $postmaster_pid - - - -# change pg_options -cat new_pg_options > $DATA_DIR/pg_options -kill -HUP $postmaster_pid - - - -# 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 - - - - - diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index 0e6bd867c3..939100ff54 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -1,28 +1,10 @@ - - Adding and Deleting Users - - - createuser enables specific users to access - Postgres. - dropuser removes users and - prevents them from accessing Postgres. - - - - These commands only affect users with respect to - Postgres; - they have no effect on a user's other privileges or status with regards - to the underlying operating system. - - - Disk Management diff --git a/doc/src/sgml/trouble.sgml b/doc/src/sgml/trouble.sgml deleted file mode 100644 index 3e3d962241..0000000000 --- a/doc/src/sgml/trouble.sgml +++ /dev/null @@ -1,289 +0,0 @@ - - - - Troubleshooting - - - Postmaster Startup Failures - - - 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: - - - - -FATAL: StreamServerPort: bind() failed: Address already in use - Is another postmaster already running on that port? - - 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 - -$ postmaster -i -p 666 -FATAL: StreamServerPort: bind() failed: Permission denied - Is another postmaster already running on that port? - - - - - -IpcMemoryCreate: shmget failed (Invalid argument) key=5440001, size=83918612, permission=600 -FATAL 1: ShmemCreate: cannot create region - - 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. - - - - -IpcSemaphoreCreate: semget failed (No space left on device) key=5440026, num=16, permission=600 - - A message like this does not 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. - - - - - - Client Connection Problems - - - 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. - - - - -connectDB() -- connect() failed: Connection refused -Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'? - - 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: - -connectDB() -- connect() failed: No such file or directory -Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'? - - 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 not 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. - - - - -No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb - - 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. - - - - -Password authentication failed for user 'joeblow' - - 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. - - - - -FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow' - - This is another variant of authentication failure: no Postgres create_user - command has been executed for the given username. - - - - -FATAL 1: Database testdb does not exist in pg_database - - 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. - - - - -NOTICE: Unrecognized variable client_encoding - - 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. - - - - - - Debugging Messages - - - The postmaster occasionally prints out - messages which - are often helpful during troubleshooting. If you wish - to view debugging messages from the postmaster, - you can - start it with the -d option and redirect the output to - the log file: - - -% postmaster -d > pm.log 2>&1 & - - - If you do not wish to see these messages, you can type - -% postmaster -S - - and the postmaster will be "S"ilent. - No ampersand ("&") is required in this case, since the postmaster - automatically detaches from the terminal when -S is specified. - - - - pg_options - - - - - Contributed by Massimo Dal Zotto - - - - - The optional file data/pg_options 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 - Postgres. - The options specified in this file may be debugging flags used by the trace - package (backend/utils/misc/trace.c) or numeric - parameters which can be used by the backend to control its behaviour. - New options and parameters must be defined in - backend/utils/misc/trace.c and - backend/include/utils/trace.h. - - - - pg_options can also be specified with the switch of - Postgres: - - -postgres options -T "verbose=2,query,hostlookup-" - - - - - The functions used for printing errors and debug messages can now make use - of the syslog(2) facility. Message printed to stdout - or stderr are prefixed by a timestamp containing also the backend pid: - - -#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 - - - - - 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. - - - - 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 printf() - 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. - - - - The format of the pg_options file is as follows: - - -# comment -option=integer_value # set value for option -option # set option = 1 -option+ # set option = 1 -option- # set option = 0 - - - Note that keyword can also be - an abbreviation of the option name defined in - backend/utils/misc/trace.c. - - - - Refer to - for a complete list of option keywords and possible values. - - - - - - diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml new file mode 100644 index 0000000000..255b5f9801 --- /dev/null +++ b/doc/src/sgml/user-manag.sgml @@ -0,0 +1,202 @@ + + Database User and Permission Management + + + 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. + + + + Database Users + + + 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 CREATE + USER SQL command: + +CREATE USER name + + name follows the rules for SQL + identifiers: either unadorned without special characters, or + double-quoted. To remove an existing user, use the analog + DROP USER command. + + + + For convenience, the shell scripts createuser + and dropuser are wrappers around these SQL + commands. + + + + 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 postgres + exists. In order to create more users you have to first connect as + this initial user. + + + + 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 + psql program uses the + 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 + . (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.) + + + + User attributes + + + A database user may have a number of attributes that define its + privileges and interact with the client authentication system. + + + + superuser + + + A database superuser bypasses all permission checks. Also, + only a superuser can create new users. To create a database + superuser, use CREATE USER name + CREATEUSER. + + + + + + database creation + + + 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 CREATE USER name + CREATEDB. + + + + + + password + + + 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 CREATE USER name WITH PASSWORD + 'string'. + + + + + + See the reference pages for CREATE USER and + ALTER USER for details. + + + + + + Groups + + + As in Unix, groups are a way of logically grouping users. To create + a group, use + +CREATE GROUP name + + To add users to or remove users from a group, respectively, user + +ALTER GROUP name ADD USER uname1, ... +ALTER GROUP name DROP USER uname1, ... + + + + + + Privileges + + + 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, + privileges must be granted. + + + + Currently, there are four different privileges: select (read), + insert (append), and update/delete (write), as well as + RULE, 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 + GRANT command is used. So, if + joe is an existing user, and + accounts is an existing table, write access can + be granted with + +GRANT UPDATE ON accounts TO joe; + + The user executing this command must be the owner of the table. To + grant a privilege to a group, use + +GRANT SELECT ON accounts TO GROUP staff; + + The special user name PUBLIC can + be used to grant a privilege to every user on the system. Using + ALL in place of a privilege specifies that all + privileges will be granted. + + + + To revoke a privilege, use the fittingly named + REVOKE command: + +REVOKE ALL ON accounts FROM PUBLIC; + + The set of privileges held by the table owner is always implicit + and is never revokable. + + + + + Functions and Triggers + + + 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 trojan horse + 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 pg_class, + pg_user and pg_group are also + possible. + + + + 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. + + + + +