use scalar IO::InnerFile::getline to work around an InnerFile bug

[debbugs.git] / debian / README.mail

Setting up MTAs for Debbugs
===========================

Config
------
Be sure to set the $gMailer variable correctly in /etc/debbugs/config.
The options are (all lower case) exim, qmail and sendmail.


Exim 4
------
The exim 4 setup supports virtual domains. This doesn't hurt on a
dedicated system. File names are for systems that use exim4's split
config scheme. If you use something else, you'll need to put the
configuration options in yourself at the appropriate place (most
likely /etc/exim4/exim4.conf or /etc/exim4/exim4.conf.template).

Create a non-root user with a non-root group as its primary group.
We'll use Debian-debbugs as the user and group:
 # adduser --system --group --home /var/lib/debbugs \
   --no-create-home --disabled-login --force-badname Debian-debbugs

This user needs to be able to write to /var/lib/debbugs.

/etc/exim4/conf.d/main/03_debbugs:
DEBBUGS_DOMAIN = <domain name>
DEBBUGS_USER = Debian-debbugs
DEBBUGS_GROUP = Debian-debbugs

/etc/exim4/conf.d/transport/30_debbugs:
debbugs_pipe:
  debug_print = "T: debbugs_pipe for $local_part@$domain"
  driver = pipe
  user = DEBBUGS_USER
  group = DEBBUGS_GROUP
  command = /usr/lib/debbugs/receive
  return_output

/etc/exim4/conf.d/router/250_debbugs:
debbugs:
  debug_print = "R: debbugs for $local_part@$domain"
  driver = accept
  transport = debbugs_pipe
  local_parts = submit : bugs : maintonly : quiet : forwarded : \
                done : close : request : submitter : control : ^\\d+
  domains = DEBBUGS_DOMAIN

bounce_debbugs:
  debug_print = "R: bounce_debbugs for $local_part@$domain"
  driver = redirect
  allow_fail
  data = :fail: Unknown user
  domains = DEBBUGS_DOMAIN

The bounce_debbugs router bounces all mail for the DEBBUGS_DOMAIN that
hasn't been picked up by the debbugs router. If you want addresses
from that domain that do not belong to debbugs to be handled normally,
simply omit that router. However, since the pattern on deb debbugs
router match a significant subset of the domain's local parts, it is
strongly recommended to use a dedicated domain for debbugs.


Exim 3
----
I've seen two types of Exim 3 set ups being used:

 1) If the machine is dedicated and all e-mail goes to the debbugs script,
    add this in the transport section:

debbugs_pipe:
  driver = pipe
  user = <some non-root user>
  group = <some non-root group>
  command = /usr/lib/debbugs/receive
  return_output

    Do not use root user/group, it is very unsafe. You could even add a new
    (locked) account "debbugs", and use that. Either user or group needs
    write access.

    And AT THE TOP of the directors section, add this:

debbugs:
  driver = smartuser
  transport = debbugs_pipe
  local_parts = submit:bugs:maintonly:quiet:forwarded:done:close:request:submitter:control:^\\d+

 2) If the domain is a virtual host on a machine that needs it, there are
    many ways of handling it.  I think the neatest was to use the above
    transport and director, except to add the following line to the
    director's options:

  domains = <domain name>

    Alternatively, Chad Miller <cmiller@surfsouth.com> suggests:

    The method I discovered involved adding at the top of the routers section:

debbugs_router:
  driver = domainlist
  transport = debbugs_transport
  route_list = "bugs.foo.bar;bugs.baz.quux"

    where bugs.foo.bar and bugs.baz.quux are mail-domains for which I want to
    receive bug requests only.
    Next, add anywhere in the transports section:

debbugs_transport:
  driver = pipe
  command = /usr/lib/debbugs/receive
  user = <some non-root user>
  group = <some non-root group>
  current_directory = /etc/debbugs
  home_directory = /var/lib/debbugs/spool

    (current_directory may need to be /var/lib/debbugs/spool, depending on
    your setup.)

    Next, the mail domains MUST NOT be in the "local_domains" list!
    Instead, we MUST put them in the "relay_domains" list.

    Essentially, this tells exim that we agree ("relay_domains") to relay
    mail for those zones ("debbugs_router") and "send" the mail using a pipe
    ("debbugs_transport").


Qmail
-----
From Tommi Virtanen (tv@debian.org), amended by Daniel Ruoso
(daniel@ruoso.com):

