See <URL:http://tmda.net/upgrade.html> for instructions on how to use
this file.

======================================================================

If you are upgrading from a release of TMDA < 0.90:

* If you are using Chinese in your TMDA templates, you must install
  the CJKCodecs Python package from http://cjkpython.i18n.org/.
  CJKCodecs has replaced the ChineseCodecs package.

======================================================================

If you are upgrading from a release of TMDA < 0.87:

* The OUTGOINGMAIL variable has been renamed MAIL_TRANSPORT, and its
  default value has also been changed from 'smtp' to 'sendmail'.

  If you desire SMTP transport, you need to set 
  MAIL_TRANSPORT = 'smtp' in your /etc/tmdarc or ~/.tmdarc.

  If you desire /usr/sbin/sendmail transport, you can take the
  default, and don't need to set MAIL_TRANSPORT.

  If you are running qmail and have previously set 
  SENDMAIL_PROGRAM = '/var/qmail/bin/qmail-inject', you need to change
  this to '/var/qmail/bin/sendmail', or simply comment this out and
  take the default value of '/usr/sbin/sendmail'.

  If you are running Exim, please make note of #1 under ``Main
  Configuration'' at http://tmda.net/config-pre.html#exim, as you may
  need to adjust your Exim configuration.

======================================================================

If you are upgrading from a release of TMDA < 0.83:

* The unmaintained tmda-gui and tmda-manager programs have been
  removed from the distribution.

======================================================================

If you are upgrading from a release of TMDA < 0.81:

* The {from,to}-mysql rules have been replaced by from-sql and
  to-sql.  See <URL:http://tmda.net/filter-sources.html> for details
  on the use of the new rules.

* The -domains argument to filter rules that search files or databases
  has been removed.  The domains of the sender or recipient addresses
  are now always added to the list of search keys.  The behavior of
  the rules is the same as before; you just don't need to specify the
  -domains argument anymore.

======================================================================

If you are upgrading from a release of TMDA < 0.79:

* The PURGED_HEADERS configuration variable has been changed to
  <URL:http://tmda.net/config-vars.html#PURGED_HEADERS_CLIENT>.  If
  you use PURGED_HEADERS in your config file you will need to change
  it to PURGED_HEADERS_CLIENT.

======================================================================

If you are upgrading from a release of TMDA < 0.78:

* The format of confirm_accept_url has changed.  This only affects you
  if you use tmda-cgi (version 0.08 or earlier) and URL confirmation.
  
  Please view the UPGRADE file of tmda-cgi version 0.09 for more
  information.  tmda-cgi 0.09 can be downloaded from:
  <URL:http://www.tmda.net/tmda-cgi/releases/>

======================================================================

If you are upgrading from a release of TMDA < 0.77:

* By default, tmda-filter now performs an automated cleanup of the
  pending queue upon receipt of an incoming message.  If you wish to
  use this feature, you should disable any cron jobs you might be
  running to periodically purge your pending queue of old messages.

  The default cleanup interval is approximately once per 100 incoming
  messages received.  To tweak this interval, or disable this feature,
  see <URL:http://tmda.net/config-vars.html#PENDING_CLEANUP_ODDS>.

  When this feature is enabled, the default lifetime for a message in
  the pending queue is 14 days.  Any message older than 14 days will
  be deleted.  If you wish to raise or lower this threshold, see
  <URL:http://tmda.net/config-vars.html#PENDING_LIFETIME>.

  This feature respects the
  <URL:http://tmda.net/config-vars.html#PENDING_DELETE_APPEND>
  setting.

======================================================================

If you are upgrading from a release of TMDA < 0.76:

* LOCALDATE has been deprecated.

======================================================================

If you are upgrading from a release of TMDA < 0.74:

* contrib/cgi has been removed.  tmda-cgi is now maintained/released
  as a stand-alone distribution to allow that effort more flexibility.
  Download at <URL:http://tmda.net/tmda-cgi/>

======================================================================

If you are upgrading from a release of TMDA < 0.72:

