This is the preliminary page of couriersrs, an SRS implementation for the Courier mail server.
To build couriersrs you need to have the libpopt and libsrs2 libraries installed as well as a modern C++ compiler.
Writing a better documentation is on my TODO for couriersrs. But as I just started work on couriersrs, I was not yet able to write a complete documentation. I hope that the following instructions will help to to use couriersrs anyway.
Make sure that you have installed the prerequisites for couriersrs on your system. These should be a modern C++ compiler (I am using gcc 4.1.2, but other modern C++ compilers should work as well), the libpopt library for parsing the command line, and the libsrs2 library, that does the actual SRS work.
If you are installing the prerequisites as packages of your Linux distribution, make sure that you do not only install the runtime files of them, but also the development package for the libraries.
On a Debian system the packages you should install are: libsrs2-dev and libpopt-dev.
For short: Get the couriersrs package (see below), unpack it, configure it, compile it and install it.
The couriersrs package is unpacked using the tar command. Go to the directory
where you downloaded the couriersrs package and type tar xfvz couriersrs-VERSION.tar.gz followed by the return key. The package will then
get unpacked in a subdirectory of the current directory.
Change to the directory where couriersrs has been unpacked to. Now you have to
configure the couriersrs package using the configure script. Typically you will
use something like ./configure --prefix=/usr --sysconfdir=/etc for this. This
checks that everything couriersrs needs to get build is installed on your system
and aranges that courier gets installed as /usr/bin/couriersrs and will by
default read the SRS secret from the file /etc/srs_secret.
If the configure script fails, you should check that all prerequisites are
present on your system. If the configure script has finished successfully, it
is now time to compile couriersrs. This is done by entering make followed by
pressing the return key. You will then see how your compiler compiles the
couriersrs package.
If compilation of the source has been finished, it is now time to install the
couriersrs binary to the location, where it will be used. This is done by
entering make install again followed by pressing the return key.
To check that couriersrs has been installed, please go to your home directory
and run couriersrs -v. If installation has succeeded, couriersrs will tell
its version and where it checks for the SRS secret by default (i.e. if you do
not explicitly provide an SRS secret on couriersrs' command line).
Couriersrs (and SRS in general) needs a secret, that protects the addresses it creates from being missused. Everytime couriersrs creates an address in forward operation or unmaps an address for delivering a bounce mail, it should use the same secret. Else couriersrs will not allow the bounce mail to be routed back to the sender of the original mail.
The easiest way to configure couriersrs to always use the same secret when
handling addresses is to place the SRS secret on line one of the text file
/etc/srs_secret (the location may be different dependant on the arguments you
passed to the configure script above, but you will always see the location
couriersrs uses by running couriersrs -v). This file that contains the SRS
secret must be readable by any user that will call couriersrs on your
system. (Which users this might be depends on your courier installation. It may
be always the same user which is responsible for delivery of all mail addresses,
or it might be your system's users, if courier delivers mail using the user's
standard system accounts.) If having the secret in this file is no option for
you, you may also pass the secret on the command line of any invocation of
couriersrs using the --secret=SECRET_TO_USE option.
Now it is time to configure the first forwarding that will use SRS. This is done
using .courier files as normal. Without couriersrs you did this by placing the
destination e-mail address prefixed by an ampersand (&) symbol. To do an SRS
forward, instead of prefixing the destination e-mail address with the ampersand,
you will prefix it by a call to the couriersrs program. So for forwarding a
message to [email protected] you will place the following line in the .courier
file:
|/usr/bin/couriersrs [email protected]
All other information that couriersrs needs to do the forward will be read from
environment variables the courier mail server sets before calling
couriersrs. This is the original sender of the message and the original
recipient of it. Couriersrs will take the domain of the original recipient's
address to build the SRS address. If you do not want to have the created SRS in
this domain (e.g. because you do virtual hosting and do want to have all SRS
addresses on a common domain), you can pass couriersrs explicitly the domain it
uses to build the SRS address using the --srsdomain=DOMAIN option on
couriersrs' command line. Your .courier file might then look like the following:
|/usr/bin/couriersrs --srsdomain=srs.example.org [email protected]
As we rewrite the envelope source address of an e-mail while forwarding it, a mailserver that cannot deliver the forwarded will not bounce the message back to the original sender, but to the generated SRS address. This is why we also have to configure the mailserver to accept these e-mails, pass it to couriersrs which maps the address back to the original address and forwards it back to there.
All addresses couriersrs generates as SRS addresses start with “SRS0-” or “SRS1-”. So you should create the users “SRS0” and “SRS1” or “srs0” and “srs1” on your mail server (which pair of users you have to create depends on if your courier server operates in case sensitive (use SRS0 and SRS1) or case in-sensitive (use srs0 and srs1) mode. For both users you create a .courier-default file in their home directory containing the following line:
|/usr/bin/couriersrs --reverse
(Please note that if you are doing virtual hosting, you will need these two
users SRS0 and SRS1 on any of your domains, where SRS addresses are
generated. Therefore if you do virtual hosting, you might want to use a common
domain for creating all SRS addresses, so that you only have to create these two
users on this central domain. This is done using the --srsdomain option as
described above.)