Here's my suggestion for safe & secure installation under qmail:
        
Create a separate user for the debbugs system.
        # adduser --system --group --home /home/misc/debbugs debbugs
Give control of a virtual domain to that user
        # echo bugs.example.com:debbugs >>/etc/qmail/virtualdomains
Give the user access to the bug databases
        # chown -R debbugs:debbugs /var/lib/debbugs/*
Set the BTS owner address
        # echo '&me@my.example.com' >~debbugs/.qmail-owner
Make the BTS handle it's mail
        # echo '|/usr/lib/debbugs/receive' >~debbugs/.qmail-default
Reload the virtualdomains config file
        # /etc/init.d/qmail reload
That's it!
        
Sendmail
--------
From Wichert Akkerman (wakkerma@debian.org):

First of all make sure that debbugs is configured for sendmail: look
at /etc/debbugs/config for the $gMailer variable and make sure it is
set to 'sendmail'.

Next make sure that your DNS is configured properly. For sendmail
this means you cannot use a CNAME for the debbugs-domain, since that
gets remapped to the canonical name and thus bypasses the mailertable
we need. This is an example of a working DNS entry:

        bugs            IN      192.168.2.100
                                0 MX mailgate.mors.net
                                HINFO "PC Pentium" "Debbugs 2.0"

Now that that is finished it is time to configure sendmail itself. First
make sure that sendmail does not consider the debbugs-domain as local by
making sure it is not listed in /etc/mail/sendmail.cw . Now start your
favourite editor and load /etc/mail/sendmail.mc . We need to make two
changes
there: add a mailertable and define the debbugs delivery agent.  The
mailertable is needed to tell sendmail to use the debbugs to deliver mail
destined for your debbugs server.

To enable the mailertable put the following line in your sendmail.mc file:

        FEATURE(mailertable, `text -o /etc/mail/mailertable')dnl

This tells sendmail to use the textfile /etc/mail/mailertable as the
database containing the table. You can also use a db database if you
want to add a lot of entries in there since that is faster. If you
want to do that use the following line instead:

        FEATURE(mailertable, `hash -o /etc/mail/mailertable.db')dnl

You can create the database using the following command:

        makemap hash mailertable.db < mailertable

Where mailertable is the textfile containing the data.

The next thing we need to do is tell sendmail about the debbugs delivery
agent. To do this add the following two lines to your sendmail.mc file,
preferably just after the MAILER commands:

Mdebbugs,       P=/usr/lib/debbugs/receive, F=SDFMlhudb80, U=<uid>:<gid>,
                S=10/30, R=20/30, D=/tmp, T=DNS/RFC822/X-Unix, A=receive $u

Where <uid> and <gid> should be replaced with the user and group you
use for debbugs.

Okay, we are now done with sendmail.mc and are ready to add the entry
in your mailertable. Save sendmail.mc and load /etc/mail/mailertable in
your editor. Put a single line in there just like this one:

        bugs.your.net           debbugs:yournet

(please note there are tabs between those words). This tells sendmail that
mail destined for the host bugs.your.net should be handled by the debbugs
delivery agent using yournet as the hostname. If you decided to use a db
database instead of the plain textfile don't forget to run makemap now!

Now the final step: run sendmailconfig to regenerate sendmail.cf and
restart sendmail with the new configuration. Your system should now
be up and running. Congratulations!


Postfix
-------
Let's assume that you are going to install bugs.domain.net, and you
are going to run it on the machine master.domain.net.

DNS setup: point the MX to the machine running debbugs:

        bugs.domain.net         MX      50      master.domain.net.

For postfix we have to do three things now:

 1. Open postfix for any recipient address on the domain
    bugs.domain.net
 2. Create a transport map to the debbugs script called
    ,,receive''.
 3. Make sure that mails are handed individually into the
    debbugs pipe. The receive script can only process mails
    with _one_ recipient.

So, create /etc/postfix/transport and insert:

        bugs.domain.net        debbugs:

This tells postfix to use the debbugs transport agent to deliver any
mail send to bugs.domain.net. Now we need to make a database from that
map, so that postfix can use:

        $ postmap hash:/etc/postfix/transport

So, create /etc/postfix/debbugs-recipients and put:

        @bugs.domain.net          ACCEPT

into it.

Here, we also need to make a database from that map, so
that postfix can use:

        # postmap hash:/etc/postfix/debbugs-recipients

In /etc/postfix/main.cf we enable the transport and local recipient
map by inserting the following lines:

        transport_maps = hash:/etc/postfix/transport
        # debbugs transport
        local_recipient_maps = hash:/etc/postfix/non-unix-users
        transport_maps = hash:/etc/postfix/transport
        debbugs_destination_recipient_limit = 1

The last line in the block above assures that mails pour into
the debbugs receive scripts on a one by one recipient basis.

At last we need to teach postfix what the debbugs transport agent is. Edit
/etc/postfix/master.cf and add:

        debbugs   unix  -       n       n       -       -       pipe
                flags=F user=debbugs argv=/usr/lib/debbugs/receive $recipient

This assumes that you are running debbugs with uid debbugs (the package
doesn't do that by default, but I generally chown /var/lib/debbugs/*
to a new debbugs account just to be safe).

Finally add bugs.domain.net to mydestination in main.cf:

        mydestination = $myhostname localhost.$mydomain bugs.domain.net

Now that all this is done, restart postfix and it should be working..

Wichert
Updated+modified by Mike (20120919)


Procmail and SpamAssassin
-------------------------

Publicly-accessible debbugs installations have been known to receive a lot
of spam. To combat this, some sites may find it useful to deliver mail to
debbugs via procmail and filter everything through a spam detector like
SpamAssassin. Here's a quick sketch of how to set this up (with Exim, but
other MTAs should be similar).