* contrib/vipmap-to-authmap has been removed.

======================================================================

If you are upgrading from a release of TMDA < 0.69:

* tmda-ofmipd now disables CRAM-MD5 negotiation when the -R or -A
  options are specified. See TMDA FAQ 5.8 for why.

* tmda-cgi now expects to find support files in the subdirectory
  ../display instead of display.  This better supports users who
  install tmda-cgi in their cgi-bin directory.  Use compile's -d
  option to override this default.

======================================================================

If you are upgrading from a release of TMDA < 0.68:

* tmda-ofmipd now forks into the background by default. Use the
  ``--foreground'' option to retain the old behavior.

======================================================================

If you are upgrading from a release of TMDA < 0.66:

* DELIVERED_CACHE and DELIVERED_CACHE_LEN are no longer used to store
  delivery status information about pending messages. Instead, a
  Maildir-like status flag (':3,R' and ':3,C') is appended to the
  filename to indicate delivery by release or delivery by
  confirmation.

  No action is required to accommodate this change, but if you use
  tmda-pending, you'll notice that previously delivered messages will
  now show up in the output until they are deleted or are cached with
  the ``--cache'' option.

======================================================================

If you are upgrading from a release of TMDA < 0.65:

* If you are using customized templates, you should replace
  %(envelope_sender)s with %(confirm_append_address)s in your
  confirm_request.txt. This is to support the new
  <URL:http://tmda.net/config-vars.html#PRIMARY_ADDRESS_MATCH>
  feature.

* When doing program deliveries to procmail, you should no longer be
  using the ``-f'' option. e.g,

  DELIVERY = "|/usr/bin/procmail -f $SENDER ~/.procmailrc-tmda"

  becomes

  DELIVERY = "|/usr/bin/procmail ~/.procmailrc-tmda"

* contrib/sample.tmdarc has been renamed contrib/sample.config.

======================================================================

If you are upgrading from a release of TMDA < 0.63:

* Python version 2.1 or greater is now required.  Upgrade at
  <URL:http://www.python.org/download/>

* When sending an auto response, a new configuration variable
  (AUTORESPONSE_INCLUDE_SENDER_COPY) is used to control whether a copy
  of the sender's message is included or not.  For available options,
  <URL:http://tmda.net/config-vars.html#AUTORESPONSE_INCLUDE_SENDER_COPY>

  If you are using customized templates, you should remove the last
  few lines in each template which include the sender's copy.  For
  example, in confirm_request.txt:

  --- Enclosed is a copy of your message.

  %(original_message)s

  Otherwise, you'll include two copies of the sender's message.

* When sending confirmation requests, Reply-To is now set from the
  confirm_request.txt template.  This is to allow the option to not
  include the confirmation address in a Reply-To header.

  If you use a customized confirm_request.txt, you'll need to add the
  following line to the top (header section) of your template:

  Reply-To: %(confirm_accept_address)s

======================================================================

If you are upgrading from a release of TMDA < 0.59:

* TMDA's auto-replies now include your FULLNAME in the From: header
  instead of just the e-mail address.  e.g,

  From: "Jason R. Mastaler" <jasonrm@nightshade.la.mastaler.com>
  Subject: Please confirm your message

  Set FULLNAME in your tmda config, to override the default value
  (taken from the password file).

* ADDED_HEADERS has been renamed ADDED_HEADERS_CLIENT.

======================================================================

If you are upgrading from a release of TMDA < 0.57:

* 'keyword' addresses now use an identifying string like 'dated' and
  'sender' addresses do.  'keyword' by default, and customizable via
  TAGS_KEYWORD.  This means you'll need to generate new addresses
  using `tmda-address', as your old ones will no longer work.

  If you want your old keyword addresses to be accepted until you can
  transition to the new format, you can add entries for them in your
  FILTER_INCOMING.  e.g,

  to jason-promos.8d06eu@mastaler.com ok
  to jason-stupid_promo.289j76@mastaler.com ok

* RECIPIENT_DELIMITER is no longer allowed to be part of the keyword
  in a keyword address.  `?' will be substituted for it when a new
  keyword address is created.

