.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` . ds C' 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PG_CREATECLUSTER 8" .TH PG_CREATECLUSTER 8 "2012-10-08" "Debian" "Debian PostgreSQL infrastructure" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" pg_createcluster \- create a new PostgreSQL cluster .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBpg_createcluster\fR [\fIoptions\fR] \fIversion\fR \fIname\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBpg_createcluster\fR creates a new PostgreSQL server cluster (i. e. a collection of databases served by a \fIpostmaster\fR\|(1) instance) and integrates it into the multi\-version/multi\-cluster architecture of the \&\fBpostgresql-common\fR package. .PP Every cluster is uniquely identified by its version and name. The name can be arbitrary. The default cluster that is created on installation of a server package is \f(CW\*(C`main\*(C'\fR. However, you might wish to create other clusters for testing, with other superusers, a cluster for each user on a shared server, etc. \f(CW\*(C`pg_createcluster\*(C'\fR will abort with an error if you try to create a cluster with a name that already exists for that version. .PP Given a major PostgreSQL \fIversion\fR (like \*(L"8.2\*(R" or \*(L"8.3\*(R") and a cluster \&\fIname\fR, it creates the necessary configuration files in \&\f(CW\*(C`/etc/postgresql/\*(C'\fR\fIversion\fR\f(CW\*(C`/\*(C'\fR\fIname\fR\f(CW\*(C`/\*(C'\fR; in particular these are \&\f(CW\*(C`postgresql.conf\*(C'\fR, \f(CW\*(C`pg_ident.conf\*(C'\fR, \f(CW\*(C`pg_hba.conf\*(C'\fR, a postgresql-common specific configuration file \f(CW\*(C`start.conf\*(C'\fR (see \fB\s-1STARTUP\s0 \s-1CONTROL\s0\fR below), \&\f(CW\*(C`pg_ctl.conf\*(C'\fR, and a symbolic link \f(CW\*(C`log\*(C'\fR which points to the log file (by default, \f(CW\*(C`/var/log/postgresql/postgresql\-\*(C'\fR\fIversion\fR\f(CW\*(C`\-\*(C'\fR\fIname\fR\f(CW\*(C`.log\*(C'\fR). .PP \&\f(CW\*(C`postgresql.conf\*(C'\fR is automatically adapted to use the next available port, i. e. the first port (starting from 5432) which is not yet used by an already existing cluster. .PP If the data directory does not yet exist, PostgreSQL's \fIinitdb\fR\|(1) command is used to generate a new cluster structure. If the data directory already exists, it is integrated into the \fBpostgresql-common\fR structure by moving the configuration file and setting the data_directory option. Please note that this \&\fIonly\fR works for data directories which were created directly with \fBinitdb\fR, i. e. all the configuration files (\f(CW\*(C`postgresql.conf\*(C'\fR etc.) must be present in the data directory. .PP If a custom socket directory is given and it does not exist, it is created. .PP If the log file does not exist, it is created. In any case the permissions are adjusted to allow write access to the cluster owner. Please note that \&\f(CW\*(C`postgresql.conf\*(C'\fR can be customized to specify \f(CW\*(C`log_directory\*(C'\fR and/or \&\f(CW\*(C`log_filename\*(C'\fR; if at least one of these options is present, then the symbolic link \f(CW\*(C`log\*(C'\fR in the cluster configuration directory is ignored. .PP If the default snakeoil \s-1SSL\s0 certificate exists (\f(CW\*(C`/etc/ssl/certs/ssl\-cert\-snakeoil.pem\*(C'\fR and \&\f(CW\*(C`/etc/ssl/private/ssl\-cert\-snakeoil.key\*(C'\fR), this program creates symlinks to these files in the data directory (\f(CW\*(C`server.crt\*(C'\fR and \f(CW\*(C`server.key\*(C'\fR) and enables \&\s-1SSL\s0 for that cluster (option \fBssl\fR in \f(CW\*(C`postgresql.conf\*(C'\fR). Therefore all clusters will use the same \s-1SSL\s0 certificate by default. Of course you can replace these symlinks with a cluster specific certificate. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-u\fR \fIuser\fR, \fB\-\-user=\fR\fIuser\fR" 4 .IX Item "-u user, --user=user" Set the user who owns the cluster and becomes the database superuser to the given name or uid. By default, this is the user \fBpostgres\fR. A cluster must not be owned by root. .IP "\fB\-g\fR \fIgroup\fR, \fB\-\-group=\fR\fIgroup\fR" 4 .IX Item "-g group, --group=group" Change the group of the cluster related data files. By default this will be the primary group of the database owner. .IP "\fB\-d\fR \fIdir\fR, \fB\-\-datadir=\fR\fIdir\fR" 4 .IX Item "-d dir, --datadir=dir" Explicitly set the data directory path, which is used to store all the actual databases and tables. This will become quite big (easily in the order of five times the amount of actual data stored in the cluster). Defaults to \&\f(CW\*(C`/var/lib/postgresql/\*(C'\fR\fIversion\fR\f(CW\*(C`/\*(C'\fR\fIcluster\fR. .IP "\fB\-s\fR \fIdir\fR, \fB\-\-socketdir=\fR\fIdir\fR" 4 .IX Item "-s dir, --socketdir=dir" Explicitly set the directory where the \fIpostmaster\fR\|(1) server stores the Unix socket for local connections. Defaults to \f(CW\*(C`/var/run/postgresql/\*(C'\fR for clusters owned by the user \fBpostgres\fR, and \f(CW\*(C`/tmp\*(C'\fR for clusters owned by other users. Please be aware that \f(CW\*(C`/tmp\*(C'\fR is an unsafe directory since everybody can create a socket there and impersonate the database server. If the given directory does not exist, it is created with appropriate permissions. .IP "\fB\-l\fR \fIpath\fR, \fB\-\-logfile=\fR\fIpath\fR" 4 .IX Item "-l path, --logfile=path" Explicitly set the path for the \fIpostmaster\fR\|(1) server log file. Defaults to \&\f(CW\*(C`/var/log/postgresql/postgresql\-\*(C'\fR\fIversion\fR\f(CW\*(C`\-\*(C'\fR\fIcluster\fR\f(CW\*(C`.log\*(C'\fR. .IP "\fB\-\-locale=\fR\fIlocale\fR" 4 .IX Item "--locale=locale" Set the default locale for the database cluster. If this option is not specified, the locale is inherited from the environment that \&\fBpg_createcluster\fR runs in. .IP "\fB\-\-lc\-collate=\fR\fIlocale\fR" 4 .IX Item "--lc-collate=locale" .PD 0 .IP "\fB\-\-lc\-ctype=\fR\fIlocale\fR" 4 .IX Item "--lc-ctype=locale" .IP "\fB\-\-lc\-messages=\fR\fIlocale\fR" 4 .IX Item "--lc-messages=locale" .IP "\fB\-\-lc\-monetary=\fR\fIlocale\fR" 4 .IX Item "--lc-monetary=locale" .IP "\fB\-\-lc\-numeric=\fR\fIlocale\fR" 4 .IX Item "--lc-numeric=locale" .IP "\fB\-\-lc\-time=\fR\fIlocale\fR" 4 .IX Item "--lc-time=locale" .PD Like \fB\-\-locale\fR, but only sets the locale in the specified category. .IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding=\fR\fIencoding\fR" 4 .IX Item "-e encoding, --encoding=encoding" Select the encoding of the template database. This will also be the default encoding of any database you create later, unless you override it there. The default is derived from the locale, or \s-1SQL_ASCII\s0 if that does not work. The character sets supported by the PostgreSQL server are described in the documentation. .Sp \&\fBNote\fR: It is not recommended to set this option directly! Set the locale instead. .IP "\fB\-p\fR \fIport\fR, \fB\-\-port=\fR\fIport\fR" 4 .IX Item "-p port, --port=port" Select the port the new cluster listens on (for the Unix socket and the \s-1TCP\s0 port); this must be a number between 1024 and 65535, since PostgreSQL does not run as root and thus needs an unprivileged port number. By default the next free port starting from 5432 is assigned. .IP "\fB\-\-start\fR" 4 .IX Item "--start" Immediately start a server for the cluster after creating it (i. e. call \&\f(CW\*(C`pg_ctlcluster\*(C'\fR \fIversion cluster\fR \f(CW\*(C`start\*(C'\fR on it). By default, the cluster is not started. .IP "\fB\-\-start\-conf=\fR\fBauto\fR|\fBmanual\fR|\fBdisabled\fR" 4 .IX Item "--start-conf=auto|manual|disabled" Set the initial value in the \f(CW\*(C`start.conf\*(C'\fR configuration file. See \fB\s-1STARTUP\s0 \&\s-1CONTROL\s0\fR below. By default, \fBauto\fR is used, which means that the cluster is handled by \f(CW\*(C`/etc/init.d/postgresql\*(C'\fR, i. e. starts and stops automatically on system boot. .SH "STARTUP CONTROL" .IX Header "STARTUP CONTROL" The \f(CW\*(C`start.conf\*(C'\fR file in the cluster configuration directory controls the start/stop behavior of that cluster's postmaster process. The file can contain comment lines (started with '#'), empty lines, and must have exactly one line with one of the following keywords: .IP "\fBauto\fR" 4 .IX Item "auto" The postmaster process is started/stopped automatically in the init script. This is also the default if the file is missing. .IP "\fBmanual\fR" 4 .IX Item "manual" The postmaster process is not handled by the init script, but manually controlling the cluster with \fIpg_ctlcluster\fR\|(1) is permitted. .IP "\fBdisabled\fR" 4 .IX Item "disabled" Neither the init script nor \fIpg_ctlcluster\fR\|(1) are permitted to start/stop the cluster. Please be aware that this will not stop the cluster owner from calling lower level tools to control the postmaster process; this option is only meant to prevent accidents during maintenance, not more. .Sp The \f(CW\*(C`pg_ctl.conf\*(C'\fR file in the cluster configuration directory can contain additional options passed to pg_ctl of that cluster. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIpg_ctlcluster\fR\|(8), \fIpg_lsclusters\fR\|(1), \fIpg_wrapper\fR\|(1) .SH "AUTHOR" .IX Header "AUTHOR" Martin Pitt