The configuration of the POPular server 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 pserv.PID.ctrl. PID, in this case, is the process id of the parent process. For easy access, there is a link from pserv.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 pserv has started, the file /etc/popular/pserv.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 following read-only variables are recognized by pserv. The content of these variables can be read by sending the command show VAR to the server. Calling show without argument will output a list of all configuration variables.
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'.
id | Id | Id (name) of server. This is always "pserv". |
pid | Int | The process id of the pserv parent process. |
rundir | Dir | This is the directory set by the --rundir option. |
sessionlimit | Int | The maximum compiled in value for maxsession. |
version | String | The version of the pserv program. |
The following read-write variables are recognized by pserv. The content of these variables can be read by sending the command show VAR to the server. They can be set by sending the command set VAR CONTENT.
backlog | Int (5-1024) | Backlog parameter for the listen() system call. The server has to be taken offline and online again for this value to take effect. |
capadir | Dir | This is the directory where the definitions for capability lists are to be found. Consult the chapter about capabilities for details. |
localip | Str | This is the IP number the server should bind to. It can
be "ANY", in which case the server will bind to
INADDR_ANY. A change will take effect
when the next server online is given.
|
logeachmsg | Bool | Can be 0 (off) or 1 (on). If this is on, the server will log deleted and read mail. This is an experimental feature and the format of this logs etc. might change. |
logfile | File | Name of the logfile. This will take effect the next time the log file is reopened. The default value for this is the parameter given to the --logfile option or, if no log file was specified on the command line, /var/log/popular/pserv<. |
maxlocalload | Int (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. |
maxsession | Int | Maximal number of 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. When maxsession is reached, a file called pserv.maxsession in the rundir (/var/run/popular) is created. If the session count decreases below maxsession-1, this file is deleted. pcheckd uses this file to inform the proxy that the maximum number of sessions is reached. |
popdir | Dir | Directory where all the mailboxes are. |
idletimeout | Time (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. |
sessiontimeout | Time (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 60*24 (1 day). If sessiontimeout is 0, no limit is enforced. |
servport | Int (1-65535) | TCP Port for the XPOP protocol. The server will listen on this port. |
statusheader | Bool | If this is set to true, a header line 'Status: RO' will be included in all mail that has already been read, i.e. that is found in the 'cur' directory. This line is not in the file on disk, the file on disk never changes, it is only included while sending out the mail to the client. This if off by default. |
To start and stop the server the server command is used. With server online the server will start listening on its TCP port. With server offline the server will close the listening socket. Make sure to set the right port number with set servport PORT before going online. With server status the current status of the server can be seen.
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 its listening socket, 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 is used to set the list of capabilities for this pserv. capa show will display the current setting. Use capa set NAME to choose which set of capabilities to use. NAME can be one of the following:
ERROR | The POP3 CAPA command will be answered with an error message simulating an old server without support for the CAPA command. |
NONE | The capability list is empty. |
DEFAULT | A default list of capabilities is used. This describes all the capabilities implemented by POPular and is consistent with the capability set of the pproxy program if it was configured with vserv conf VS capa DEFAULT. |
everything else | Must be a file name in the capadir directory. The contents of this file are aused as the list of capabilites. |
Note that the capa command for pproxy uses a different syntax!
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: