479 lines
15 KiB
HTML
479 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>ProFTPD module mod_ctrls_admin</title>
|
|
</head>
|
|
|
|
<body bgcolor=white>
|
|
|
|
<hr>
|
|
<center>
|
|
<h2><b>ProFTPD module <code>mod_ctrls_admin</code></b></h2>
|
|
</center>
|
|
<hr><br>
|
|
|
|
This module is contained in the <code>mod_ctrls_admin.c</code> file for
|
|
ProFTPD /1.3.<i>x</i>, and is not compiled by default. Installation
|
|
instructions are discussed <a href="#Installation">here</a>.
|
|
|
|
<p>
|
|
This module implements administrative control actions for the
|
|
<code>ftpdctl</code> program.
|
|
|
|
<p>
|
|
The most current version of <code>mod_ctrls_admin</code> is distributed with
|
|
the ProFTPD source.
|
|
|
|
<h2>Author</h2>
|
|
<p>
|
|
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
|
|
questions, concerns, or suggestions regarding this module.
|
|
|
|
<h2>Directives</h2>
|
|
<ul>
|
|
<li><a href="#AdminControlsACLs">AdminControlsACLs</a>
|
|
<li><a href="#AdminControlsEngine">AdminControlsEngine</a>
|
|
</ul>
|
|
|
|
<h2>Control Actions</h2>
|
|
<ul>
|
|
<li><a href="#config"><code>config</code></a>
|
|
<li><a href="#debug"><code>debug</code></a>
|
|
<li><a href="#dns"><code>dns</code></a>
|
|
<li><a href="#down"><code>down</code></a>
|
|
<li><a href="#get"><code>get</code></a>
|
|
<li><a href="#kick"><code>kick</code></a>
|
|
<li><a href="#restart"><code>restart</code></a>
|
|
<li><a href="#scoreboard"><code>scoreboard</code></a>
|
|
<li><a href="#shutdown"><code>shutdown</code></a>
|
|
<li><a href="#status"><code>status</code></a>
|
|
<li><a href="#trace"><code>trace</code></a>
|
|
<li><a href="#up"><code>up</code></a>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h1>Directives</h1>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="AdminControlsACLs">AdminControlsACLs</a></h3>
|
|
<strong>Syntax:</strong> AdminControlsACLs <em>actions|all allow|deny user|group list</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_ctrls_admin<br>
|
|
<strong>Compatibility:</strong> 1.2.10rc1 and later
|
|
|
|
<p>
|
|
The <code>AdminControlsACLs</code> directive configures access lists of
|
|
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
|
|
use the <em>actions</em> implemented by <code>mod_ctrls_admin</code>. The
|
|
default behavior is to deny everyone unless an ACL allowing access has been
|
|
explicitly configured.
|
|
|
|
<p>
|
|
If "allow" is used, then <em>list</em>, a comma-delimited list
|
|
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
|
|
others are denied. If "deny" is used, then the <em>list</em> of
|
|
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
|
|
allowed. Multiple <code>AdminControlsACLs</code> directives may be used to
|
|
configure ACLs for different control actions, and for both users and groups.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="AdminControlsEngine">AdminControlsEngine</a></h3>
|
|
<strong>Syntax:</strong> AdminControlsEngine <em>on|off|actions</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_ctrls_admin<br>
|
|
<strong>Compatibility:</strong> 1.2.10rc1 and later
|
|
|
|
<p>
|
|
The <code>AdminControlsEngine</code>directive enables or disables the
|
|
<code>mod_ctrls_admin</code> module, and thus the handling of its
|
|
implemented control actions.
|
|
|
|
<p>
|
|
If only certain of the module's control actions are wanted, provide a list
|
|
of those <em>actions</em>, rather than the normal "on" or
|
|
"off". Any of <code>mod_ctrls_admin</code>'s control actions that
|
|
do not appear in <em>actions</em> will be unregistered; by default, all of
|
|
the module's control actions are registered.
|
|
|
|
<p>
|
|
<hr>
|
|
<h1>Control Actions</h1>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="config"><code>config</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl config set|remove <em>ip-address|dns-name[:port] directive ...</em><br>
|
|
<strong>Purpose:</strong> Update configuration of a virtual server
|
|
|
|
<p>
|
|
The <code>config</code> control action can be used to update the configuration
|
|
of an individual virtual server, without requiring a <code>SIGHUP</code>
|
|
to restart the daemin and reparse the configuration. The <code>config</code>
|
|
action supports two subcommands: "set" and "remove".
|
|
|
|
<p>
|
|
Both <code>config</code> subcommands take the address of the virtual server
|
|
whose configuration is to be changed. This can be specified as a DNS name
|
|
or an IP address, and optionally the port number. If no port number is
|
|
explicitly provided, a default of port 21 is assumed. IPv6 addresses <b>are</b>
|
|
supported. Examples:
|
|
<pre>
|
|
$ ftpdctl config set 10.1.2.3 ...
|
|
$ ftpdctl config set ftp.example.com:2121 ...
|
|
$ ftpdctl config set '[::1]:4242' ...
|
|
</pre>
|
|
<b>Note</b> that using the IPv6 syntax may require that you enclose the
|
|
address in single quotes, to prevent the shell from parsing those characters.
|
|
|
|
<p>
|
|
When <i>setting</i> a configuration directive, all of the parameters of that
|
|
configuration directive are required, just as if you were typing that
|
|
configuration directive in the config file:
|
|
<pre>
|
|
$ ftpdctl config set 192.168.0.101:2121 TLSRequired off
|
|
ftpdctl: config set: TLSRequired configured
|
|
</pre>
|
|
|
|
<p>
|
|
When <i>removing</i> a configuration directive, only the configuration directive
|
|
name is needed:
|
|
<pre>
|
|
$ ftpdctl config remove 192.168.0.101 TLSRequired
|
|
ftpdctl: config remove: TLSRequired removed
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="debug"><code>debug</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl debug <em>[level [number]]|memory|config</em><br>
|
|
<strong>Purpose:</strong> Obtain debug information from the running daemon
|
|
|
|
<p>
|
|
Obtaining debug output from the server greatly helps in diagnosing problems.
|
|
The trick is in getting this debug output from the server. The
|
|
<code>debug</code> control action can be used to gather such information.
|
|
|
|
<p>
|
|
First, this control action can increase or query the debug logging verbosity
|
|
of the daemon on-the-fly, to obtain the needed output, and then to return the
|
|
daemon to a more silent state of logging.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
$ ftpdctl debug level 9
|
|
</pre>
|
|
raises the verbosity of the daemon to its maximum level. Once enough output
|
|
has been collected, use:
|
|
<pre>
|
|
$ ftpdctl debug level 0
|
|
</pre>
|
|
to return the daemon to its default debug output level.
|
|
|
|
<p>
|
|
Instead, to simply check the current debug logging verbosity, use:
|
|
<pre>
|
|
$ ftpdctl debug level
|
|
</pre>
|
|
|
|
<p>
|
|
Alternatively, for developers (<i>i.e.</i> if <code>proftpd</code> was
|
|
compiled with the <code>--enable-devel</code> configure option), this control
|
|
action can be used to display the current memory allocation of the daemon:
|
|
<pre>
|
|
$ ftpdctl debug memory
|
|
</pre>
|
|
Memory allocations for session processes are currently not available via
|
|
this control action.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="dns"><code>dns</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl dns <em>on|off</em><br>
|
|
<strong>Purpose:</strong> DNS configuration
|
|
|
|
<p>
|
|
The <code>dns</code> control action can be used to enable or disable
|
|
the <code>UseReverseDNS</code> configuration at run time:
|
|
<pre>
|
|
# Enable resolution of IP addresses to DNS names
|
|
$ ftpdctl dns on
|
|
|
|
# Disable resolution of IP addresses to DNS names
|
|
$ ftpdctl dns off
|
|
</pre>
|
|
|
|
<p>
|
|
Note that the <code>dns</code> control action also supports a command for
|
|
clearing any cached DNS lookup information:
|
|
<pre>
|
|
$ ftpdctl dns clear cache
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="down"><code>down</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl down <em>ip-address|dns-name[#port]|"all"</em><br>
|
|
<strong>Purpose:</strong> Turn down a virtual server
|
|
|
|
<p>
|
|
The <code>down</code> control action can be used to "turn down"
|
|
an individual virtual server, so that clients cannot connect to it. Once
|
|
a virtual server has been "downed", the
|
|
"<a href="#up">up</a>" control action can be used to bring
|
|
that virtual server back up.
|
|
|
|
<p>
|
|
If a port number is not specified, it defaults to 21.
|
|
|
|
<p>
|
|
Note that using "down all" effectively puts the daemon in an
|
|
"administrative" shutdown state, where the daemon is still running
|
|
but no servers are available for servicing incoming connection requests.
|
|
Current sessions are not affected.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="get"><code>get</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl get <em>"config"|"directives"</em><br>
|
|
<strong>Purpose:</strong> Obtain configuration information
|
|
|
|
<p>
|
|
The <code>get</code> control action can be used obtain various sorts of
|
|
configuration information from the daemon. At present, this control action
|
|
only supports the "config" and "directives" parameters.
|
|
|
|
<p>
|
|
The "config" parameter causes <code>ftpdctl</code> to display
|
|
a configuration dump, similar to what is displayed by a syntax check
|
|
(<i>i.e.</i> using the <code>-t</code> proftpd command-line option).
|
|
|
|
<p>
|
|
The "directives" parameter causes <code>ftpdctl</code> to display a
|
|
sorted list of all supported configuration directives, as well as the module
|
|
which handles the corresponding directive.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="kick"><code>kick</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl kick <em>[class name]|[host dns-name|ip-address][user name]</em><br>
|
|
<strong>Purpose:</strong> Kick a currently connected class, host or user from the daemon
|
|
|
|
<p>
|
|
The <code>kick</code> control action can be used to disconnect a currently
|
|
connected <em>class</em>, <em>host</em> or <em>user</em> from the daemon.
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
$ ftpdctl kick user bob dave
|
|
</pre>
|
|
will kick all sessions that have logged in as user "bob" or user "dave".
|
|
<pre>
|
|
$ ftpdctl kick host luser.host.net
|
|
</pre>
|
|
will kick all sessions that have connected from host "luser.host.net".
|
|
<pre>
|
|
$ ftpdctl kick class eval intranet
|
|
</pre>
|
|
will kick all sessions that belong to classes "eval" and "intranet".
|
|
|
|
<p>
|
|
You can also use the <code>-n <count></code> command-line option to
|
|
specify the maximum number of clients to be kicked. For example, perhaps
|
|
you only want to kick off 10 clients from host "luser.host.net"
|
|
rather than kicking all of them off. To do this, use:
|
|
<pre>
|
|
$ ftpdctl kick host -n 10 luser.host.net
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="restart"><code>restart</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl restart<br>
|
|
<strong>Purpose:</strong> Restart the daemon
|
|
|
|
<p>
|
|
The <code>restart</code> control action causes the daemon to re-read its
|
|
configuration file, just as if a <code>SIGHUP</code> had been used. This is
|
|
convenient for administrators, as it does not (necessarily) require root
|
|
privileges, nor knowledge of the daemon's PID, to restart the daemon.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
$ ftpdctl restart
|
|
</pre>
|
|
In addition, you can use the <code>restart</code> control to ask the daemon
|
|
how many times it has been restarted:
|
|
<pre>
|
|
$ ftpdctl restart count
|
|
ftpdctl: restarted 4 times since 2010-01-06 23:20:09 GMT
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="scoreboard"><code>scoreboard</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl scoreboard scrub<br>
|
|
<strong>Purpose:</strong> Scrubs the ScoreboardFile for dead processes
|
|
|
|
<p>
|
|
The <code>scoreboard</code> control action can be used to force the
|
|
<code>ScoreboardFile</code> to be "scrubbed" for dead session
|
|
processes which may not have exited cleanly.
|
|
<pre>
|
|
$ ftpdctl scoreboard scrub
|
|
|
|
# The verb "clean" is synonymous with "scrub"
|
|
$ ftpdctl scoreboard clean
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="shutdown"><code>shutdown</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl shutdown <em>["graceful" seconds]</em><br>
|
|
<strong>Purpose:</strong> Stop the daemon
|
|
|
|
<p>
|
|
The <code>shutdown</code> control action shuts the daemon down. This is
|
|
convenient for administrators, as it does not (necessarily) require root
|
|
privileges, nor knowledge of the daemon's PID, to stop the daemon.
|
|
|
|
<p>
|
|
The optional "graceful" parameter allows for a graceful shutdown,
|
|
in which <code>proftpd</code> will wait for the given number of <em>seconds</em>
|
|
for all current sessions to end, before shutting down.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
$ ftpdctl shutdown graceful 30
|
|
</pre>
|
|
will cause <code>proftpd</code> to wait for 30 seconds for all current
|
|
sessions to end before shutting down completely.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="status"><code>status</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl status <em>ip-address|dns-name[#port]|"all"</em><br>
|
|
<strong>Purpose:</strong> Display the status of virtual servers
|
|
|
|
<p>
|
|
The <code>status</code> control action can be used to show the status of
|
|
a particular virtual server, whether it is <b>up</b> or <b>down</b>.
|
|
|
|
<p>
|
|
If a port number is not specified, it defaults to 21.
|
|
|
|
<p>
|
|
If "status all" is used, the status of all virtual servers will be
|
|
displayed.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="trace"><code>trace</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl trace <em>channel:level|"info"</em><br>
|
|
<strong>Purpose:</strong> Configure trace channel log levels
|
|
|
|
<p>
|
|
The <code>trace</code> control action can be used to dynamically change
|
|
the log levels of trace log levels.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
$ ftpdctl trace delay:10
|
|
</pre>
|
|
will set the log verbosity level of the <em>delay</em> trace log channel to 10.
|
|
|
|
<p>
|
|
Additionally, the <code>trace</code> control action can be used to display
|
|
the list of current trace channels and their log levels, <i>e.g.</i>:
|
|
<pre>
|
|
$ ftpdctl trace info
|
|
ftpdctl: Channel Level
|
|
ftpdctl: ---------- ------
|
|
ftpdctl: pam 10
|
|
ftpdctl: netacl 10
|
|
ftpdctl: response 10
|
|
ftpdctl: auth 10
|
|
ftpdctl: utf8 10
|
|
ftpdctl: inet 10
|
|
ftpdctl: binding 10
|
|
ftpdctl: dns 10
|
|
ftpdctl: dso 10
|
|
ftpdctl: parser 10
|
|
ftpdctl: pool 10
|
|
ftpdctl: ctrls 10
|
|
ftpdctl: data 10
|
|
ftpdctl: netio 10
|
|
ftpdctl: config 10
|
|
ftpdctl: ident 10
|
|
ftpdctl: command 10
|
|
ftpdctl: delay 10
|
|
ftpdctl: timer 10
|
|
ftpdctl: var 10
|
|
ftpdctl: event 10
|
|
ftpdctl: fsio 10
|
|
ftpdctl: site 10
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="up"><code>up</code></a></h3>
|
|
<strong>Syntax:</strong> ftpdctl up <em>ip-address|dns-name[#port]</em><br>
|
|
<strong>Purpose:</strong> Turn up a "downed" virtual server
|
|
|
|
<p>
|
|
The <code>up</code> control action can be used to "turn up"
|
|
any virtual server that has been "downed" by the
|
|
"<a href="#down">down</a>" control action. Note that using the
|
|
"<a href="#restart">restart</a>" control action is sufficient to
|
|
enable, with one command, all virtual servers that have been downed.
|
|
|
|
<p>
|
|
If a port number is not specified, it defaults to 21.
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Installation">Installation</a></h2>
|
|
This module requires that controls support be enabled in <code>proftpd</code>
|
|
via the <code>--enable-ctrls</code> configure option. Follow the normal
|
|
steps for using third-party modules in ProFTPD:
|
|
<pre>
|
|
$ ./configure --enable-ctrls --with-modules=mod_ctrls_admin
|
|
</pre>
|
|
To build <code>mod_ctrls_admin</code> as a DSO module:
|
|
<pre>
|
|
$ ./configure --enable-ctrls --enable-dso --with-shared=mod_ctrls_admin
|
|
</pre>
|
|
Then follow the usual steps:
|
|
<pre>
|
|
$ make
|
|
$ make install
|
|
</pre>
|
|
|
|
<p>
|
|
For those with an existing ProFTPD installation, you can use the
|
|
<code>prxs</code> tool to add <code>mod_ctrls_admin</code>, as a DSO module, to
|
|
your existing server:
|
|
<pre>
|
|
$ prxs -c -i -d mod_ctrls_admin.c
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<font size=2><b><i>
|
|
© Copyright 2004-2016 The ProFTPD Project<br>
|
|
All Rights Reserved<br>
|
|
</i></b></font>
|
|
<hr>
|
|
|
|
</body>
|
|
</html>
|