@Mail System Documentation : v 3.4
The latest version of this file can be found at:
http://atmail.nl/docs/


@Mail POP3 Server configuration

1 Introduction: What is @Mail POP3

2 Configuring @Mail POP3 Server
    2.1 Running via Inetd
    2.11 Running via Xinetd
    2.2 Running via command line
    2.3 Relay Configuration
    2.4 Testing

3 Troubleshooting

4 Contact Information

1 Introduction: What is POP3?

@Mail POP3 allows your @Mail users access their eMail with a POP3 client like Eudora or Outlook. If you have configured @Mail to run as a Server with it's own users that can send / receive email.

If you wish to configure @Mail as a web interface to access other POP3 accounts, Please see @Mail POP3 Client Configuration

The @Mail POP3 server can be run in one of two ways; inetd or standalone. For larger userbases running the POP3 server as standalone will increase performance.

2 Configuring @Mail POP3 Server

The install.pl script for @Mail can automatically configure the @Mail POP3 server on your system. It is recommended you run this utility to setup the POP3 service.

Optionally you can manually configure the POP3 server for your system. Configuration the @Mail POP3 Server is done via the atmaildir/modules/pop3server/pop3.conf file.

$port = shift || 110;

If you are already running a POP3 Server on port 110 that you can not disable, you need to run @Mail on a different Port. You can set the port here. If you can not run port 110, change this to port 1100

$server = "\@Mail POP3 Server";

This is what people will see if they telnet into your POP3 Server.

$timeout = 1800;

The idle timeout in seconds before users must login again

$userid = "nobody"

This must the same username that @Mail is running as, If you are running @Mail via the web, this will be your web-server user.

$smtpauth = "/etc/mail/access";

Feature to add users IP address to a file, allowing users to relay via the SMTP server

2.1 How to install via inetd

Edit /etc/inetd.conf

If you are running an other POP3 server that you are not using, make sure that you comment it out.

#pop-3 stream tcp nowait root /usr/sbin/tcpd ipop3d -s -d

Add a line similar to:

pop-3 stream tcp nowait [atmailuser] [atmaildir]/modules/pop3server/pop3-inetd.pl pop3-inetd.pl

Where [atmailuser] is the username with permissions over @Mail. Generally the Webserver user apache or nobody. Define the [atmaildir] to your pathname of @Mail.

Note: Make sure that you are careful when configuring Inetd. If Inetd fails to restart you may not be able to access your server via Telnet / SSH / FTP.

2.11 How to install via Xinetd

New releases of RedHat Linux and other distributions of @Mail replace the existing inetd daemon with a new and improved Xinetd.

Xinetd is recommended over the traditional inetd. Enhancements include:

  • Increased security. The number of threads/connections from specified IPs can be controlled
  • Xinetd will pass the remote IP address of the client connecting. Allowing the POP3 server to update the SMTP access file for relaying messages out.
  • Increased logging capability

To configure the @Mail POP3 server using Xinetd; modify the configuration file with a new entry for the pop3 service.

Typically the configuration file is located at: /etc/xinetd.conf

If your Xinetd.conf file includes:

includedir /etc/xinetd.d

You must create a new file in /etc/xinetd.d/atmailpop3 with the configuration below.

service pop-3
           {
           flags = NAMEINARGS
           socket_type = stream
           protocol = tcp
           wait = no
           user = [atmailuser]
           server = /[atmaildir]/modules/pop3server/pop3-inetd.pl
           server_args = pop3-inetd.pl
           }

Where [atmailuser] is the username with permissions over @Mail. Generally the Webserver user apache or nobody. Define the [atmaildir] to your pathname of @Mail.

After editing the configuration file, restart the Xinetd process using the commands below

shell# /etc/init.d/xinetd restart
shell# killall -HUP xinetd

Test the new POP3 server is live by access port 110 on your server.

shell# telnet localhost 110
Trying localhost...
Connected to localhost.
Escape character is '^]'.
+OK Welcome to the @Mail POP3 Server. Authenticate yourself.

Once you have successfully installed the POP3 service you will be greeted with the above text. If the configuration failed, check your xinetd.conf does not have a previous pop3 service defined.

You can also view the log file for Xined, typically in /var/log/messages or /var/log/secure

Note: Make sure that you are careful when configuring Xinetd. If Xinetd fails to restart you may not be able to access your server via Telnet / SSH / FTP.

2.2 How to Install standalone server

The pop3.pl can run as a standalone daemon. This mode of operational is recommended for larger userbases. The main advantage is the increased performance over inetd configuraiton ( less overhead to accept new connections )

root#: nohup perl pop3.pl [port optional] &

This will leave the process in the background, accepting connections for POP3 clients. Running it on STDOUT can be helpful to see incoming connections, you can also pipe the output to a file for logging purposes.

The POP3 daemon runs standard on port 110 on all IP addresses on the server. You may need to disable your current pop3 server in /etc/inetd.conf to free the port for @Mail

The POP3 server can be configured to listen on another port or IP address by editing the pop3.conf file.

Note: Make sure that you add the @Mail POP3 server to your boot script to automatically startup @Mail. For RedHat systems you can configure the startup script by running:

root# cd atmail/modules/pop3server/
root# cp atmail-startup.sh /etc/init.d/atmailpop3
root# chmod 755 /etc/init.d/atmailpop3
root# ln -s /etc/init.d/atmail /etc/rc.d/rc6.d/K90atmailpop3

You can use the /etc/init.d/atmailpop3 command to control the POP3 server, e.g