======================================================================

If you are upgrading from a release of TMDA < 0.56:

* The format for a confirmation request address is now:

  RECIPIENT-confirm-TIMESTAMP.PID.HMAC, instead of
  RECIPIENT-confirm-accept.TIMESTAMP.PID.HMAC
  
  The new format is detailed in CRYPTO.  Because of this change, it's
  recommended that you run tmda-pending to make sure your queue is
  free of legitimate messages, since the old confirmation addresses
  will no longer work.  

  If you are unable to do this and need temporary backward
  compatibility with the old format, there is a patch against 0.56
  available at:
  <URL:http://mla.libertine.org/tmda-users/200206/msg00193.html>

* Confirmed messages are now reinjected to the original envelope
  recipient address (RECIPIENT) rather than to:
  RECIPIENT-confirm-done.TIMESTAMP.PID.HMAC

  See CRYPTO for more details.

* TMDA now sends outgoing mail by handing it off to an SMTP server
  instead of the /usr/sbin/sendmail program.  By default it will use
  the standard SMTP port (25) on the local host.  You can modify this
  by setting the "SMTPHOST" variable in your tmdarc.  See
  http://tmda.net/config-vars.html for further information.

* tmdarc variable SENDMAIL has been renamed SENDMAIL_PROGRAM, but is
  irrelevant unless OUTGOINGMAIL = "sendmail".

* tmdarc variable PURGED_HEADERS now lists "Bcc:" and "Resent-Bcc" by
  default.  If you define this variable in your tmdarc, be sure to add
  these two headers.

* CRYPT_KEY should be removed from ~/.tmdarc or ~/.tmda/config.  Your
  secret key is now read from CRYPT_KEY_FILE, which defaults to
  ~/.tmda/crypt_key.  To make this conversion, move your existing
  CRYPT_KEY to ~/.tmda/crypt_key, but without the double-quotes.  e.g,

  if CRYPT_KEY = "df7a18a8d95f02ff94bf6463a8ec214cf20cb9e8"

  ~/.tmda/crypt_key should contain:
  df7a18a8d95f02ff94bf6463a8ec214cf20cb9e8

* ~/.tmdarc and ~/.tmda/config are no longer checked for file
  permissions.  Instead, make sure ~/.tmda/crypt_key is chmod 400 or
  600 (or 640 if ALLOW_MODE_640 = 1).

* An exception is no longer be raised if ~/.tmdarc or ~/.tmda/config
  is missing.  However, a ~/.tmda/crypt_key file is required.

* tmda-keygen now outputs an unquoted key instead of a CRYPT_KEY line.

* Template variables dated_cookie_address and sender_cookie_address
  were replaced with dated_recipient_address and
  sender_recipient_address, which are based on the RECIPIENT address.

======================================================================

If you are upgrading from a release of TMDA < 0.55:

