Support Docs & Contrib

1 files changed, 279 insertions, 0 deletions

diff --git a/doc/man/unix.1 b/doc/man/unix.1
new file mode 100644
index 00000000000..cc33492dfc1
--- /dev/null
+++ b/doc/man/unix.1
@@ -0,0 +1,279 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/man/Attic/unix.1,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
+.TH INTRODUCTION UNIX 11/05/95 Postgres95 Postgres95
+.SP INFORMATION UNIX 11/05/95
+.BH "SECTION 2 \(em Unix COMMANDS (Unix)"
+.SH "OVERVIEW"
+This section outlines the interaction between Postgres and
+the operating system.  In particular, this section describes 
+the Postgres support programs that are executable as Unix
+commands.
+.SH TERMINOLOGY
+In the following documentation, the term
+.IR site
+may be interpreted as the host machine on which Postgres is installed.
+Since it is possible to install more than one set of Postgres
+databases on a single host, this term more precisely denotes any
+particular set of installed Postgres binaries and databases.
+.PP
+The 
+.IR "Postgres super-user"
+is the user named \*(lqpostgres\*(rq who owns the Postgres
+binaries and database files.  As the database super-user, all
+protection mechanisms may be bypassed and any data accessed
+arbitrarily.  In addition, the Postgres super-user is allowed to execute
+some support programs which are generally not available to all users.
+Note that the Postgres super-user is
+.IR not
+the same as the Unix super-user,
+.IR root ,
+and should have a non-zero userid for security reasons.
+.PP
+The
+.IR "database base administrator"
+or DBA, is the person who is responsible for installing Postgres to
+enforce a security policy for a site.  The DBA can add new users by
+the method described below 
+and maintain a set of template databases for use by
+.IR createdb (1).
+.PP
+The
+.IR postmaster
+is the process that acts as a clearing-house for requests to the Postgres
+system.
+Frontend applications connect to the 
+.IR postmaster ,
+which keeps tracks of any system errors and communication between the
+backend processes.  The
+.IR postmaster
+can take several command-line arguments to tune its behavior.
+However,
+supplying arguments is necessary only if you intend to run multiple
+sites or a non-default site.  See
+.IR postmaster (1)
+for details.
+.PP
+The
+.IR "Postgres backend"
+(the actual executable program called "postgres") may be executed
+directly from the user shell by the 
+Postgres super-user (with the database name as an argument).  However,
+doing this bypasses the shared buffer pool and lock table associated
+with a postmaster/site, therefore this is not recommended in a multiuser
+site.
+.SH NOTATION
+\*(lq.../\*(rq at the front of a file name is used to represent the
+path to the Postgres super-user's home directory.  Anything in brackets
+(\*(lq[\*(rq and \*(lq]\*(rq) is optional.  Anything in braces
+(\*(lq{\*(rq and \*(lq}\*(rq) can be repeated 0 or more times.
+Parentheses (\*(lq(\*(rq and \*(lq)\*(rq ) are used to group boolean
+expressions.  \*(lq|\*(rq is the boolean operator
+.SM OR .
+.SH "USING Postgres FROM Unix"
+All Postgres commands that are executed directly from a Unix shell are
+found in the directory \*(lq.../bin\*(rq.  Including this directory in
+your search path will make executing the commands easier.
+.PP
+A collection of system catalogs exist at each site.  These include a
+class (\*(lqpg_user\*(rq) 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.
+.SH "Security"
+.SP SECURITY UNIX 03/12/94
+.SH "USER AUTHENTICATION"
+.IR Authentication
+is the process by which the backend server and 
+.IR 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 \*(lqpg_user\*(rq 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.
+.SS "From the user shell"
+A backend server started from a user shell notes the user's (effective)
+user-id before performing a 
+.IR setuid (3)
+to the user-id of user \*(lqpostgres\*(rq.  The effective user-id is used
+as the basis for access control checks.  No other authentication is
+conducted.
+.SS "From the network"
+If the Postgres system is built as distributed, access to the Internet
+TCP port of the
+.IR postmaster
+process is available to anyone.  However, Postgres offers optional
+host-based authentication where only access from certain hosts are
+allowed.  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.
+.PP
+If greater security is desired, Postgres and its clients may be
+modified to use a network authentication system.  For example, the
+.IR postmaster ,
+.IR psql
+and the
+.IR libpq
+library have already been configured to use either Version 4 or Version 5 of
+the
+.IR Kerberos
+authentication system from the Massachusetts Institute of Technology.
+For more information on using
+.IR Kerberos
+with Postgres, see the appendix below.
+.SH "ACCESS CONTROL"
+Postgres provides mechanisms to allow users to limit the access to
+their data that is provided to other users.
+.SS "Database superusers"
+Database super-users (i.e., users who have \*(lqpg_user.usesuper\*(rq
+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 \*(lqpg_user.usecatupd\*(rq set, and destruction of
+system catalogs (or modification of their schemas) is never allowed.
+.SS "Access Privilege
+The use of access privilege to limit reading, writing and setting
+of rules on classes is covered in
+.IR "grant/revoke" (l).
+.SS "Class removal and schema modification"
+Commands that destroy or modify the structure of an existing class,
+such as
+.IR "alter" ,
+.IR "drop table" ,
+and
+.IR "drop index" ,
+only operate for the owner of the class.  As mentioned above, these
+operations are
+.BR never
+permitted on system catalogs.
+.SH "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
+.BR "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
+\*(lqpg_class\*(rq, \*(lqpg_user\*(rq and \*(lqpg_group\*(rq are also
+recommended.
+.SS "Functions"
+Functions written in any language except SQL 
+run inside the backend server
+process with the permissions of the user \*(lqpostgres\*(rq (the
+backend server runs with its real and effective user-id set to
+\*(lqpostgres\*(rq).  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.
+.SS "Rules"
+Like SQL functions, rules always run with the identity and
+permissions of the user who invoked the backend server.
+.SH "SEE ALSO"
+postmaster(1),
+alter(l),
+insert(l),
+grant/revoke(l),
+copy(l),
+create(l),
+delete(l),
+drop table(l),
+drop index(l),
+drop rule(l),
+update(l),
+select(l),
+kerberos(1),
+kinit(1),
+kerberos(3)
+.SH CAVEATS 
+.PP
+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.
+.PP
+User names, group names and associated system identifiers (e.g., the
+contents of \*(lqpg_user.usesysid\*(rq) are assumed to be unique
+throughout a database.  Unpredictable results may occur if they are
+not.
+.SH "APPENDIX: USING KERBEROS"
+.SS "Availability"
+The
+.IR Kerberos
+authentication system is not distributed with Postgres, nor is it
+available from the University of California at Berkeley.  Versions of
+.IR Kerberos
+are typically available as optional software from operating system
+vendors.  In addition, a source code distribution may be obtained
+through MIT Project Athena by anonymous FTP from ATHENA-DIST.MIT.EDU
+(18.71.0.38).  (You may wish to obtain the MIT version even if your
+vendor provides a version, since some vendor ports have been
+deliberately crippled or rendered non-interoperable with the MIT
+version.)  Users located outside the United States of America and
+Canada are warned that distribution of the actual encryption code in
+.IR Kerberos
+is restricted by U. S. government export regulations.
+.PP
+Any additional inquiries should be directed to your vendor or MIT
+Project Athena (\*(lqinfo-kerberos@ATHENA.MIT.EDU\*(rq).  Note that FAQLs
+(Frequently-Asked Questions Lists) are periodically posted to the
+.IR Kerberos
+mailing list, \*(lqkerberos@ATHENA.MIT.EDU\*(rq (send mail to
+\*(lqkerberos-request@ATHENA.MIT.EDU\*(rq to subscribe), and USENET
+news group, \*(lqcomp.protocols.kerberos\*(rq.
+.SS "Installation"
+Installation of 
+.IR Kerberos
+itself is covered in detail in the 
+.IR "Kerberos Installation Notes" .
+Make sure that the server key file (the
+.IR srvtab
+or
+.IR keytab )
+is somehow readable by user \*(lqpostgres\*(rq.
+.PP
+Postgres and its clients can be compiled to use either Version 4 or
+Version 5 of the MIT
+.IR Kerberos
+protocols by setting the 
+.SM KRBVERS
+variable in the file \*(lq.../src/Makefile.global\*(rq to the
+appropriate value.  You can also change the location where Postgres
+expects to find the associated libraries, header files and its own
+server key file.
+.PP
+After compilation is complete, Postgres must be registered as a
+.IR Kerberos
+service.  See the
+.IR "Kerberos Operations Notes"
+and related manual pages for more details on registering services.
+.SS "Operation"
+After initial installation, Postgres should operate in all ways as a
+normal
+.IR Kerberos
+service.  For details on the use of authentication, see the manual
+pages for 
+.IR postmaster (1)
+and 
+.IR psql (1).
+.PP
+In the 
+.IR Kerberos
+Version 5 hooks, the following assumptions are made about user
+and service naming: (1) user principal names (anames) are assumed to
+contain the actual Unix/Postgres user name in the first component; (2)
+the Postgres service is assumed to be have two components, the service
+name and a hostname, canonicalized as in Version 4 (i.e., all domain
+suffixes removed).
+.PP
+.nf
+user example: frew@S2K.ORG
+user example: aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
+host example: postgres_dbms/ucbvax@S2K.ORG
+.fi
+.PP
+Support for Version 4 will disappear sometime after the production
+release of Version 5 by MIT.