Runtime configuration

The configuration of the POPular proxy is done by sending commands to the running server via a UNIX domain socket. This socket is in the run directory (default: /var/run/popular) and named pproxy.PID.ctrl. PID, in this case, is the process id of the parent process. For easy access, there is a link from pproxy.ctrl to the real socket file.

The pcontrol utility program is provided to send commands to this socket. See the man page for details.

Normally, after pproxy has started, the file /etc/popular/pproxy.rc should be used to set the start configuration of the server. There is an example of this file in the conf directory of the distribution. The supplied RedHat and Debian init scripts will use this file to do the initial configuration.

The show and set commands

The following read-only variables are recognized. The content of these variables can be read by sending the command show VAR to the proxy.

Each variable has one of the following types: Bool, Int, File, Dir, String, Id, or Time. Bool variables can be set to 0=false=no=off or 1=true=yes=on. Directories named in variables of type Dir must exist. Variables of type Id hold strings which can only contain chars, numbers, the underscore (_), the hyphen (-), and the dot (.). Time variables hold time intervals. They can be set using something like '5d3h10m4s'.

idId Id (name) of server. This is always "pproxy".
pidInt The process id of the pproxy parent process.
rundirDir This is the directory set by the --rundir option.
sessionlimitInt The maximum compiled in value for maxsession.
versionString The version of the pproxy program.

The following read-write variables are recognized:

allowsslv2Boolean Allow SSLv2 connections. Only used when SSL/TLS is compiled in. Default is off. SSLv2 is considered less secure than SSLv3 and TLS, but some clients might need it. Changes in this variable will only be applicable for virtual servers that are configured after the change!
authtimeoutTime (0-1h) This is the timeout while in authorization state. 0 means no timeout.
backlogInt (5-1024) Backlog parameter for the listen(2) system call. When this is changed future listen(2) system calls will get the new parameters. Already listening sockets are not affected. To activate the new setting the virtual server has to be taken offline and online again.
capadirDir This is the directory where the definitions for capability lists are to be found. Consult the chapter about capabilities for details.
checkportInt (1-65535) UDP Port, that the pcheckd on the backend server listens on. All children spawned after this is changed will use the new value.
checktimeoutTime (1s-1m) Timeout in seconds after which a UDP packet sent to the pcheckd server is given up as lost. All children spawned after this is changed will use the new value.
defaultnsId This is the default namespace used, if the namespace is USER and there is no namespace in the username sent from the client. All children spawned after this is changed will use the new value.
fallbackId If the username is not found in the local database, the proxy server can connect to a fallback POP3 backend server and try authenticating the user there. This is the name of the backend as defined with the backend command. All children spawned after this is changed will use the new value.
idletimeoutTime (10m-1d) Timeout in seconds when a session is idle. If no data is read after this timeout the connection will be closed. All children spawned after this is changed will use the new value. This is what RFC1939 calles the 'inactivity autologout timer'. RFC1939 doesn't allow this to be set smaller than 10 minutes, so POPular doesn't allow this. See also proxytimeout.
logfileFile Name of the logfile. This will take effect the next time the log file is reopened.
maxlocalloadId (0-9999) If the system load average for the last minute is equal to this value or higher, no new connections are accepted. This is an integer value between 0 and 9999. 0 means that the load is not checked. When the server notices that the load is too high (or ok after beeing to high), this event is logged. The load average is not a really good measure of the system load so this is more of a last ditch effort to keep the system usable than a good way of controlling the load. You probably have to experiment with different values of maxsession and maxlocalload to find the best values for your system. Note that the load check currently only works on systems with /proc/loadavg.
maxsessionId Maximal number of proxy child processes. This means that not more then this number of simultaneous connections can be handled. You probably want to set this large enough to handle the biggest estimated load on your system without running out of ressources. Note that there is a maximum value for this compiled into the binary. The value of this variable can currently only be increased, not decreased.
pdmdirDir Directory where POPular database modules (PDM) are stored.
proxytimeoutTime (10m-1d) Timeout in seconds when proxying data. If no data is read from the client or backend for this time the connection will be closed. All children spawned after this is changed will use the new value. This is what RFC1939 calles the 'inactivity autologout timer'. RFC1939 doesn't allow this to be set smaller than 10 minutes, so POPular doesn't allow this. See also idletimeout.
sessiontimeoutTime (0s-1d) Overall timeout for the length of a session in minutes. Regardless of what is happening, a session will be killed after sessiontimeout minutes. This value must be between 0 and 1 day. If sessiontimeout is 0, no limit is enforced. Note that the time real session time may be somewhat longer, because the authentication phase is not included in this timer. There is a separate timeout for this: authtimeout.
sidprefixId This is the prefix for all session IDs. Default is the hostname (without the domain). If this is set to a different value on every proxy server in a cluster, session IDs will be unique over the whole cluster. The session ID will be the concatenation of this prefix, the UNIX timestamp (seconds since the epoch 1970-01-01 00:00:00), and the process ID of the pproxy process handling this session. These three components are separated by dots. Example: "p02.990738012.7845".
tlsdirDir In this directory all the key and signature files for SSL/TLS are to be found.

