Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
qpopper(8)		    System Manager's Manual		    qpopper(8)

       qpopper -- POP3 server (v4.1)

       /usr/local/libexec/qpopper [ [ address ]	[ : ] [	port ] ]
	    [ -b buildir ] [ -c	] [ -d ] [ -D drac-host	]
	    [ -e login_delay=nn,expire=nn ] [ -f config-file ]
	    [ -k ] [ -K	service	] [ -l0|1|2 ] [	-p0|1|2|3|4 ]
	    [ -R ] [ -s	] [ -S ] [ -t trace-file ] [ -T	timeout	]
	    [ -u ] [ -U	] [ -v ] [ -V ]	[ -x ] [ -y log-facility ]

       This man	page may be out	of date.  Please see the Administrator's Guide
       included	in the distribution or on the Qpopper web  site	 at  www.qpop-

       Qpopper	is  a  POP3 server to enable POP3 clients to read and download
       mail. This server implements the	POP protocol defined in	RFC  1939  and
       the RFC 2449 extensions.	 This implementation runs on a variety of Unix
       platforms, including Linux.

       The server also enables clients to send mail using XTND XMIT, which  is
       processed via sendmail(8).

	      If  compiled  as	a standalone daemon (instead of	being run from
	      inetd), you can can specify the IP address and/or	port number to
	      bind   to	  at   run-time	  as   parameter   1,	e.g.,  'popper -S' or 'popper 8110 -S -T600'.  If IPv6 support
	      is  compiled  in,	 address can be	also IPv6 address by enclosing
	      the address with `[' and `]'.  If	not specified, the IP  address
	      defaults	to all available.  The default port is 110 except when
	      _DEBUG (not simply DEBUG)	is defined, then it is 8765.

	      See the Administrator's  Guide  file  for	 more  information  on
	      standalone mode.

       -b bulldir
	      Turns  on	the bulletin feature and specifies the bulletin	direc-
	      tory path.  The command line overrides the compiled value	if  it
	      is  defined.   To	 enable	bulletins by default and specify a de-
	      fault bulletin directory during compilation, include  the	 --en-
	      able-bulletins=bull-directory  flag  when	 running  ./configure.
	      The usual	bulletin directory is /var/spool/bulls.

	      A	bulletin database can be used to track the  bulletins  instead
	      of  the  users'  home directory.	This feature is	enabled	by in-
	      cluding the  --enable-bulldb=bull-directory  flag	 when  running

       -c     Downcases	 user  names.	This  permits users to configure their
	      clients with user	names in UPPER or MiXeD	case, and still	login,
	      assuming their actual user name is all lower case.

       -d     Turns  on	 debug logging if compiled (pass --enable-debugging to
	      ./configure).  All debugging information	is  saved  using  sys-
	      log(8).  If this option is used, it should be first, so that de-
	      bug records are generated	for subsequent options.

       -D drac-host
	      If compiled with --enable-drac, specifies	the  drac  host.   De-
	      faults to	localhost.

       -e x=value,...
	      Sets  POP3  extensions.  Sets x to the specified value.  Used to
	      include Login Delay and/or Expire	response tags to the CAPA com-

	      Remember	neither	Expire nor Login Delay is enforced by qpopper;
	      Sysadmins	have to	implement them by some other means.   However,
	      you  can	enforce	 EXPIRE	 0  (no	retention at all) by using the
	      --enable-auto-delete flag	with ./configure.   This  causes  mes-
	      sages to be automatically	deleted	after they are downloaded.

       -f config-file
	      Reads additional run-time	options	from config-file.  See Config-
	      File Options for option names and	syntax.

       -k     Enables Kerberos authentication when qpopper has	been  compiled
	      with  --with-kerberos5.	You  must  already have	libraries that
	      support Kerberos.

       -K service
	      The specified Kerberos service is	used instead of	the  compiled-
	      in value.	 The default is	rcmd, but pop is also common.

       -l 0|1|2
	      Sets  TLS/SSL  handling.	Must have compiled with	OpenSSL	or SSL

	      0	is the default.	 TLS/SSL is not	supported.

	      1	enables	the STLS command.  This	permits	a  client  to  attempt
	      TLS/SSL negotiation after	connecting.

	      2	 Causes	Qpopper	to attempt TLS negotiation when	a client first
	      connects.	 This is for alternate-port support.

       -p 0|1|2|3|4
	      Sets plain-text password handling	options.  To use this  option,
	      you  must	have an	alternative to plain-text passwords available,
	      such as APOP.

	      0	is the default,	which permits plain-text  passwords  only  for
	      those users who are not in the APOP database.

	      1	 disables  plain-text  passwords for all users,	even those who
	      are not in the APOP database.

	      2	permits	plain-text passwords for all users, even those who are
	      in the APOP database (this allows	clients	to fall	back on	plain-
	      text authentication if they do not support APOP).

	      3	allows plain-text passwords only for connections on the	 loop-
	      back (127.*.*.*)	address.

	      4	 permits plain-text passwords only if TLS/SSL has been negoti-
	      ated for the  session  (requires	an  executable	compiled  with
	      OpenSSL or SSL Plus).

       -R     Disables reverse lookups on client IP addresses.

       -t trace-file
	      Turns  on	 debug logging if compiled (pass --enable-debugging to
	      ./configure) and writes the trace	information in trace-file  us-
	      ing fprintf(3V).	If this	option is used,	it should be first, so
	      that debug records are generated for subsequent options.

       -s     Turns on statistics logging using	syslog(8) or  trace-file.   At
	      the  end	of  each  popper session, the following	information is
	      logged: username,	number of messages deleted,  number  of	 bytes
	      deleted,	number of message left on server, number of bytes left
	      on server.

       -S     Enables server mode.  This mode reduces disk I/O and disk	 space
	      usage when popper	is used	on a system that serves	POP only users

       -T timeout
	      option changes the default compiled value	POP_TIMEOUT for	termi-
	      nating a session with a pop client.

	      When  the	 server	 is  waiting  for a command to arrive from the
	      client, it times out after the specified number of  seconds  and
	      terminates  the  session.	  This	avoids having popper processes
	      hang forever waiting for command input from clients  which  have
	      terminated abnormally or are hung.

	      A	 small value is	ok for small to	medium networks	where the net-
	      work delay is within a few seconds.  In this case	15-30  seconds
	      is  not  unreasonable.   Networks	 with  large delays in sending
	      packets (e.g., SLIP links) may require a larger value.  In  this
	      case 300 seconds (5 minutes) is not unreasonable.

	      Note  that  RFC  1939  requires a	minimum	of 600 second (10 min-

       -u     After a user authenticates, process options from a  file	called
	      .qpopper-options in the user's home directory.  This file	can be
	      owned by and writable by the user.

       -U     After a user authenticates, process options from a  file	called
	      .<user>.qpopper-options  in the spool directory, where <user> is
	      the user name.  This file	should not be owned by nor writable by
	      the user.

       -v     Report the current version and exit.

       -V     Report the current version and exit.

       -x     Disable use of XTND XMIT.	 NOTE: Administrators are strongly en-
	      couraged to disable XTND XMIT in favor  of  mechanisms  such  as
	      SMTP AUTH.

       -y  log-facility

       Processing Options are described	below.

   Processing Options
       Here   are  some	 options the values of which are announced to clients.
       Syntax of the options is:


       This sets option	opt to be value.  Multiple options can be specified at
       one instance and	are comma separated.

       The following are the options supported:

   Config-File Options
       You can set Qpopper run-time options either from	the command line or in
       a configuration file.

       Configuration files use different option	names and a  different	syntax
       than  the command-line (because command-line options are	limited	to one

       The general syntax of the config	file (in ABNF) is:

	    config-line	 ::= comment-line / reset-line / set-line

	    comment-line ::= "#" <comment-text to end of line>

	    reset-line	 ::= "reset" boolean-option

	    set-line	 ::= implicit-set / explicit-set

	    explicit-set ::= "set" option "=" value

	    implicit-set ::= "set" boolean-option

	    option	 ::= boolean-option / integer-option /
			     string-option / mnemonic-option

	    value	 ::= "true" / "false" /	integer	/ name

	    string	 ::= <"> 1*255 CHAR <">

	    CHAR	 ::= <any printable character except space or tab>

       In other	words the line starts with set or reset, then an option	 name,
       and either ends there or	has an = followed by a value.

       A  comment  line	 starts	with #.	 The rest of the line is ignored.  You
       can also	use # to end any line.	Everything else	on the line is a  com-

       Note  that  reset can only be used with boolean options.	 The = and the
       value are omitted when reset is used.  When set is used with a  boolean
       option, you can omit the	= and value if you wish	(it defaults to	true),
       or you can use any of the four values true, false, 1, or	0.

       Some options are	"restricted", meaning that they	can't  be  used	 in  a
       .qpopper-options	  file	 in  a	user's	home  directory	 and/or	 in  a
       <user>.qpopper-options file in the spool	directory.

       The following are the command line options you can use:

	   Type: Integer
	   Equivalent switch: "-elogin_delay=xx"
	   Restricted: no

	   Type: Integer
	   Equivalent switch: "-e expire=xxx"
	   Restricted: no

	   Type: Name
	   Equivalent switch: "-b bulldir"
	   Restricted: no

	   Type: Boolean
	   Equivalent switch: "-B"
	   Restricted: no

	   Only	valid if compiled with --enable-bulldb.

	   Type: Mnemonic
	   Equivalent switch: "-p0|1|2|3|4"

		  Permits clear-text passwords for any user not	 in  the  APOP

	   never  Clear-text  passwords	are never permitted.  Users not	in the
		  APOP database	are unable to use Qpopper.

	   always Clear-text passwords are always permitted, even for users in
		  the APOP database.

	   local  Clear-text passwords are permitted only when the client con-
		  nects	through	the local interface (127.*.*.*).

	   tls	  Clear-text passwords are permitted when TLS/SSL has been ne-
		  gotiated  for	 the session.  Available only if compiled with
		  OpenSSL or SSL Plus.

	   ssl	  (Same	as tls).
	   Restricted: not valid in a configuration file in  the  user's  home
	   directory nor in the	spool directory.

	   Type: Name
	   Equivalent switch: "-f config-file"
	   Restricted: no

	   Type: Boolean
	   Equivalent switch: "-d debug
	   Restricted: no

	   Only	valid if compiled with --enable-debug.

	   Type: Boolean
	   Equivalent switch: "-c"
	   Restricted:	not  valid  in a configuration file in the user's home
	   directory nor in the	spool directory.

	   Type: Name
	   Equivalent switch: "-D drac-host"
	   Restricted: no

	   Only	valid if compiled with --enable-drac

	   Type: Boolean
	   Equivalent switch: "-k"
	   Restricted: not valid in a configuration file in  the  user's  home
	   directory nor in the	spool directory.

	   Only	valid if compiled with --enable-kerberos5 or -DKERBEROS

	   Type: Name
	   Equivalent switch: "-K service-name"
	   Restricted:	not  valid  in a configuration file in the user's home
	   directory nor in the	spool directory.

	   Only	valid if compiled with --enable-kerberos5 or -DKERBEROS

	   Type: Integer
	   Equivalent switch: "-L msgs"
	   Restricted: no

	   Type: Boolean
	   Equivalent switch: "-R" (Sense reversed!)
	   Restricted: not valid in a configuration file in  the  user's  home
	   directory nor in the	spool directory.

	   Sense  reversed  from command-line switch.  Using -R	is the same as

	   Type: Boolean
	   Equivalent switch: "-S"
	   Restricted: no

	   Type: Boolean
	   Equivalent switch: "-s"
	   Restricted: no

	   Type: Integer
	   Equivalent switch: "-T timeout"
	   Restricted: no

	   Type: Mnemonic
	   Equivalent switch: "-l"

		  TLS/SSL not supported.

	   none	  (same	as default).

	   stls	  Enables support for the STLS command.

		  Enables alternate-port TLS/SSL.
	   Restricted: not valid in a configuration file in  the  user's  home
	   directory nor in the	spool directory.

	   Only	valid if compiled with OpenSSL or SSL Plus.

	   Type: Name
	   Equivalent switch: "-t logfile"
	   Restricted: no

	   Only	valid if compiled with --enable-debug.

	   Type: Integer
	   Equivalent switch: "-U"
	   Restricted:	not  valid  in a configuration file in the user's home
	   directory nor in the	spool directory.

	   Type: Integer
	   Equivalent switch: "-u"
	   Restricted: not valid in a configuration file in  the  user's  home
	   directory nor in the	spool directory.

	   Type: Boolean
	   Equivalent switch: "-x"
	   Restricted:	not  valid  in a configuration file in the user's home
	   directory nor in the	spool directory.

       The bulletin feature gives system administrators	a way to  send	impor-
       tant announcements to all POP users without having to do	mass mailings.

       The  bulletin  directory	contains one file per bulletin.	Each file con-
       tains a single mail message with	a header and body  in  normal  mailbox
       format.	The  first  line of each such bulletin must be a "From " line.
       The easiest way for sysadmins to	create such bulletins is to mail them-
       selves  a  copy	of  the	 bulletin using	the account to which they want
       replies to be sent, then	use their mail program to save the message  to
       a file in the bulletin directory	in mailbox format. The bulletin	direc-
       tory must be world readable.

       The name	of each	bulletin file begins with the bulletin number, and may
       optionally  continue  with any other characters.	E.g., the file name of
       bulletin	number 23 might	be "23.pophost_down_sunday".

       Popper creates a	file named .popbull in	the  home  directory  of  each
       user.   This file contains a single line	recording the highest numbered
       bulletin	received by the	user.

       Each time a POP client connects to the server, any new bulletins	 which
       the  user has not received previously are automatically appended	to the
       user's mail.

       When a bulletin is copied, the "To" header line	is  replaced  by  "To:
       username@thishost",  and	any "Status:" header lines are deleted.	Other-
       wise, the bulletin is copied as is.

       When a new user checks for mail the  first  time,  popper  creates  the
       .popbull	 file  in the user's home directory and	seeds it with the cur-
       rent maximum bulletin number. Thus new users do not get old bulletins.

       Bulletins can be	enabled	by default, and	the bulletin directory	speci-
       fied, by	including the --enable-bulletins=bull-directory	flag when run-
       ning ./configure.

       To use a	database instead of .popbull files in users' home  directories
       for tracking the	highest	bulletin seen by a user, include the --enable-
       bulldb=bull-directory flag when running	./configure.   You  must  also
       create two empty	files in the bulletin directory, called	bulldb.pag and
       bulldb.dir.  When a bulletin database is	used, qpopper checks  for  and
       uses any	.popbull files in the user's home directory, to	provide	conti-

       To specify the maximum number of	bulletins sent to new  users,  include
       the  --with-new-bulls  flag  when  running  ./configure.	  For example,
       --with-new-bulls=10 says	that new users get at most ten bulletins.

       The Qpopper server is a single program (called popper) that is launched
       by  inetd when it gets a	service	request	on the POP TCP port.  (The of-
       ficial port number specified in RFC 1939	for POP	version	3 is port 110.
       However,	 some  POP3 clients attempt to contact the server at port 109,
       the POP version 2 port.	Unless you are	running	 both  POP2  and  POP3
       servers,	 you  can simply define	both ports for use by the POP3 server.
       This is explained in the	installation instructions later	on.)

       The qpopper program initializes and verifies that the peer  IP  address
       is registered in	the local domain (unless the -R	command-line option is
       used), logging a	warning	message	when  a	 connection  is	 made  with  a
       client  whose  IP  address does not have	a canonical name.  For systems
       using BSD 4.3 bind, it also checks to see if a  canonical  name	lookup
       for the client returns the same peer IP address,	logging	a warning mes-
       sage if it does not.

       The server enters the authorization state, during which the client must
       correctly identify itself by providing a	valid Unix userid and password
       on the server's host machine (or	successfully authenticate  using  APOP
       or AUTH).  No other exchanges are allowed during	this state (other than
       a request to quit.)  If authentication  fails,  a  warning  message  is
       logged and the session ends.

       Once  the user is identified, qpopper changes its user and group	ids to
       match that of the user and enters the transaction  state.   The	server
       makes  a	 temporary  copy  of the user's	maildrop which is used for all
       subsequent transactions (unless running in server mode  ).   These  in-
       clude  the bulk of POP commands to retrieve mail, delete	mail, undelete
       mail, and so forth.

       When the	client quits, the server enters	the final update state,	during
       which  the  network connection is terminated and	the user's maildrop is
       updated with the	(possibly) modified temporary maildrop.

       The POP server uses syslog to keep a record of its activities.  On sys-
       tems  with BSD 4.3 syslogging, the server logs (by default) to the "lo-
       cal0" facility at priority "notice" for all messages  except  debugging
       which  is  logged  at  priority	"debug".   The	default	 log  file  is
       /var/log/messages.  These can be	changed, if desired.  On systems  with
       4.2  syslogging	all messages are logged	to the local log file, usually

       Qpopper logs debugging information when the -d parameter	 is  specified
       after  its invocation in	the inetd.conf file.  Care should be exercised
       in using	this option since it generates considerable output in the sys-
       log  file.  Alternatively, the "-t <file-name>" option places debugging
       information into	file "<file-name>" using fprintf instead of syslog.

       For SunOS version 3.5, the popper program is  launched  by  inetd  from
       /etc/servers.  This file	does not allow you to specify command line ar-
       guments.	 Therefore, if you want	to enable debugging, you can specify a
       shell  script  in  /etc/servers to be launched instead of popper	and in
       this script call	popper with the	desired	arguments.

       You can confirm that the	POP server is running on Unix by telneting  to
       port 110	(or 109	if you set it up that way).  For example:

       %telnet	110
       Connected to
       Escape character	is '^]'.
       +OK QPOP	(version 3.0) at starting.
       +OK Pop server at signing off.
       Connection closed by foreign host.

       The server implements several extended commands.

       XTND XMIT: Sends	a mail message using /usr/sbin/sendmail.

       XTND XLIST header [num]:	Extracts and returns the specified header line
       for the specified message number. If the	"num"  parameter  is  missing,
       returns	the  header  line for all the messages which are not currently
       marked for deletion.

       XMANGLE:	Can be used as a modifier to the TOP, RETR, LIST commands. The
       result is to condense MIME messages into	a single part. For example:

	      RETR 10 XMANGLE(text=html;headers=to:,cc:,from:,date:)
       results	in  transforming message 10 into a single part of content-type
       text/html with only those headers which were requested.

       Qpopper also supports the "-no-mime" user name hack.  As	a way  to  en-
       able  MIME-mangling with	clients	that do	not support XMANGLE, add "-no-
       mime" to	the user name.	For example, if	the userid is "mary", enter it
       in the client as	"mary-no-mime".

       /var/mail	       mail files
       /etc/ftpusers	       list of unwelcome/restricted users
       /etc/inetd.conf	       pop program invocation
       /etc/syslog.conf	       logging specifications
       /var/spool/bulls	       bulletins
       ~/.popbull	       largest bulletin	number seen by user

       inetd(8), inetd.conf(4),	sendmail(8)

       Randall	Gelles,	 Praveen  Yaramada, Laurence Lundblade,	Mark Erickson,
       Bob Campbell, Edward Moy, Austin	Shelton, Marshall T Rose, and cast  of
       thousands  at  Rand,  UDel, UCI,	QUALCOMM Incorporated and the Internet
       user community.

4.3 Berkeley Distribution	 26 April 2010			    qpopper(8)


Want to link to this manual page? Use this URL:

home | help