<!-- $Id: Stopping.html,v 1.4 2005/01/03 05:36:06 castaglia Exp $ -->
<!-- $Source: /cvsroot/proftp/proftpd/doc/howto/Stopping.html,v $ -->
<html>
<head>
<title>ProFTPD mini-HOWTO - Stopping and Starting</title>
</head>
<body bgcolor=white>
<hr>
<center><h2><b><i>Stopping and Starting ProFTPD</i></b></h2></center>
<hr>
<p>
The starting and stopping of a ProFTPD server is a straightforward process,
once the means intended for such things are understood. Starting the
server is easy. Stopping and/or restarting the server are the more complicated
tasks. These can be accomplish either using signals or <code>ftpshut</code>,
depending on your needs. Use of signals will fulfill most requirements; the
<code>ftpshut</code> program is used for a <a href="#ftpshut">specific way of
shutting down</a> a <code>proftpd</code> server.
<p><a name="Starting"></a>
<b>Starting <code>proftpd</code></b><br>
init.d scripts vs command-line invocation
standalone vs inetd
<pre>
/usr/local/sbin/proftpd [options]
</pre>
where <code>/usr/local/sbin</code> is determined by <code>configure</code>
and <code>[options]</code> are described below (or in <em>proftpd(8)</em>):
<pre>
-h, --help
Display proftpd usage
-n, --nodaemon
Disable background daemon mode and send all output to stderr)
-q, --quiet
Don't send output to stderr when running with -n or --nodaemon
-d [level], --debug
Set debugging level (0-9, 9 = most debugging)
-D [definition], --define
Set arbitrary IfDefine definition
-c [config-file], --config
Specify alternate configuration file
-p [0|1], --persistent
Enable/disable default persistent passwd support
-l, --list
List all compiled-in modules
-t, --configtest
Test the syntax of the specified config
-v, --version
Print version number and exit
-vv, --version-status
Print extended version information and exit
</pre>
<p><a name="Signals"></a>
<b>Signals</b><br>
You will notice many <code>proftpd</code> processess running on your system,
but you should not send signals to any of them except the parent, whose PID is
in the <code>PidFile</code>. That is to say, you should not ever need to
send signals to any process except the parent. There are two signals that you
can send the parent: <code>TERM</code> and <code>HUP</code>, which will be
described below.
<!--
<GeekBoy> timeouts left child proccesses going... I kill -9 both of them and it proceeds to tell me max num of allowed clients are connected
<castaglia> don't use -9
<GeekBoy> hmmmm, ok
<castaglia> there's no way proftpd can handle killed sessions if you use -9
<GeekBoy> let's try this again
<castaglia> no app can
<castaglia> if you need to kill a session
<GeekBoy> was unaware of the low level workings of the various kill signals
<castaglia> just use 'kill <pid>'
<castaglia> -9 is SIGKILL
<GeekBoy> ok
<castaglia> and an application cannot catch or handle that particular signal
<castaglia> the kernel will not allow it
<castaglia> as that one signal is reserved, to make sure that the kernel can use it to kill any process
<castaglia> as when the server is shutting down
<GeekBoy> ok
<castaglia> unfortunately, it also means that the application can't catch the -9 and do any proper cleanup
<castaglia> imho, people use -9 too much these days
<GeekBoy> i see
<GeekBoy> I'll avoid using it when the default doesn't work
<GeekBoy> which is 15, right?
<castaglia> ummm...yes
<castaglia> SIGTERM
-->
<p>
To send a signal to the parent you should issue a command such as:
<pre>
kill -TERM `cat /usr/local/var/proftpd.pid`
</pre>
You can read about its progress by issuing:
<pre>
tail -f /usr/local/var/logs/proftpd.log
</pre>
Modify those examples to match your <code>SystemLog</code> and
<code>PidFile</code> settings.
<p>
<b>The <code>TERM</code> Signal</b> <i>(stop now)</i><br>
Sending the <code>TERM</code> signal to the daemon parent process causes it
to immediately attempt to kill off all of its children. It may take it several
seconds to complete killing off its children. The daemon itself then exits.
Any transfers in progress are terminated, and no further session requests
are served.
<p>
Servers run out of <code>inetd</code> or <code>xinetd</code> (<i>e.g.</i> with
a <code>ServerType</code> setting of <code>inetd</code>) will not need this
signal, as their "parent" is the <code>inetd</code> or
<code>xinetd</code> process.
<p>
<b>The <code>HUP</code> Signal</b> <i>(restart now)</i><br>
Sending the <code>HUP</code> signal to the daemon parent process causes it to
re-read its configuration file(s), and re-opens any log files. Then it
returns to handling new sessions. Any existing sessions will <b>not</b>
be terminated.
<p>
Servers run out of <code>inetd</code> or <code>xinetd</code> will not need
this signal; a new server process is started by the superserver process
(<i>e.g.</i> <code>inetd</code> or <code>xinetd</code>) for every session
request. This means that any changes to the configuration file will be
visible to the next session after saving the changes to the file.
<p>
Note that if your configuration file has errors in it when you issue a restart
then your parent will not restart, it will exit with an error. To avoid this,
perform a syntax check of the file before sending the signal:
<pre>
proftpd -t -d5
</pre>
<p><a name="InitScript"></a>
<b>Example <code>init.d</code> script</b><br>
<pre>
#!/bin/sh
# ProFTPD files
FTPD_BIN=/usr/local/sbin/proftpd
FTPD_CONF=/usr/local/etc/proftpd.conf
PIDFILE=/var/run/proftpd.pid
# If PIDFILE exists, does it point to a proftpd process?
if [ -f $PIDFILE ]; then
pid=`cat $PIDFILE`
fi
if [ ! -x $FTPD_BIN ]; then
echo "$0: $FTPD_BIN: cannot execute"
exit 1
fi
case $1 in
start)
if [ -n "$pid" ]; then
echo "$0: proftpd [PID $pid] already running"
exit
fi
if [ -r $FTPD_CONF ]; then
echo "Starting proftpd..."
$FTPD_BIN -c $FTPD_CONF
else
echo "$0: cannot start proftpd -- $FTPD_CONF missing"
fi
;;
stop)
if [ -n "$pid" ]; then
echo "Stopping proftpd..."
kill -TERM $pid
else
echo "$0: proftpd not running"
exit 1
fi
;;
restart)
if [ -n "$pid" ]; then
echo "Rehashing proftpd configuration"
kill -HUP $pid
else
echo "$0: proftpd not running"
exit 1
fi
;;
*)
echo "usage: $0 {start|stop|restart}"
exit 1
;;
esac
exit 0
</pre>
<p>
<a name="ftpshut"><b>The <code>ftpshut</code> program</b><br>
The <code>ftpshut</code> program that comes as part of ProFTPD can also
be used to shut down a <code>proftpd</code> server, in a sense. This program
does not actually cause the server to stop completely, but rather places
the server in an "administrative shutdown" state. This means
that the server will still be handling session requests, but will deny
incoming requests, telling clients to come back later. <code>ftpshut</code>
allows the administrator to configure the server to start refusing
connections at some future date, and also to disconnect existing sessions
at some future date.
<p>
The situation in which this ability is most useful (a
<a href="http://www.proftpd.org/docs/faq/proftpdfaq-4.html#ss4.17">FAQ</a>) is
one where filesystem maintainenance or work needs to be done in the area from
which the FTP server is serving files, but the server need not be shutdown.
By placing the server in an "administrative shutdown" mode, clients
are barred from their file while the adminstrative work is being done. Once
completed, the server can be put back in normal operating mode by simply
deleting the shutdown message file, described below.
<p>
The <code>ftpshut</code> program works by creating a file, usually
<code>/etc/shutmsg</code>, for which the server checks periodically. This
file will contain the time at which the server is to place itself in
"administrative shutdown" mode, and times (if any) of refusing
incoming connections, disconnecting existing connections. Unfortunately,
many third-party administration tools use <code>ftpshut</code> to shut
down <code>proftpd</code> servers, rather than using the method above. The
problem with this approach is that, once restarted, the server will check
for <code>/etc/shutmsg</code>, and will not accept incoming connections,
leading to this
<a href="http://www.proftpd.org/docs/faq/faq_full.html#AEN373">FAQ</a>;
the third-party administration tool often forgets to delete that file once
done.
<p>
Read <code>ftpshut</code>'s
<a href="http://www.castaglia.org/proftpd/doc/ftpshut.html">man</a> page
for more detailed information on its usage.
<p>
<hr>
Last Updated: <i>$Date: 2005/01/03 05:36:06 $</i><br>
<hr>
</body>
</html>
