postfixadmin/VIRTUAL_VACATION/INSTALL.TXT

##################################################
# Virtual Vacation for Postfix Admin Release 2.x #
##################################################
#
# Postfix Admin (Virtual Vacation)
# Originally authored by Mischa Peters <mischa at high5 dot net>
# Copyright (c) 2002 - 2005 High5!
# Licensed under GPL for more info check GPL-LICENSE.TXT
#

REQUIRED!
---------
There are a bunch of Perl modules which need installing, depending on your 
distribution these may be available through your package management tool, or
will need installing through CPAN.

A full list of required modules can be found in the source of vacation.pl.

It obviously relies on Perl

About Virtual Vacation
----------------------
The vacation script runs as service within Postfix's master.cf configuration file.
Mail is sent to the vacation service via a transport table mapping.
When users mark themselves as away on vacation, an alias is added to their account 
sending a copy of all mail to them to the vacation service.

e.g. mail to billy@goat.com will be delivered to 
    billy@goat.com AND 
    billy#goat.com@autoreply.goat.com

Mail to @autoreply.goat.com is caught by the vacation.pl script and a reply 
will be sent based on various settings. By default a reply is only sent once.


Install Virtual Vacation
------------------------

1. Create a local account
-------------------------
Create a dedicated local user account called "vacation". 
This user handles all potentially dangerous mail content - that is why it
should be a separate account.

Do not use "nobody", and most certainly do not use "root" or "postfix".  The
user will never log in, and can be given a "*" password and non-existent
shell and home directory.

This should look like this:

#/etc/passwd
vacation:*:65501:65501:Virtual Vacation:/nonexistent:/sbin/nologin

#/etc/group
vacation:*:65501:


2. Create a directory
---------------------
Create a directory, for example  /var/spool/vacation, that is accessible
only to the "vacation" user. This is where the vacation script is supposed
to store its temporary files. 


3. Copy the files
-----------------

Copy the vacation.pl file to the directory you created above:

  $ cp vacation.pl <HOME>/vacation.pl
  $ chown -R vacation:vacation <HOME>

Which will then look something like:

-rwx------   1 vacation  vacation  3356 Dec 21 00:00 vacation.pl*


4. Setup the transport type
---------------------------
Define the transport type in the Postfix master file:

#/etc/postfix/master.cf:
vacation    unix  -       n       n       -       -       pipe
  flags=Rq user=vacation argv=/var/spool/vacation/vacation.pl -f ${sender} -- ${recipient}

5. Setup the transport maps file
--------------------------------

Tell Postfix to use a transport maps file, so add the following to your
Postfix main.cf:

#/etc/postfix/main.cf:
transport_maps = hash:/etc/postfix/transport

Then add the transport definition to the newly created transport file.
Obviously, change yourdomain.com to your own domain. This can be any
arbitrary domain, and it is easiest if you just choose one that will be used
for all your domains.

#/etc/postfix/transport
autoreply.yourdomain.com	vacation:

(You may need to create an entry in /etc/hosts for your non-existant domain)

Execute "postmap /etc/postfix/transport" to build the hashed database.

Execute "postfix reload" to complete the change.




6. Configure vacation.pl
------------------------

The perl vacation.pl script needs to know which database you are using, and also
how to connect to the database.

Namely :

Change any variables starting with '$db_' and '$db_type' to either 'mysql' or 'pgsql'.

Change the $vacation_domain variable to match what you entered in your /etc/postfix/transport 
file.

You can do this in two ways:

a) edit vacation.pl directly

b) create /etc/mail/postfixadmin/vacation.conf and enter your settings there

   Just use perl syntax there to fill the config variables listed in vacation.pl
   (without the "our" keyword). Example:
   $db_username = 'mail';


7. Check the alias expansion
----------------------------

Depending on your setup, you may have multiple 'smtpd' service definitions within 
your postfix master.cf file. This is especially the case if you are also using AMAVIS or
another content filtering system when mail is re-injected into Postfix using the smtpd daemon.

If you are, it's likely that alias expansion may happen more than once, in which case you 
may see vacation-style responses duplicated. To suppress this behaviour, you need to add :

  -o receive_override_options=no_address_mappings

For example :

smtp      inet  n       -       -       -       12       smtpd
    -o content_filter=amavis:[127.0.0.50]:10024
    -o receive_override_options=no_address_mappings

127.0.0.1:10025 inet    n   -   -   -   - smtpd
    -o smtpd_autorized_xforward_hosts=127.0.0.0/8
    -o smtpd_client_restrictions=
    -o smtpd_helo_restrictions=
    -o smtpd_sender_restrictions=
    -o smtpd_recipient_restrictions=permit_mynetworks,reject
    -o mynetworks=127.0.0.0/8
    -o receive_override_options=no_header_body_checks

	^^^ Alias expansion occurs here, so we don't want it to happen again for the
		first smtpd daemon (above). If you have per-user settings in amavis,
		you might want to have no_address_mappings in the smtpd on port 10025
		instead.


8. Security
-----------

If security is an issue for you, read ../DOCUMENTS/Security.txt




What do these files do?
-----------------------
When a user enables a vacation message on their account, the alias
definition is changed so that in addition to delivering to their own
mailbox, it also delivers to a dummy alias which calls the vacation.pl
program. In other words, if joeuser@domain.com enables their vacation, the
entry in the alias database table will deliver mail to
joeuser@something.com, as well as
joeuser#something.com@autoreply.yourdomain.com

vacation.pl then checks the database to see wether a user is on holiday and
what message to send back. Make sure that vacation.pl is able to communicate
to your database. In the first couple of lines you have to specify the
database, username and password for it.
NOTE: Make sure that the path to perl is correct.


I'm in trouble!
---------------
When something is not working there are a couple of files that you can have
a look at. The most important one is your maillog (usually in /var/log/).

Vacation.pl also has some debugging and logging capabilties. Check the top
of vacation.pl.


Done!
-----
When this is all in place you need to have a look at the Postfix Admin
config.inc.php. Here you need to enable Virtual Vacation for the site.