Arrange for mail to be delivered to procmail somehow. At the time of
writing, bugs.debian.org uses a .forward file like this:

        |procmail -p -m /org/bugs.debian.org/mail/.procmailrc

The first thing to do in .procmailrc is to set up various variables used
either implicitly or explicitly later on. Obviously, substitute
/org/bugs.debian.org and so on with details of your own installation, and
make sure any directories mentioned in mailbox names exist with appropriate
permissions under $MAILDIR. Many of these variables are documented in
procmailrc(5).

        MAILDIR=/org/bugs.debian.org/mail
        LOGFILE=$MAILDIR/.logfile
        COMSAT=no
        UMASK=003
        SPAMC=/usr/bin/spamc
        SENDMAIL=/usr/sbin/sendmail
        YEARMONTH=`/bin/date +%Y-%m`
        YEAR=`/bin/date +%Y`

Next, a safety catch (optional): we copy all incoming mail into an mbox.
This can easily grow quite large!

        :0c:
        backup/save-all.$YEARMONTH

At this point you can insert customized rules for your site that drop or
bounce particular types of mail. Then, filter through SpamAssassin and file
matches off into a separate mailbox:

        :0fw:spamc.lock
        | $SPAMC

        :0:
        * ^X-Spam-Flag: yes
        spam/assassinated.$YEARMONTH

(The lock here is due to resource problems during mail floods. There may be
better solutions.)

Now arrange for owner@bugs mail to be copied to another mailbox and sent on
to the right people. $LOCAL_PART is Exim-specific. Some people may prefer
this to come before the SpamAssassin check.

        :0
        ? test "$LOCAL_PART" = owner -o "$LOCAL_PART" = postmaster
        {
          :0c:
          owner/owner.$YEAR

          :0
          !foo@example.org, bar@example.org
        }

Everything else can now be saved to yet another mailbox and passed on to the
receive script:

        :0c:
        receive/receive.$YEARMONTH

        :0
        |/usr/lib/debbugs/receive

This should be sufficient, or even overkill, for a small installation.

Some sites need to block particular abusers from using particular services,
such as control@bugs, but don't want to ban them altogether. In this case an
autoreply approach may be useful.

        :0h
        * LOCAL_PART ?? control
        * !^FROM_DAEMON
        * !^X-Loop: owner@bugs\.example\.org
        * ^(From|Reply-To):.*(abuser1@example\.org|abuser2@example\.org)
        | (formail -r -I"From: owner@bugs.example.org" -I"Precedence: junk" \
                      -A"X-Loop: owner@bugs.example.org"; \
           echo "Processing commands for control@bugs.example.org:"; \
           echo; \
           echo "This service is unavailable.") | $SENDMAIL -oi -t

Although not documented here, similar autoreply tricks should be possible
without procmail. For instance, I would be surprised if Exim filters weren't
up to the task.