* DELIVERY has replaced LOCAL_DELIVERY_AGENT.  If you wish to retain
  existing functionality, you can simply rename LOCAL_DELIVERY_AGENT
  to DELIVERY in your tmdarc, but be sure to add a `|' (pipe) to
  the front of the path to indicate a program delivery.  e.g,

  LOCAL_DELIVERY_AGENT = "/usr/bin/maildrop ~/.mailfilter_tmda"

  becomes
   
  DELIVERY = "|/usr/bin/maildrop ~/.mailfilter_tmda"

  However, you should also read about DELIVERY in
  http://tmda.net/config-vars.html, as it contains some significant
  enhancements that may simplify your overall configuration.  e.g, if
  the only purpose of the above ~/.mailfilter_tmda is to deliver to
  your mailbox, you can use the following instead for example:

  DELIVERY = "/var/mail/jasonrm"

* You should no longer specify 'subscribers' when using a from-ezmlm
  or to-ezmlm source.  Specify the parent directory instead, and
  'subscribers' will automatically be appended.  e.g,

  from-ezmlm ~alias/all-acl-users ok
  from-ezmlm ~alias/all-acl-users/mod ok
  from-ezmlm ~alias/all-acl-users/digest ok

* You should no longer specify 'config.db' or 'config.pck' when using
  a from-mailman or to-mailman source.  Specify just the list
  directory instead, and the configuration database will be located
  automatically.  e.g,

  from-mailman -attr=members ~mailman/lists/viewnet-news ok
  from-mailman -attr=digest_members ~mailman/lists/viewnet-news ok

======================================================================

If you are upgrading from a release of TMDA < 0.52:

* For its Python 2.x dependency, tmda.spec now has RPM look for the
  file "/usr/bin/python2" instead of the package "python2".

======================================================================

If you are upgrading from a release of TMDA < 0.50:

* Messages in the pending directory are no longer deleted after they
  are confirmed (or released) and delivered.  Now they are simply
  noted in the DELIVERED_CACHE file.  

* BOUNCE_TEXT_ALREADY_CONFIRMED has been deprecated.

* The confirm_accept.txt template has been modified.  The message body
  of the notification is no longer hardcoded, but rather stored in
  %(confirm_accept_text)s, which comes from one of the following
  tmdarc variables depending on context:

  CONFIRM_ACCEPT_TEXT_INITIAL
  CONFIRM_ACCEPT_TEXT_ALREADY_CONFIRMED
  CONFIRM_ACCEPT_TEXT_ALREADY_RELEASED

======================================================================

If you are upgrading from a release of TMDA < 0.49:

* Custom templates are now referred to by a template directory rather
  than individually.  Any templates found in this directory will be
  used, otherwise the default templates will be used.  You can specify
  a custom template directory in one of two ways:

  A TEMPLATE_DIR setting in your tmdarc.  This replaces use of
  CONFIRM_ACCEPT_TEMPLATE and CONFIRM_REQUEST_TEMPLATE.

  tmda-filter's -t option, which replaces both -A and -R.

* The 'unquoted' and 'parens' options to MESSAGE_FROM_STYLE have been
  deprecated.  'angles' now double-quotes the fullname only when
  necessary.

======================================================================

If you are upgrading from a release of TMDA < 0.48:

* As of v0.48, TMDA is released under the GNU General Public License
  (GNU GPL).  See COPYING for more information.

* qmail users now must invoke tmda-filter with 'preline' from their
  dot-qmail files.  e.g,

  |preline /usr/bin/tmda-filter

* Exim users must configure Exim to add a Return-Path header to
  messages from their address_pipe transport.  See the "TMDA
  Pre-Configuration" page (config-pre.html#exim) for more details.

* The 'to-autocdb' and 'from-autocdb' sources have been removed.  If
  you use the autocdb functionality, you will need to change these
  sources to 'to-file' or 'from-file', respectively, and add the
  '-autocdb' flag.  The match field is the name of the textfile
  without the '.cdb' extension, as before.

  # old rule
  from-autocdb ~/lists/whitelist_confirmed accept

  # new rule
  from-file -autocdb ~/lists/whitelist_confirmed accept

* The contrib/list2cdb and contrib/list2dbm scripts have been removed.
  Using the '-autocdb' or '-autodbm' argument to from-file or to-file
  is much easier than rebuilding your DB files manually.  See the
  TMDA Filter Specification for more details on these options.

* The 'to-mailman' and 'from-mailman' sources have changed.  You no
  longer specify the attribute to search with '.<attr_name>'.  Instead
  these sources now take the '-attr' argument with the attribute as
  the option.

  # old rule
  from-mailman.members ~mailman/lists/mylist/config.db accept

  # new rule
  from-mailman -attr=members ~mailman/lists/mylist/config.db accept

* The filter file parser used to ignore all syntax errors in filter
  files.  This means that your file might not be working as you want
  but you wouldn't know it.  This behavior has been changed.  Every
  error that the filter parser encounters is saved and, after the
  entire file has been processed, an exception is thrown and written
  to the debug log.

  If you want to check your filter files, make sure you have
  LOGFILE_DEBUG defined in your ~/.tmdarc and run tmda-filter with the
  '-M' switch.  Run 'tmda-filter -h' for more information about '-M'.
  Then examine the contents of your debug log.

======================================================================

If you are upgrading from a release of TMDA < 0.47:

* tmda-clean has been removed from the distribution.  The new
  tmda-pending script can be used to provide identical functionality
  by combining its `-q', `-b', `-d', and `-O' options.  tmda-pending's
  `-h' option provides an example of this.

======================================================================

If you are upgrading from a release of TMDA < 0.46:

* Python version 2.0 or greater is now required.

======================================================================

If you are upgrading from a release of TMDA < 0.45:

* Filter file rules must now start at the beginning of a line.  e.g,

  # invalid
    from johndoe ok

  # valid
  from johndoe ok

  See the documentation for more details on filter file syntax.

* 'headers' and 'body' filter file rules now use quotes (single or
  double) rather than parentheses to delimit the regular expression in
  the match field.

  # invalid
  headers (Subject: Site Down:.*) reject

  # valid
  headers "Subject: Site Down:.*" reject
  headers 'Subject: Site Down:.*' reject

* tmda-filter no longer looks for the `X-Originally-To' header by
  default.  If you need to retain this feature, set the following in
  your tmdarc:
  
  RECIPIENT_HEADER = "x-originally-to"

  See the related documentation for RECIPIENT_HEADER in
  http://tmda.net/config-vars.html.