root# /etc/init.d/atmailpop3 start

2.3 Relay Configuration

When a user connects via the POP3 server their IP address can be appended to a file. The SMTP server can be configured to read this file for relay permissions. For @Mail to receive the IP address of the remote caller the server must be configured via Xinetd or standalone. The default inetd daemon does pass the IP address of the users connection to external programs.

To configure the POP3 server for Sendmail:

First edit the pop3.conf with the following:

$smtptype = "sendmail";

$smtpauth = "/etc/mail/access";

$makemap = "1";

Where /etc/mail/access is the location of your Sendmail access file (See the sendmail.cf for the exact pathname)

The permissions of the $smtpauth file must be owned by the user defined in the pop3.conf file.

root# chown nobody /etc/mail/access*

To configure the POP3 server for Exim:

$smtptype = "exim";

$smtpauth = "/usr/exim/relay-access";

The permissions of the $smtpauth file must be owned by the user defined in the pop3.conf file.

To configure the POP3 server for qMail:

The setup of qMail to read the @Mail relay file requires extra configuration of the SMTP server. To begin you must declare the following the the pop3.conf

$smtptype = "qmail";

$tcprules = "/usr/local/bin/tcprules";

$smtpauth = "/path/to/atmail/modules/pop3server/tcp.smtp";

$tcpauthdb = "/path/to/atmail/modules/pop3server/tcp.smtp.db";

The permissions of the $smtpauth and $tcpauthdb file must be owned by the user defined in the pop3.conf file (usually the Webserver user).

Each users IP which authenticates successfully via the POP3 server will be added to the tcp.smtp file and rebuilt into the tcp.smtp.db format readable by qMail.

The format of tcp.smtp follows:

127.0.0.1:allow,RELAYCLIENT=""

Where 127.0.0.1 is the IP address of the remote user. The above definition allows the specified IP address to relay messages via the SMTP server.

Next qMail must be configured to read the tcp.smtp.db file for which hostnames can relay messages. To allow @Mail users to relay via the SMTP server run tcpserver like so:

root# tcpserver -x/path/to/atmail/modules/pop3server/tcp.smtp.db -uqmaild -g101 0 smtp /var/qmail/bin/qmail-smtpd &

Replace qmaild with your qmaild user ID and 101 with your nofiles group id, and make sure the pathname to the tcp.smtp.db file is correct.

NOTE: If you're already starting your qmail-smtpd service in a script that runs as part of your boot process, don't start it again with the above tcpserver line; just make sure that your script includes the -x/path/to/atmail/modules/pop3server/tcp.smtp.db option.

For systems that do not have the tcpserver binary ( optional for a default qMail installation ) Then you'll need to download and install a copy of the ucspi-tcp package. The current version is available from http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz.

2.4 Testing

To work with more than one domain, the domain must be given with the username.

Username: username#domain
Password: password

Or:

Username: username@domain
Password: password

Depending on the POP3 client, the configuration will vary. Most new clients will accept the user@domain format.

For additional domains, users must authenticate by user@hostname

root:# telnet domain.com 110
Trying 243.189.1.4...
Connected to main.
Escape character is '^]'.
+OK Welcome to @Mail POP3 Server. Authenticate yourself.
user ben@wapatmail.com
+OK Password required for ben@wapatmail.com
pass benben
+OK ben has 1 messages (2816 octets)
retr 1
+OK 2816 octets
Received: (netbased@localhost) by netbasedsoftware.com (8.9.2) id PAA32211;
Thu, 14 Sep 2000 15:42:51 GMT
Date: Thu, 14 Sep 2000 15:42:51 GMT
Message-Id: 200009141542.PAA32211@netbasedsoftware.com>
To: ben@wapatmail.com
X-Uidl: 968946171264
From: info@CGIsupport.com
Subject: Welcome Ben to your new account!
Content-Type: text/html;
X-Mailer: @Mail 3.1 (http://webbasedemail.net)


[themsg]
.
quit
+OK Goodbye (No msgs deleted)
Connection closed by foreign host

3 Troubleshooting

While the POP3 server is easy to setup it depends on the correct configuraiton of the pop3.conf file, permissions, and requires no existing POP3 servers installed on the same port.

  1. ERR bind: Address already in use at pop3.pl
    If you receive the following when trying to start the pop3.pl command an existing POP3 server is already running on your system.

    Verify the system /etc/inetd.conf and /etc/xinetd/* does not contain an existing POP3 server. Disable the existing daemon then start the @Mail POP3 server again.

  2. POP3 error '/path/to/atmail/modules/pop3server/tcp.smtp: Permission denied'
    This error is received if the relay file has incorrect permissions. You are required to change the ownership of the file to the user which runs the POP3 server.

    Sendmail:
    root# chown nobody /etc/mail/access*

    qMail
    root# chown nobody /path/to/atmail/modules/pop3server/tcp*

    Where nobody is the user which runs the @Mail POP3 server.

  3. When configuring qMail I receive the error 'tcpserver: command not found'
    For qMail to parse the @Mail relay file you must configure the ucspi-tcp package for the SMTP server. qMail can then be configured to parse the @Mail relay file by running the startup command 'tcpserver -x/path/to/atmail/modules/pop3server/tcp.smtp.db -uqmaild -g101 0 smtp /var/qmail/bin/qmail-smtpd &'

4 Contact Support

For additional support, please visit our web site, http://webbasedemail.com
Or send us an eMail : support@CalaCode.com