===== Setting up the vacation(1) email auto-responder on SDF: =====

==== What: ====

The vacation(1) tool allows users to schedule automated email replies, useful for letting people know when you're away for a while.

==== Prerequisites: ====

  * SDF ARPA membership or higher
  * public key authentication (only for Meta Array users)

==== How vacation(1) works: ====

The tool uses two files - "$HOME/.vacation.msg" and "$HOME/.vacation.db" by default - to a) issue an auto-reply message, and b) track who and when a sender was replied to. vacation(1) is usually called via a user's "$HOME/.forward" file, but as the tool can read from stdin(4) there are other possibilities, ie. in conjunction with procmail(1).

=== Basic setup procedure: ===

  * initialize the DB file; initialization creates the DB file if it doesn't exist and sets/resets the vacation interval timer - the period it waits to resend an auto-reply. The default interval is one (1) week; to specify an different interval use "'-t nu'", where "n" is an integer and "u" is "s", "m", "h", "d", or "w" (seconds, minutes, hours, days, weeks; week is default). If "n" = 0 and "u" is omitted, a notice is sent for every message. If "n" is set to a very large number, say 9999, no sender will ever receive more than one notice.
  * create the auto-reply message. The message needs to be a routable email file with a header and body section. A "$SUBJECT" variable is supported for a more customized response.
  * edit the "$HOME/.forward" file to pipe mail through vacation(1); it's good idea to test the configuration beforehand using the vacation(1) "'-d'" debug option.

==== Some examples: ====

=== ex.1) minimal setup using defaults: ===

  % vacation -I                       # initialize DB; defaults to 30 days

  % cat > $HOME/.vacation.msg         # create minimal auto-reply message
  From: sdf_user@sdf.org
  Subject: Vacation notice
  Precedence: bulk

  I will be out of the office until next week.
  ^D

  % cat > $HOME/test.msg              # create test message for debugging
  From frog@mud.bog
  To: sdf_user@sdf.org
  Subject: Hop on over here

  Check out my new pad!
  ^D

  % vacation -d sdf_user < test.msg   # test w/o actually replying
   =>
      To: frog@mud.bog
      Auto-Submitted: auto-replied
      From: sdf_user@sdf.org
      Subject: Vacation notice
      Precedence: bulk

      I will be out of the office until next week.

   note: if executed as-is more than once there won't be any output; use
         the '-t0' option to override the default 30 day response time.

  % cat > $HOME/.forward              # retain a copy &amp; pipe to vacation(1)
  \sdf_user, "|/usr/bin/vacation sdf_user"
  ^D

=== ex.2) customized auto-reply sent every 2 days: ===

  % vacation -I -t 2d                 # initialize DB; set timer to 2 days
  % cat > $HOME/.vacation.msg         # create custom auto-reply message
  From: sdf_user@sdf.org
  Subject: Out of the office
  Delivered-By: vacation(1) on SDF
  Precedence: bulk

  I will be out of the office until next week; please contact
  George about $SUBJECT if it's urgent.
  ^D

  % cat > $HOME/test2.msg             # create test message for debugging
  From frog@mud.bog
  To: sdf_user@sdf.org
  Subject: the penski account

  Can you get this done this week?
  ^D

  % vacation -d sdf_user < test2.msg  # test w/o actually replying
   =>
      To: frog@mud.bog
      Auto-Submitted: auto-replied
      From: sdf_user@sdf.org
      Subject: Out of the office
      Delivered-By: vacation(1) on SDF
      Precedence: bulk

      I will be out of the office until next week; please contact
      George about the penski account if it's urgent.

  % cat > $HOME/.forward  # retain a copy &amp; pipe to vacation(1)
  \sdf_user, "|/usr/bin/vacation sdf_user"
  ^D

=== ex.3) SDF Meta Array setup: ===

SDF users who have their mail sent to the Meta Array (host //ma.sdf.org//) will need to use ssh(1) with public key authentication to the SDF Cluster (host //tty//) as vacation(1) is not available natively on the Meta Array.

Basic setup:

  - setup vacation(1) on the SDF cluster as previously shown
  - setup ssh(1) [[http://sdf.org/?tutorials/SSH-SDF#public_key|public key authentication]] to host //tty//
  - on //ma.sdf.org// create a test.msg and test things before committing:
    sdf_user@ma: cat test.msg | ssh sdf_user@tty "cat - | vacation -d -t0 sdf_user"
     =>
        To: frog@mud.bog
        Auto-Submitted: auto-replied
        From: sdf_user@ma.sdf.org
        Subject: Vacation notice
        Precedence: bulk
        ...
  - edit "$HOME/.forward" on //ma.sdf.org// like so:
    # .forward
    \sdf_user, "| ssh sdf_user@tty 'cat - | vacation sdf_user' "

=== ex.4) using vacation(1) with procmail(1): ===

Users of the procmail(1) program probably won't want to disable it just to make use of vacation(1). The following illustrates how to integrate vacation(1) into a typical user's "$HOME/.procmailrc" file; it should be inserted above any "delivery" recipes so all messages are passed through:

  # ~sdf_user/.procmailrc
  ...
  ## selective vacation(1) auto-responder filter setup:
  VACATION_SENDER=`formail -rx "To:"`
  VACATION_LIST=$HOME/.vacation.list
  VACATION_MSG=$HOME/.vacation.msg
  VACATION_DB=$HOME/.vacation.db

  ## Send vacation(1) notification if SENDER is in VACATION_LIST :
  :0 c  # "c" => keep a copy of msg
  ## uncomment next line to do selective notifications
  #* ? egrep $VACATION_SENDER $VACATION_LIST
  | /usr/bin/vacation -F R -f $VACATION_DB -m $VACATION_MSG sdf_user

The "$HOME/.vacation.list" is just a simple text file listing those email addresses you want to send notifications to, one per line. If you don't need the functionality just leave the "'egrep'" line commented out.

Note that "$HOME/.vacation.db" still needs to be initialized since this filter is just a pipe to vacation(1) which does the real processing.

==== Misc: ====

  * There is a "pure procmail" filter option that implements much of the vacation(1) functionality; see the procmailex(5) manpage for code.
  * Passing the "'-F R'" option to vacation(1) forces checking of the Return-Path: field which can help in some cases. See the vacation(1) manpage for details as well as other options.
  * The "$HOME/.vacation.db" file is a hashed Burkeley DB binary file. It can be read somewhat using strings(1); useful for determining who has been auto-replied to:
        % strings $HOME/.vacation.db | grep "@"
        frog@mud.bog
        itchy@bed.bug

\\

----

$Id: vacation_auto-responder.html,v 1.4 2014/11/23 00:05:00 jgw Exp $