======================================================================

If you are upgrading from a release of TMDA < 0.44:

* LOGFILE has been renamed LOGFILE_INCOMING.

* tmda-address has replaced tmda-dated-address, tmda-keyword-address,
  and tmda-sender-address.  Run `tmda-address -h' to get a list of
  available options.

* tmda-address now prints a newline after the tagged address by
  default.  Use the `-n' option to prevent this behavior.

======================================================================

If you are upgrading from a release of TMDA < 0.43:

* The TIMEZONE configuration setting has been removed.  If you need to
  specify a timezone for TMDA different than that of the local system,
  set the `TZ' environment variable directly from /etc/tmdarc or
  ~/.tmdarc.  e.g,

  import os
  os.environ['TZ'] = "Europe/Moscow"

======================================================================

If you are upgrading from a release of TMDA < 0.41:

Version 0.41 introduced TMDA filter files which are used to control
both incoming and outgoing mail (one filter file for incoming, and a
second for outgoing).  These obsolete all files in ~/.tmda/lists/*

TMDA filter file support necessitates several configuration changes.
You will also need to rename/add/delete several variables in your
tmdarc:

* BLACKLIST, WHITELIST, SACRED_FILE, and REVOKED_FILE were replaced by
  FILTER_INCOMING.  Create your ~/.tmda/filters/incoming filter file
  as explained in "TMDA Server Configuration" (config-server.html).

* BARE_FILE, DATED_FILE, EXP_FILE, EXT_FILE, KEYWORD_FILE,
  SENDER_FILE, were replaced by FILTER_OUTGOING.  Create your
  ~/.tmda/filters/outgoing filter file as explained in "TMDA Client
  Configuration" (config-client.html).

* WHITELIST_TO_BARE was removed as it is no longer relevant.  You can
  retain this functionality by adding the following line to your
  ~/.tmda/filters/outgoing filter file:

  to-file ~/.tmda/lists/whitelist bare

* BOUNCE_BLACKLIST_CC, BOUNCE_CONFIRM_CC, and BOUNCE_REVOKED_CC were
  replaced by FILTER_DROP_CC, CONFIRM_CC, and FILTER_BOUNCE_CC.

* WHITELIST_AUTO_APPEND was replaced by CONFIRM_APPEND.  The value for
  CONFIRM_APPEND should be the path to a filename rather than an
  integer.

* COOKIE_TYPE was replaced by ACTION_OUTGOING.

* X-TMDA headers should now contain only one field.  Separate
  multi-word entries with `='.  e.g,

  X-TMDA: ext=mlists

