<!-- $Id: mod_ctrls_admin.html,v 1.8 2010/01/06 23:30:24 castaglia Exp $ --> <!-- $Source: /cvsroot/proftp/proftpd/doc/contrib/mod_ctrls_admin.html,v $ --> <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.2.<i>x</i>/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="#debug"><code>debug</code></a> <li><a href="#dns"><code>dns</code></a> <li><a href="#down"><code>down</code></a> <li><a href="#dump"><code>dump</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> <h2><a name="AdminControlsACLs">AdminControlsACLs</a></h2> <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> <h2><a name="AdminControlsEngine">AdminControlsEngine</a></h2> <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> <h2><a name="debug"><code>debug</code></a></h2> <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 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> Alternatively, for developers, 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> A dump of the in-memory configuration structure can also be obtained via this control action: <pre> ftpdctl debug config </pre> <p> <hr> <h2><a name="dns"><code>dns</code></a></h2> <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> <h2><a name="down"><code>down</code></a></h2> <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> <h2><a name="dump"><code>dump</code></a></h2> <strong>Syntax:</strong> ftpdctl dump classes|config|memory</em><br> <strong>Purpose:</strong> Dump internal information from the running daemon <p> The <code>dump</code> control action dumps various information from the internal subsystems. It is intended mainly for use by developers and curious system administrators. This control action can be used to display the current memory allocation of the daemon: <pre> ftpdctl dump memory </pre> Memory allocations for session processes are currently not available via this control action. <p> A dump of the in-memory configuration structure can also be obtained via this control action: <pre> ftpdctl dump config </pre> <p> To list the in-meory representation of all configured Classes, use: <pre> ftpdctl dump classes </pre> <p> <hr> <h2><a name="get"><code>get</code></a></h2> <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> <h2><a name="kick"><code>kick</code></a></h2> <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> <hr> <h2><a name="restart"><code>restart</code></a></h2> <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> <h2><a name="scoreboard"><code>scoreboard</code></a></h2> <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> <h2><a name="shutdown"><code>shutdown</code></a></h2> <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> <h2><a name="status"><code>status</code></a></h2> <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> <h2><a name="trace"><code>trace</code></a></h2> <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> <h2><a name="up"><code>up</code></a></h2> <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 make make install </pre> <p> <hr> Last Updated: <i>$Date: 2010/01/06 23:30:24 $</i><br> <br><hr> <font size=2><b><i> © Copyright 2004-2010 ProFTPD Project<br> All Rights Reserved<br> </i></b></font> <hr><br> </body> </html>
