Make -w the default for shut down, add -W option to specify no wait.

Add -l option to name log file.  Set umask to 077.
Proper file descriptor redirection to allow postmaster to detach from
shell's process group.
Add -s option to turn off informational messages.
This commit is contained in:
Peter Eisentraut 2001-02-08 19:39:24 +00:00
parent e58775ee75
commit 088c0b9546
2 changed files with 244 additions and 162 deletions

View File

@ -1,11 +1,11 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.5 2000/12/25 23:15:26 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere Exp $
Postgres documentation
-->
<refentry id="app-pg-ctl">
<docinfo>
<date>2000-11-25</date>
<date>2001-02-08</date>
</docinfo>
<refmeta>
@ -25,12 +25,13 @@ Postgres documentation
<arg choice="plain">start</arg>
<arg>-w</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-p <replaceable>path</replaceable></arg>
<arg>-l <replaceable>filename</replaceable></arg>
<arg>-o <replaceable>options</replaceable></arg>
<arg>-p <replaceable>path</replaceable></arg>
<sbr>
<command>pg_ctl</command>
<arg choice="plain">stop</arg>
<arg>-w</arg>
<arg>-W</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-m
<group choice="plain">
@ -64,8 +65,52 @@ Postgres documentation
<title>Description</title>
<para>
<application>pg_ctl</application> is a utility for starting,
stopping, or restarting the <xref linkend="app-postmaster">, or
displaying the status of a running postmaster.
stopping, or restarting <xref linkend="app-postmaster">, the
<productname>PostgreSQL</productname> backend server, or displaying
the status of a running postmaster. Although the postmaster can be
started manually, <application>pg_ctl</application> encapulates
tasks such as redirecting log output, properly detaching from the
terminal and process group, and additionally provides an option for
controlled shut down.
</para>
<para>
In <option>start</option> mode, a new postmaster is launched. The
server is started in the background, the standard input attached to
<filename>/dev/null</filename>. The standard output and standard
error are either appended to a log file, if the <option>-l</option>
option is used, or are redirected to
<application>pg_ctl</application>'s standard output (not standard
error). If no log file is chosen, the standard output of
<application>pg_ctl</application> should be redirected to a file or
piped to another process, for example a log rotating program,
otherwise the postmaster will write its output the the controlling
terminal (from the background) and will not leave the shell's
process group.
</para>
<para>
In <option>stop</option> mode, the postmaster that is running on
the specified data directory is shut down. Three different
shutdown methods can be selected with the <option>-m</option>
option: <quote>Smart</quote> mode waits for all the clients to
disconnect. This is the default. <quote>Fast</quote> mode does
not wait for clients to disconnect. All active transactions will
be rolled back. <quote>Immediate</quote> mode will abort without
complete shutdown. This will lead to a recovery run on restart.
By the default, stop mode waits for the shutdown to complete.
</para>
<para>
<option>restart</option> mode effectively executes a stop followed
by a start. This allows the changing of postmaster command line
options.
</para>
<para>
<option>status</option> mode checks whether a postmaster is running
and if so displays the <acronym>PID</acronym> and the command line
options that were used to invoke it.
</para>
<refsect2 id="app-pg-ctl-options">
@ -73,18 +118,6 @@ Postgres documentation
<para>
<variablelist>
<varlistentry>
<term>-w</term>
<listitem>
<para>
Wait for the database server to come up, by watching for
creation of the pid file
(<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
Times out after 60 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D <replaceable class="parameter">datadir</replaceable></term>
<listitem>
@ -97,15 +130,25 @@ Postgres documentation
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">path</replaceable></term>
<term>-l <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Specifies the location of the <filename>postmaster</filename>
executable. By default the postmaster is taken from the same
directory as pg_ctl, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
that the postmaster was not found.
Append the server log output to
<replaceable>filename</replaceable>. If the file does not
exist, it is created. The umask is set to 077, so access to
the log file from other users is disallowed by default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-m <replaceable class="parameter">mode</replaceable></term>
<listitem>
<para>
Specifies the shutdown mode. <replaceable>mode</replaceable>
may be <literal>smart</literal>, <literal>fast</literal>, or
<literal>immediate</literal>, or the first letter of one of
these three.
</para>
</listitem>
</varlistentry>
@ -125,82 +168,35 @@ Postgres documentation
</varlistentry>
<varlistentry>
<term>-m <replaceable class="parameter">mode</replaceable></term>
<term>-p <replaceable class="parameter">path</replaceable></term>
<listitem>
<para>
Specifies the shutdown mode.
<variablelist>
<varlistentry>
<term>smart</term>
<term>s</term>
<listitem>
<para>
Smart mode waits for all the clients to disconnect. This
is the default.
Specifies the location of the <filename>postmaster</filename>
executable. By default the postmaster is taken from the same
directory as pg_ctl, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
that the postmaster was not found.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fast</term>
<term>f</term>
<term>-w</term>
<listitem>
<para>
Fast mode does not wait for clients to disconnect. All
active transactions will be rolled back.
Wait for the start or stutdown to complete. Times out after
60 seconds. This is the default for shutdowns.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>immediate</term>
<term>i</term>
<term>-W</term>
<listitem>
<para>
Immediate mode will abort without complete shutdown. This
will lead to a recovery run on restart.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>start</term>
<listitem>
<para>
Start up <application>postmaster</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>stop</term>
<listitem>
<para>
Shut down <application>postmaster</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>restart</term>
<listitem>
<para>
Stop the <application>postmaster</application>, if one is running,
and then start it again.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>status</term>
<listitem>
<para>
Show the current state of <application>postmaster</application>.
Do not wait for start or shutdown to complete. This is the
default for starts and restarts.
</para>
</listitem>
</varlistentry>
@ -223,7 +219,7 @@ Postgres documentation
<refsect1 id="R1-APP-PGCTL-2">
<title>Usage</title>
<title>Examples</title>
<refsect2 id="R2-APP-PGCTL-3">
<title>Starting the postmaster</title>
@ -260,7 +256,6 @@ Postgres documentation
</screen>
stops postmaster. Using the <option>-m</option> switch allows one
to control <emphasis>how</emphasis> the backend shuts down.
<option>-w</option> waits for postmaster to shut down.
</para>
</refsect2>
@ -312,6 +307,25 @@ Command line was:
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>
Waiting for complete start is not a well-defined operation and may
fail if access control is set up in way that a local client cannot
connect without manual interaction. It should be avoided.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View File

@ -4,11 +4,11 @@
# pg_ctl.sh--
# Start/Stop/Restart/Report status of postmaster
#
# Copyright (c) 2000, PostgreSQL Global Development Group
# Copyright (c) 2001 PostgreSQL Global Development Group
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.17 2000/12/30 06:10:43 ishii Exp $
# $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.18 2001/02/08 19:39:24 petere Exp $
#
#-------------------------------------------------------------------------
@ -19,20 +19,29 @@ $CMDNAME is a utility to start, stop, restart, and report the status
of a PostgreSQL server.
Usage:
$CMDNAME start [-w] [-D DATADIR] [-p PATH-TO-POSTMASTER] [-o \"OPTIONS\"]
$CMDNAME stop [-w] [-D DATADIR] [-m SHUTDOWN-MODE]
$CMDNAME restart [-w] [-D DATADIR] [-m SHUTDOWN-MODE] [-o \"OPTIONS\"]
$CMDNAME start [-w] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]
$CMDNAME stop [-W] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]
$CMDNAME restart [-w] [-D DATADIR] [-s] [-m SHUTDOWN-MODE] [-o \"OPTIONS\"]
$CMDNAME status [-D DATADIR]
Options:
Common options:
-D DATADIR Location of the database storage area
-m SHUTDOWN-MODE May be 'smart', 'fast', or 'immediate'
-s Only print errors, no informational messages
-w Wait until operation completes
-W Do not wait until operation completes
(The default is to wait for shutdown, but not for start or restart.)
If the -D option is omitted, the environment variable PGDATA is used.
Options for start or restart:
-l FILENAME Write (or append) server log to FILENAME. The
use of this option is highly recommended.
-o OPTIONS Command line options to pass to the postmaster
(PostgreSQL server executable)
-p PATH-TO-POSTMASTER Normally not necessary
-w Wait until operation completes
If the -D option is omitted, the environment variable PGDATA is used.
Options for stop or restart:
-m SHUTDOWN-MODE May be 'smart', 'fast', or 'immediate'
Shutdown modes are:
smart Quit after all clients have disconnected
@ -50,6 +59,9 @@ Try '$CMDNAME --help' for more information."
bindir='@bindir@'
VERSION='@VERSION@'
# protect the log file
umask 077
# Check for echo -n vs echo \c
if echo '\c' | grep -s c >/dev/null 2>&1
@ -96,8 +108,11 @@ fi
po_path="$PGPATH/postmaster"
# set default shutdown signal
sig="-TERM"
wait=
wait_seconds=60
logfile=
silence_echo=
shutdown_mode=smart
while [ "$#" -gt 0 ]
do
@ -114,35 +129,35 @@ do
shift
PGDATA="$1"
;;
-p)
shift
po_path="$1"
-l)
logfile=$2
shift;;
-l*)
logfile=`echo "$1" | sed 's/^-l//'`
;;
-m)
shift
case $1 in
s|smart)
;;
f|fast)
sig="-INT"
;;
i|immediate)
sig="-QUIT"
;;
*)
echo "$CMDNAME: wrong shutdown mode: $1" 1>&2
echo "$advice" 1>&2
exit 1
;;
esac
;;
-w)
wait=1
shutdown_mode=$2
shift;;
-m*)
shutdown_mode=`echo "$1" | sed 's/^-m//'`
;;
-o)
shift
POSTOPTS="$1"
;;
-p)
shift
po_path="$1"
;;
-s)
silence_echo=:
;;
-w)
wait=yes
;;
-W)
wait=no
;;
-*)
echo "$CMDNAME: invalid option: $1" 1>&2
echo "$advice" 1>&2
@ -181,20 +196,47 @@ if [ -z "$PGDATA" ];then
exit 1
fi
if [ -z "$wait" ]; then
case $op in
start) wait=no;;
stop) wait=yes;;
restart) wait=no;; # must wait on shutdown anyhow
esac
fi
case $shutdown_mode in
s|smart)
sig="-TERM"
;;
f|fast)
sig="-INT"
;;
i|immediate)
sig="-QUIT"
;;
*)
echo "$CMDNAME: invalid shutdown mode: $1" 1>&2
echo "$advice" 1>&2
exit 1
;;
esac
DEFPOSTOPTS=$PGDATA/postmaster.opts.default
POSTOPTSFILE=$PGDATA/postmaster.opts
PIDFILE=$PGDATA/postmaster.pid
if [ $op = "status" ];then
if [ -f $PIDFILE ];then
PID=`head -1 $PIDFILE`
PID=`sed -n 1p $PIDFILE`
if [ $PID -lt 0 ];then
PID=`expr 0 - $PID`
echo "$CMDNAME: postgres is running (pid: $PID)"
else
echo "$CMDNAME: postmaster is running (pid: $PID)"
echo "Command line was:"
echo "`cat $POSTOPTSFILE`"
cat "$POSTOPTSFILE"
fi
exit 0
else
@ -205,29 +247,29 @@ fi
if [ $op = "stop" -o $op = "restart" ];then
if [ -f $PIDFILE ];then
PID=`head -1 $PIDFILE`
PID=`sed -n 1p $PIDFILE`
if [ $PID -lt 0 ];then
PID=`expr 0 - $PID`
echo "$CMDNAME: Cannot restart postmaster. postgres is running (pid: $PID)"
echo "Please terminate postgres and try again"
echo "$CMDNAME: Cannot restart postmaster. postgres is running (pid: $PID)" 1>&2
echo "Please terminate postgres and try again." 1>&2
exit 1
fi
kill $sig $PID
# wait for postmaster to shut down
if [ "$wait" = 1 -o $op = "restart" ];then
if [ "$wait" = yes -o "$op" = restart ];then
cnt=0
$ECHO_N "Waiting for postmaster to shut down.."$ECHO_C
$silence_echo $ECHO_N "waiting for postmaster to shut down..."$ECHO_C
while :
do
if [ -f $PIDFILE ];then
$ECHO_N "."$ECHO_C
$silence_echo $ECHO_N "."$ECHO_C
cnt=`expr $cnt + 1`
if [ $cnt -gt 60 ];then
echo "failed."
echo "postmaster does not shut down."
if [ $cnt -gt $wait_seconds ];then
$silence_echo echo " failed"
echo "$CMDNAME: postmaster does not shut down" 1>&2
exit 1
fi
else
@ -235,26 +277,35 @@ if [ $op = "stop" -o $op = "restart" ];then
fi
sleep 1
done
echo "done."
$silence_echo echo "done"
fi
$silence_echo echo "postmaster successfully shut down"
echo "postmaster successfully shut down."
else
echo "$CMDNAME: cannot find $PIDFILE"
echo "Is postmaster running?"
else # ! -f $PIDFILE
echo "$CMDNAME: cannot find $PIDFILE" 1>&2
echo "Is postmaster running?" 1>&2
if [ $op = "restart" ];then
echo "starting postmaster anyway..."
echo "starting postmaster anyway" 1>&2
else
exit 1
fi
fi
fi
fi # stop or restart
if [ $op = "start" -o $op = "restart" ];then
if [ -f $PIDFILE ];then
echo "$CMDNAME: It seems another postmaster is running. Trying to start postmaster anyway."
pid=`head -1 $PIDFILE`
echo "$CMDNAME: It seems another postmaster is running. Trying to start postmaster anyway." 1>&2
pid=`sed -n 1p $PIDFILE`
fi
unset logopt
if [ -n "$logfile" ]; then
logopt='</dev/null >>$logfile 2>&1'
else
# when starting without log file, redirect stderr to stdout, so
# pg_ctl can be invoked with >$logfile and still have pg_ctl's
# stderr on the terminal.
logopt='</dev/null 2>&1'
fi
# no -o given
@ -262,49 +313,66 @@ if [ $op = "start" -o $op = "restart" ];then
if [ $op = "start" ];then
# if we are in start mode, then look for postmaster.opts.default
if [ -f $DEFPOSTOPTS ]; then
$po_path -D $PGDATA `cat $DEFPOSTOPTS` &
else
$po_path -D $PGDATA &
POSTOPTS=`cat $DEFPOSTOPTS`
fi
POSTOPTS="-D $PGDATA $POSTOPTS"
else
# if we are in restart mode, then look postmaster.opts
`cat $POSTOPTSFILE` &
# if we are in restart mode, then look for postmaster.opts
set X `cat $POSTOPTSFILE`
shift
po_path=$1
shift
POSTOPTS=$@
fi
else
# -o given
$po_path -D $PGDATA $POSTOPTS &
else # -o given
POSTOPTS="-D $PGDATA $POSTOPTS"
fi
eval '$po_path' '$POSTOPTS' $logopt '&'
if [ -f $PIDFILE ];then
if [ "`head -1 $PIDFILE`" = "$pid" ];then
echo "$CMDNAME: Cannot start postmaster. Is another postmaster is running?"
if [ "`sed -n 1p $PIDFILE`" = "$pid" ];then
echo "$CMDNAME: cannot start postmaster" 1>&2
echo "Examine the log output." 1>&2
exit 1
fi
fi
# wait for postmaster to start up
if [ "$wait" = 1 ];then
# wait for postmaster to start
if [ "$wait" = yes ];then
cnt=0
$ECHO_N "Waiting for postmaster to start up.."$ECHO_C
$silence_echo $ECHO_N "waiting for postmaster to start..."$ECHO_C
while :
do
# FIXME: This is horribly misconceived.
# 1) If password authentication is set up, the connection will fail.
# 2) If a virtual host is set up, the connection may fail.
# 3) If network traffic filters are set up tight enough, the connection
# may fail.
# 4) When no Unix domain sockets are available, the connection will
# fail. (Using TCP/IP by default ain't better.)
# 5) When a different port is configured, the connection will fail
# or go to the wrong server.
# 6) If the dynamic loader is not set up correctly (for this user/at
# this time), psql will fail (to find libpq).
# 7) If psql is misconfigured, this may fail.
if "$PGPATH/psql" -l >/dev/null 2>&1
then
break;
else
$ECHO_N "."$ECHO_C
$silence_echo $ECHO_N "."$ECHO_C
cnt=`expr $cnt + 1`
if [ $cnt -gt 60 ];then
echo "$CMDNAME: postmaster does not start up"
if [ $cnt -gt $wait_seconds ];then
$silence_echo echo "failed"
echo "$CMDNAME: postmaster does not start" 1>&2
exit 1
fi
sleep 1
fi
done
echo "done"
fi
echo "postmaster successfully started up"
$silence_echo echo "done"
fi
$silence_echo echo "postmaster successfully started"
fi # start or restart
exit 0