======================================================================

If you are upgrading from a release of TMDA < 0.38:

* The local copy of the documentation is now in `htdocs'.

* The `X-Confirmed' header is now `X-TMDA-Confirmed'.

* You can remove INJECT and INJECT_FLAGS from your .tmdarc as they are
  no longer used.

======================================================================

If you are upgrading from a release of TMDA < 0.36:

* The `setup' script was renamed `compileall'.

======================================================================

If you are upgrading from a release of TMDA < 0.35:

* Be aware that `WHITELIST_TO_BARE' is now turned on by default.

======================================================================

If you are upgrading from a release of TMDA < 0.33:

* If you maintain your own templates, make sure to replace all
  instances of `envelope_recipient' with `recipient_address'.

======================================================================

If you are upgrading from a release of TMDA < 0.31:

* You can remove LOCALS and USERPREFIX from your .tmdarc as they are
  no longer used.

======================================================================

If you are upgrading from a release of TMDA < 0.30:

Version 0.30 introduced "confirmation mode" where instead of just
bouncing the message, it will be stored in a pending-queue until the
sender responds to a confirmation request.  This replaces the old
behavior.  Some configuration changes are necessary:

* If you don't have a catch-all `.qmail-default', you will need to
  make a link from `.qmail-confirm-default' to `.qmail'.

* confirm_request.txt is the template used when generating
  confirmation requests.  This obsoletes bounce_dated.txt and
  bounce_sender.txt.  confirm_accept.txt is the template used to
  generate confirmation acceptance notices.

* BOUNCE_CONFIRM_CC replaces both BOUNCE_DATED_CC and BOUNCE_SENDER_CC.

* The copy of the original message is now added through the template
  instead of the code.

* The pending message queue will be maintained under ~/.tmda/ by
  default, and it will be created automatically if it doesn't exist.
  Set "DATADIR" in your .tmdarc to something else if you want to use a
  different directory.

* The default locations for the former 'dot-tmda' files are now within
  ~/.tmda/lists/:

  ~/.tmda-bare      -->  ~/.tmda/lists/bare
  ~/.tmda-blacklist -->  ~/.tmda/lists/blacklist
  ~/.tmda-dated     -->  ~/.tmda/lists/dated
  ~/.tmda-exp       -->  ~/.tmda/lists/exp
  ~/.tmda-ext       -->  ~/.tmda/lists/ext
  ~/.tmda-sender    -->  ~/.tmda/lists/sender
  ~/.tmda-whitelist -->  ~/.tmda/lists/whitelist

======================================================================

If you are upgrading from a release of TMDA < 0.21:

Starting with version 0.21, the syntax for .tmda-* files changed from
simple substring matching to supporting matching patterns based on
Unix shell-style wildcards.  The benefits are more matching
flexibility and better matching precision.  

As a result, your global patterns will need to be modified to support
the new syntax.  For example, `@domain.dom' will no longer match
anyone@domain.dom.  See `FAQ' for further explanation and examples
using the new syntax.

======================================================================

If you are upgrading from a release of TMDA < 0.10:

Starting with version 0.10, TMDA's crypto-cookie generation and
verification scheme switched to using HMACs instead of block cipher
encryption, which invalidated all previous tagged addresses.  For the
motivations behind this, see `CRYPTO'.

* The amkCrypto package is no longer necessary as HMAC uses Python's
  built-in `sha' module for hashing.

* You need to generate a new CRYPT_KEY by running bin/tmda-keygen and
  replace your current key in .tmdarc.

* You can remove BLOCK_CIPHER, CRYPT_IV, and HASH_FUNCTION from your
  .tmdarc as they are no longer used.

* Again, the new 'dated' and 'sender' addresses are not compatible
  with those generated prior to v0.10, so re-issue addresses as
  necessary with bin/tmda-dated-address and bin/tmda-sender-address.

======================================================================

^L
Local Variables:
mode: text
End: