This module implements administrative control actions for the ftpdctl program.

The most current version of mod_ctrls_admin is distributed with the ProFTPD source.

Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

Directives

• AdminControlsACLs
• AdminControlsEngine

Control Actions

• debug
• dns
• down
• dump
• get
• kick
• restart
• scoreboard
• shutdown
• status
• trace
• up

Directives

AdminControlsACLs

The AdminControlsACLs directive configures access lists of users or groups who are allowed (or denied) the ability to use the actions implemented by mod_ctrls_admin. The default behavior is to deny everyone unless an ACL allowing access has been explicitly configured.

If "allow" is used, then list, a comma-delimited list of users or groups, can use the given actions; all others are denied. If "deny" is used, then the list of users or groups cannot use actions all others are allowed. Multiple AdminControlsACLs directives may be used to configure ACLs for different control actions, and for both users and groups.

AdminControlsEngine

The AdminControlsEnginedirective enables or disables the mod_ctrls_admin module, and thus the handling of its implemented control actions.

If only certain of the module's control actions are wanted, provide a list of those actions, rather than the normal "on" or "off". Any of mod_ctrls_admin's control actions that do not appear in actions will be unregistered; by default, all of the module's control actions are registered.

Control Actions

debug

Obtaining debug output from the server greatly helps in diagnosing problems. The trick is in getting this debug output from the server. The debug control action can be used to gather such information.

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.

Example:

  ftpdctl debug level 9

  ftpdctl debug level 0

Alternatively, for developers, this control action can be used to display the current memory allocation of the daemon:

  ftpdctl debug memory

A dump of the in-memory configuration structure can also be obtained via this control action:

  ftpdctl debug config

dns

The dns control action can be used to enable or disable the UseReverseDNS configuration at run time:

  # Enable resolution of IP addresses to DNS names
  ftpdctl dns on

  # Disable resolution of IP addresses to DNS names
  ftpdctl dns off

down

The down 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 "up" control action can be used to bring that virtual server back up.

If a port number is not specified, it defaults to 21.

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.

dump

The dump 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:

  ftpdctl dump memory

A dump of the in-memory configuration structure can also be obtained via this control action:

  ftpdctl dump config

To list the in-meory representation of all configured Classes, use:

  ftpdctl dump classes

get

The get 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.

The "config" parameter causes ftpdctl to display a configuration dump, similar to what is displayed by a syntax check (i.e. using the -t proftpd command-line option).

The "directives" parameter causes ftpdctl to display a sorted list of all supported configuration directives, as well as the module which handles the corresponding directive.

kick

The kick control action can be used to disconnect a currently connected class, host or user from the daemon.

Examples:

  ftpdctl kick user bob dave 

  ftpdctl kick host luser.host.net

  ftpdctl kick class eval intranet

restart

The restart control action causes the daemon to re-read its configuration file, just as if a SIGHUP 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.

scoreboard

The scoreboard control action can be used to force the ScoreboardFile to be "scrubbed" for dead session processes which may not have exited cleanly.

  ftpdctl scoreboard scrub

  # The verb "clean" is synonymous with "scrub"
  ftpdctl scoreboard clean

shutdown

The shutdown 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.

The optional "graceful" parameter allows for a graceful shutdown, in which proftpd will wait for the given number of seconds for all current sessions to end, before shutting down.

Example:

  ftpdctl shutdown graceful 30

status

The status control action can be used to show the status of a particular virtual server, whether it is up or down.

If a port number is not specified, it defaults to 21.

If "status all" is used, the status of all virtual servers will be displayed.

trace

The trace control action can be used to dynamically change the log levels of trace log levels.

Example:

  ftpdctl trace delay:10

Additionally, the trace control action can be used to display the list of current trace channels and their log levels, e.g.:

  # 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    

up

The up control action can be used to "turn up" any virtual server that has been "downed" by the "down" control action. Note that using the "restart" control action is sufficient to enable, with one command, all virtual servers that have been downed.

If a port number is not specified, it defaults to 21.

Installation

  ./configure --enable-ctrls --with-modules=mod_ctrls_admin
  make
  make install