In all places where host names or IP numbers must be given, either one can be given. A host name is resolved to an IP number at the moment of configuration. The IP number is then saved internally. So if you change something in your network and IP numbers change, you have to redo the configuration.

The shutdown command

There are four variants of the shutdown command:

shutdown parent will shutdown the parent process, but leave the children running.

shutdown children asks the parent to kill all its children, but keep running itself.

shutdown all asks the parent to kill all its children and then exit itself.

With shutdown delayed, the parent will close all listening sockets, i.e. it will not accept any new connections. It will then wait for all its children to die and then exit itself.

Several signals can be sent to the server to achieve the same effect. See below.

The capa command

The capa command is used to manage user defined capability sets. The following subcommands are supported:

list List IDs of all loaded capability sets.
load NAME Load a set of capabilities from disk. NAME is the file name of this list in the capadir directory and the ID that will be used in pproxy.
del NAME Delete a set of capabilities from pproxy memory.
show NAME Show the capabilities in a capability set.

Note that the capa command for pserv uses a different syntax!

The debug command

The debug can be used to enable or disable certain debug logging options. If debug is used without arguments, the current debug options are printed. If the debug command is followed by one of '=', '+', or '-' the debug options following after this character are set, added to the current set or deleted from the current set, respectively.

The following debug logging options are recognized:

AUTH Authentication details (but without passwords).
RINGD Communication with the ringd process.
CTRL Control requests and answers.
IO Low level IO functions.
MAIN General messages about what the program is doing.
NET Network stuff...
PASS Passwords are logged. This might be a security risk if somebody can access your logfiles, so this should normally not be used. Note that ALL includes this.
POP POP3 dialogs.
TLS SSL/TLS messages if compiled in.
ALL Pseudo option including all of the above.
NONE Pseudo option meaning 'no option'.

The vserv command

The POPular proxy features virtual server support. Depending on which IP number and port a request comes in, it can use different namespaces for authenticating a user. Currently there is a maximum number of 32 virtual servers compiled in. Virtual servers are configured with the vserv. Each virtual server has an ID which is used to address it with the configuration commands. The ID can be freely chosen, but only letters, digits, underscore, hyphens and dots are allowed. The following subcommands are recognized:

vserv list

Show a list of all configured virtual servers. Only the ID of the virtual server is shown. It can be used to show or set details of its configurations with other subcommands.

vserv flush

Deletes all virtual servers. All listening ports are closed.

vserv show VSERV

Show details of the configuration of the virtual server VSERV. The configuration is output in the format of the vserv conf command, so it can be easily cut-and-pasted. See below for the configuration options.

vserv conf VSERV [PARAMETER ARG] ...

Set configuration parameters for the virtual server VSERV. If VSERV doesn't exist it will be created. One or more parameters can be set in one command. Parameters that are not set are unchanged or get a default value for new servers. See below for a list of parameters.

vserv del VSERV

Delete the virtual server VSERV. The corresponding file descriptor is closed.

The following parameters can be set for virtual servers:

iface Interface this virtual server should listen on. If this is the string "ANY", this virtual server will be bound to IPADDR_ANY. Otherwise this must be an IP number or a host name. A host name will be resolved to the first IP number for this hostname at the moment the command is given. Obviously the IP number should belong to the host the pproxy command is running on. The IP number can only be changed if the virtual server is currently in the state "offline".
port This is the TCP port, this virtual server should listen on. It defaults to the well-known port for the protocol given as the prot parameter. The port can only be changed if the virtual server is currently in the state "offline".
prot This is the protocol that should be spoken on this virtual server. Currently POP3 and POP3s is supported. The default is POP3. See the chapter on SSL/TLS for details. This is only available if the server was configured with SSL/TLS support.
starttls Set this to "off" to disable the STARTTLS command. Set this to "optional" to allow the STARTTLS command. Set this to "force" to force use of the STARTTLS command before authentication. See the chapter on SSL/TLS for details. This is only available if the server was configured with SSL/TLS support.
capa This is the capability list that should be used on this virtual server. See the chapter about capabilities for details.
state Each virtual server can be in one of four states. See below for a list of states.
namespace This is the "namespace", that should be used for all authentications from users coming in on this virtual server. If the special name space "USER" is set here, the real name space will be set with the POP3 USER command. This is sometimes useful for access by the postmaster or support staff. Instead of sending the user name after the USER command, the client has to send the user name, an equal sign ('=') and the namespace after the USER command. See the Authentication chapter for more information about namespaces.
bannerok This is the POP3 greeting banner used when the virtual server is online. A "+OK" is output before the banner. The banner should be something like "host.doma.in POP3 server ready".
bannererr This is the POP3 greeting banner used when the virtual server is disabled. A "-ERR" is output before the banner. The banner should be something like "host.doma.in POP3 server currently disabled".

