$Id: //depot/Teapop/0.3/doc/INSTALL#5 $ How To Install: =============== There are two versions of how to install, the first one is the quick way for people in a hurry and the second for those who want to know what they are actually doing. Read the one suiting you, or both if you prefer. Do note that in the examples below a dollar sign ($) means that you should type the text following it as a normal user. A pound sign (#) means that you must type the text following it as the superuser, root. Obviously you should NOT type the dollar-sign ($) nor the pound-sign (#). Verified platforms: ------------------- Teapop has been successfully compiled on the following platforms: OpenBSD 2.5, 2.6 Solaris 2.6 (With gcc) - Please read note at bottom Debian Since I don't have access to any systems with other OS's than the ones above I can't try compiling on them. Arriba, Arriba-Way: ------------------- $ ./configure $ make Now you need to become the superuser, usually done by typing su # make install Make sure you have the following line in /etc/services, if it's missing you need to add it. pop3 110/tcp Next step is to add the following line to the file called /etc/inetd.conf pop3 stream tcp nowait root /usr/local/libexec/teapop teapop Now you need to find out the pid number for inetd. If you're not sure how to get the pid number for inetd, just reboot the computer instead of doing the following step. A hint to find the pid number is to use ps(1). When you have the pid number, issue the following command: # kill -HUP pidnumber Done! Now enjoy your newly installed POP3-server. What am I doing-way: -------------------- The configure-script is a "normal" GNU autoconf script, which most people have run into when installing new programs. I will just explain the teapop-specific stuff here. You may mix the arguments explained below in any way you want, unless noted otherwise. You must specify all arguments you want on one command line; if you try to run configure with one argument first and then again with another argument, the first will get overridden. If configure is run without any arguments, it will check if the directory /var/mail exists. If it does, the configure script will assume that this is where all mailboxes are. If it doesn't find the directory, it will instead check if there is a directory called /var/spool/mail. If that directory doesn't exist either, configure will exit with an error and ask you to manually specify where your mailboxes are. There are two ways to specify where mailboxes are, one for the people using a mailspool and one for people who have the mailboxes in the users homedir. This argument will tell teapop where the DEFAULT mailbox is located. If you are using a teapop.passwd file, it will take precedence over the default location. The two ways, explained in more detail below, are mutually exclusive. If you specify both anyway, the homespool argument will take precedence over the mailspool argument. However, this behaviour might change at anytime without any notice and should not be depended upon. The first way, for those who are using a mailspool directory, is to use the --enable-mailspool switch. If you are using some other directory than the two default ones, or if you prefer using /var/spool/mail over /var/mail even if both exist, you will need to use this switch. Let's say that you are using /usr/spool/mail for your mailspool, then you would type: $ ./configure --enable-mailspool=/usr/spool/mail The second way is for all of you who have given up on mailspools, for one or another reason, and instead put the mailbox in the users homedir. If the mailbox is called Mail you would use the following: $ ./configure --enable-homespool=Mail Since POP3 (and mbox-format) isn't really suited for accessing a mailbox with more then one concurrent session there is a need to do some kind of locking. The default way to lock a users mailbix, in Teapop, is to use the flock(2) method. This is an advisory lock that responsible programs checks and honors. Unfortunally not all programs are responsible and in some instances the definition of responsible varies. Therefor you might prefer to use one of the other methods of locking a mailbox; fcntl, lockf and/or dotlock. fcntl is the posix locking, while lockf is another type of advisory locking. dotlock locking while make Teapop create a file with the same name as the users mailbox, but with ".lock" appended to the end. If you want to use another locking then the default (flock) you should specify this when running the configure-script: $ ./configure --enable-lock=fcntl It is also possible to specify more then one locking method to the configure-script by separating them with a colon: $ ./configure --enable-lock=flock,dotlock Beware that flock, fcntl and lockf may block each other, depending on your system. The POP3-protocol gives users two different ways to log on to the server. The normal way is the USER/PASS commands. That means that the client first sends USER username to the server and then PASS password. As you can see this will send the password in cleartext. The other way is to use the APOP command instead, which will send the password encrypted with a one time key. The APOP command however requires that the password exists in cleartext on the server, which means you can't use the system-passwords for APOP. Most UNIX systems keep all passwords for user accounts on the system stored in a one way encryption method, which means you can't figure out what the password really is. Teapop has the APOP support enabled by default, but some admins might want to turn it off, maybe because of the "problem" with APOP explained above. To turn it off use the following: $ ./configure --disable-apop One of the features in Teapop is it's native virtual pop (vpop) support. The vpop support will allow you to configure Teapop to do different things depending on what domain the user is coming from. For more information on how to configure the vpop support look in the sample vpop-configfile etc/teapop.passwd or etc/teapop.passwd.template, which is used to create the former file during a make. This will use up a couple of extra cpu cycles though. So if you have a busy site and don't need the vpop support, you can disable it at configuring time with the following: $ ./configure --disable-vpop Teapop supports the POP-before-SMTP (or SMTP-after-POP) mechanism by writing the IP addresses of previously authenticated clients to a file. Most MTA's can use this file to allow relaying for the IP addresses listed in this file. To enable this support call configure with the following option: $ ./configure --enable-popauth-file This will write the IP addresses of the clients which authenticated correctly to the file "popauth" in the "var" directory of your Teapop installation. You can choose another location/filename for that file by passing it as a parameter to the configure option, e.g.: $ ./configure --enable-popauth-file=/etc/mail/popsmtp You need to call the cronpopauth.pl (see the bin subdirectory) regularly (e.g. by cron) to ensure that older entries are removed from that file. Remember to add all arguments you want to send to the configuring script. If you want to use the flock(3) method and disable APOP you would type: $ ./configure --enable-flock --disable-apop If you are happy with how Teapop configures itself by default you just need to run the configure-script without any arguments: $ ./configure Now you need to build Teapop. To do that just issue the following command: $ make When that is done you need to install Teapop. This has to be done as the superuser (root). Teapop will install itself in the correct places with the following command: # make install Now you are almost done. All you need now is to enable Teapop to startup when someone connects to your pop3 port (110). There are two ways to start Teapop, one is from inetd and the other way is to run it in standalone mode. The first, through inetd, is ok for small and medium sites but bigger sites are strongly recommended to use the standalone feature. Running Teapop through inetd: ----------------------------- Check in your /etc/services and make sure you have the following line in it, or add it if needed pop3 110/tcp Note: Some systems have pop-3 setup in /etc/services instead of pop3. If your system is one of them, either replace pop3 with pop-3 in the examples found here or add the above line. To start Teapop from inetd, add the following line to /etc/inetd.conf pop3 stream tcp nowait root /usr/local/libexec/teapop teapop Note: Some systems allow you to enchance your sites security by adding a tcpwrapper. Please check your system manuals for information to see if such exists and if so, how to use it. (Hint: typing "man tcpd" (without quotes) will give you the information on several system with tcpwrappers) If you already have a line starting with pop3, you need to either remove that line or add a # in front of it, which comments out the line. When that is done you need to issue a kill -HUP pid-of-inetd and then you are all set to go. Running Teapop through xinetd: ------------------------------ Some OS's have decided to remove the "standard" inetd and ship with xinetd instead. If you are running one of those, the above section will not work for you, instead you have to create a file called /etc/xinetd.d/teapop and the following in it: service pop3 { socket_type = stream protocol = tcp wait = no user = root server = /usr/local/libexec/teapop server_args = teapop } If you have installed Teapop in another directory than the default, you will need to change the server line to reflect the correct path. You need to restart xinetd for it to notice the change. Running Teapop as standalone: ----------------------------- Start Teapop with the -s argument and teapop will put itself into the background and start to listen on port 110. You want to do something like this: # ./teapop -s Note to Solaris users: ---------------------- If you are using Solaris, you must pay attention to the LD_LIBRARY_PATH environment setting. An incorrect setting may cause Teapop to not compile and/or not to start. When running the configure-script and compiling Teapop, /usr/ucblib must be present in LD_LIBRARY_PATH. Teapop needs the flock()-compability that is found in libucb, which is present in /usr/ucblib. If you want MySQL or PostgreSQL support, you need to also add the path to the lib-file for accessing respective database. This is a "design-feature" in Solaris, and not a restriction in Teapop.