Most parameters can be changed at any time and will take effect immediately for any new connections. Old connections are never affected by any change in parameter.

A virtual server can be in one of the following states:

offline This virtual server is configured, but not in use. There is no file descriptor listening to the port. To change the IP number of port the virtual server has to be taken offline.
disabled The virtual server is listening on its port, but all connections will be greeted with the "bannererr" banner and immediately disconnected.
fake The virtual server is listening on its port, but all users will just see an empty mailbox. The client is asked for username and password, but it is NOT properly authenticated. The reason is that the virtual server might has been disabled by the admin, because the authentication is not working properly at the moment.
online The virtual server is online and working.

The backend command

The POPular proxy server can connect to several backend servers Currently there is a maximum number of 32 backends compiled in. Backend servers are configured with the backend. Each backend server has an ID which is used to address it with the configuration commands. The ID can be freely chosen, but only letters, digits, underscore, hyphens and dots are allowed. The following subcommands are recognized:

backend list

Show a list of all configured backends. Only the ID of the backends is shown. It can be used to show or set details of its configurations with other subcommands.

backend flush

Deletes configuration of all backends.

backend show BACKEND

Show details of the configuration of the backend BACKEND. The configuration is output in the format of the backend conf command, so it can be easily cut-and-pasted. See below for the configuration options.

backend conf BACKEND [PARAMETER ARG] ...

Set configuration parameters for the backend BACKEND. If BACKEND doesn't exist it will be created. One or more parameters can be set in one command. Parameters that are not set are unchanged or get a default value for new servers. See below for a list of parameters.

backend del BACKEND

Delete the backend BACKEND.

The following parameters can be set for all backends:

host Hostname or IP number of this backend. A host name will be resolved to the first IP number for this hostname at the moment the command is given.
port This is the TCP port, where the backend server should listens on. It defaults to the well-known port for the protocol given as the prot parameter.
prot This is the protocol that should be spoken with this backend. Currently only POP3, XPOP and CXPOP are supported. The default value is POP3.
state Each virtual server can be in one of three states. See below for a list of states.

Most parameters can be changed at any time and will take effect immediately for any new connections. Old connections are never affected by any change in the parameters.

A backend can be in one of the following states:

offline This backend is configured, but not in use. All connections that would result in a use of this backend will be closed after an error message is sent.
fake This backend is configured, but not in use. The proxy server will fake an empty mailbox.
online The backend server is online and working.

The pdm command

The pdm ist used to configure the authentication modules. The following sub commands are available:

pdm list

Show list of modules. This list is ordered. Modules will be called upon in order to find and authenticate an user.

pdm flush

Delete all modules.

pdm add ID MOD ARG ...

Add a module to the list of modules. ID is a unique ID of this module. MOD is the name of the module. The module will be looked for in the directory set in the config variable 'pdmdir'. A 'libpdm_' will be prepended before the module name and a '.so' appended. All arguments (ARG ...) will be handed over to the module.

pdm del ID

Delete this module from the list.

pdm reload ID

Reload module. The action depends on the module. Generally it will mean that files are reopend etc.

pdm show ID

Show module name and arguments with which this module was loaded.

The prng command

The prng ist used to seed the pseudo random number generator. It is only used when SSL/TLS is compiled in.

pdm FILENAME [BYTES]

Read BYTES bytes (default 1024) from file FILENAME. Normally the file will be the /dev/random for maximum security or /dev/urandom for somewhat less security. Reading from /dev/random might block if there is not enough entropy available. You can also read from a normal file if you have some random data in there. Make sure you understand what this is all about, otherwise your precious SSL/TLS server might not be so secure after all. Use this command before you issue any vserv commands, so that the PRNG is initialized before use.