Configuration

After installation, edit email2trac.conf for your site. The most important parameter is project. Below is a table of options with short descriptions and their default value:

NAME	DEFAULT VALUE	Description	version
[DEFAULT]	REQUIRED
project:	/data/trac/jouvin	REQUIRED
alternate_notify_template	None	OPTIONAL if set then use this style sheet for notify. E.g., ticket_alternate
alternate_notify_template_update	None	OPTIONAL if set then use this style sheet for notify ticket updates. E.g., ticket_alternate_update
applesingle	warn	OPTIONAL, Attachments options, default: warn	deprecated in 1.1.0
appledouble	warn	OPTIONAL, Attachments options, default: warn	deprecated in 1.1.0
binhex	warn	OPTIONAL, Attachments options, default: warn	deprecated in 1.1.0
black_list	None	Drop mail if sender/domain matches. Can have multiple values separated by ,.
debug:	0	OPTIONAL, if set prints DEBUG info. depends on log_type where the output is saved	1.5.0
drop_spam:	0	OPTIONAL: see Spam configuration
drop_alternative_html_version:	0	OPTIONAL, if set then drop the HTML part of the message that is t he same as the plain text version
email_header:	0	OPTIONAL, if set then show TO/CC fields in description
email_quote	>	OPTIONAL, if strip_quote is set, then remove email starting with this quote char
email_triggers_workflow	1	OPTIONAL, If set to 0 it will prevent closed tickets to be reopened or trigger a workflow	1.6.0
enable_syslog	0	OPTIONAL, if set log errors to syslog, note they are not mailed back to the reporter	deprecated in 1.5.0
ignore_trac_user_settings	0	OPTIONAL, if set it will skip the email address to trac user login name mapping
inline_properties	0	OPTIONAL, This is used to set ticket fields within an email, see body text parsing ]	1.2.0
inline_properties_first_wins	0	OPTIONAL, Only process the first inline property when an email want to change the same ticket field, see body text parsing	2.0.0
log_file	email2trac.log	OPTIONAL, can be set to the same values as trac logging	1.5.0
log_format	Emailtrac: %(message)s	OPTIONAL, can be set to the same values as trac logging	1.5.0
log_level	INFO	OPTIONAL, can be set to the same values as trac logging	1.5.0
log_type	syslog	OPTIONAL, can be set to the same values as trac logging	1.5.0
mailto_cc	OPTIONAL, use this address as CC in mailto line. E.g., ticket@test.nl
mailto_link	0	OPTIONAL, if set then [mailto:reporter] in description
notify_reporter	0	OPTIONAL, if set then always mail the reporter	2.0.0
notify_reporter_black_list	None	Do not send mail if reporter matches. Can have muliple values separated by ,	2.0.0
parentdir	<directory>	OPTIONAL, Is the root directory of all trac projects, see parentdir	2.0.0
python_egg_cache	$PYTHON_EGG_CACHE	OPTIONAL, if set use this setting as environment variable; some installations depend on this.
recipient_list	If set then only accept mail when the to-field is in this list, usually only used in a dropbox configuration
reflow	1	OPTIONAL, if set then soft line breaks will be removed from {{[format:flowed]}} email when creating the ticket with verbatim_format turned off
reply_all:	0	OPTIONAL, if set then put all CC-addresses in ticket CC-field
spam_level:	0	OPTIONAL, see Spam configuration
spam_header	X-Spam-Score	OPTIONAL, see Spam configuration
strip_quotes	0	OPTIONAL, if set strip quotes from the email, useful when replying to tickets (see also email_quote), default: 0
strip_signature	0	OPTIONAL, if set try to remove the user signature from the mail, default: 0
subject_field_separator	&	OPTIONAL. This is used to split the subject line, see Subject field parsing	1.1.0
ticket_permission_system	OPTIONAL. Select which Permission System must be used trac or update_restricted_to_participants		1.5.0
ticket_update:	0	OPTIONAL, if set then check if this is an update for a ticket (see below)
ticket_update_by_subject	0	Optional, When there is no ticket number found in the reply mail. It will try to find a ticket that matches the subject line. Default time 30 days back from time received	1.4.0
ticket_update_by_subject_lookback	30	Optional, see ticket_update_by_subject for explanation	1.4.0
tmpdir	/tmp	OPTIONAL, if set use this as temporary directory, default: /tmp
trac_version:	0.10	OPTIONAL, if set then use this as version number	deprecated in 1.4.0
umask:	process's umask	OPTIONAL, if set use this umask for saving attachments. E.g., 022.
use_textwrap	0	OPTIONAL, if set wrap text lines longer then the indicated number of characters. A value of 0 disables wrapping.
verbatim_format	1	OPTIONAL, default: 1, if unset then do not use format: {{{ mail body text }}]
white_list	None	If set only accept mail when sender matches. Can have multiple values separated by ,

FURTHER ENTRIES	EXAMPLE VALUE	DESCRIPTION
[bas]	OPTIONAL next project declaration, also set project and use --project option
project:	/data/trac/bas	path to Trac project bas
spam_level:	2	Override DEFAULT spam_level for project bas. All above settings also can be set for project bas.

Spam

There are three configuration options to handle spam. One of the options specifies which header field we must check to determine if a message is SPAM. The default value is X-Spam-Score . The other options depend on this setting and will check the contents of this header field. The header field is set by SPAM detecing program like SpamAssassin. Email2trac counts the number of * characters in the spam_header line.

For example, with the configuration:

spam_level: 4
drop_spam: 1   
spam_header: X-Spam-Level

Email2trac drops all email with Spam-score greater the 4. Given this setting, an email with the below header is rejected:

From lijuydru@example.com Tue Dec  5 12:47:04 2006
To: test@example.com
Subject: Test
MIME-Version: 1.0
Content-Type: text/plain;
List-Id: 8
X-Scanned-By: MIMEDefang 2.56 on 145.100.16.144
X-Scanned-By: MIMEDefang 2.51 on 145.100.16.26
X-Scanned-By: MIMEDefang 2.56 on 145.100.16.144
X-Spam-Level: ***************************** (29.334) BAYES_99,
        HELO_DYNAMIC_DHCP,HELO_DYNAMIC_IPADDR,MSGID_FROM_MTA_ID,
        RCVD_IN_BL_SPAMCOP_NET,RCVD_IN_SORBS_DUL,RCVD_IN_XBL,
        SUBJ_ILLEGAL_CHARS, URIBL_JP_SURBL, URIBL_SBL, URIBL_SC_SURBL,
        WEIRD_PORT, autolearn=spam

Default values for ticket fields

In email2trac.conf you can specify the default values for the ticket fields. This can be different then the one's specified in trac.ini. email2trac will process the files in this order:

1. email2trac.conf
2. trac.ini

The format is the same as for trac.ini, eg:

[test_project]
default_component : test
default_version : 0.20

Email2trac check if the given values are allowed for this field. If it is not allowed then the trac.ini default value is used.

Multiple email addresses setup

When there are more then one email address to the same project. You can configure it to have different default values for a ticket, eg:

• /etc/aliases

  support: |"/usr/local/bin/run_email2trac --project=test --ticket_prefix=support"
  devel:   |"/usr/local/bin/run_email2trac --project=test --ticket_prefix=devel"
  

• /usr/local/etc/email2trac.conf

  [test]
  support_component : support
  devel_component : devel
  

Ticket Update

If you have enabled ticket_update in email2trac.conf then you have to configure one of the two options explained below. Email2trac will scan the subject field of all emails to determine if a given email is a ticket update, and consequently it must update ticket fields.

For example:

• This subject line will trigger an update of ticket number 1529:

  Subject: [hic] #1529: Re: LRZ
  

• The following subject line will trigger an update of ticket number 1529 and will set its owner to bas and priority to medium:

  Subject: [hic] #1529?owner=bas&priority=medium: Re: LRZ
  

NOTE: For versions prior to 1.1.0 the subject field separator is , instead of &

Email address

This is the preferred method. This will setup an email address where the ticket information will be sent to. This is a different email address than the ticket email address. When you reply on this email a copy will be sent to the ticket email address.

Here is an example setup for the trac.ini of the respective trac project:

      (ticket address: ticket@test.nl)
      [notification]
      smtp_enabled = true
      smtp_always_cc = test@test.nl
      smtp_server = localhost
      smtp_from =  ticket@test.nl
      always_notify_reporter = true

smtp_always_cc is the address where the ticket information is sent to and smtp_from is the ticket email address. So if somebody replies a copy of the ticket is sent to this address.

html code

Use the mailto_cc and mailto_link in email2trac.conf. This will add a HTML mailto link in the description field. If you click on this link it will open the default mail program which will send an email to the reporter and Carbon Copy to the ticket address.

Formatting options

There are several options that control the behavior of the format of a ticket. Below there is a brief explanation of the options:

verbatim_format::

By default, this option is enabled. When mail is inserted in the

trac ticket system the message's body is inserted as plain text in between {{{ ''body_text'' }}}. Thus, Trac does not process the body text. You can disable this option in email2trac.conf:

verbatim_format : 0

strip_signature::

When enabled it will try to strip the signatures from the email.

It scans the message for a line containing the string --. All lines after this line will be skipped.

strip_signature : 1

use_textwrap::

When enabled it will break lines greater then the the number specified.

For example:

use_textwrap : 40 

input:

This is an example of a line that has more than 40 characters

output:

This is an example of a line that has
more than 40 characters

reflow::

Most email clients wrap long lines to <80 characters. In some cases, this breaks Trac wiki formatting (when verbatim_format is off). For example:

  * This is a very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long list item

may get incorrectly rendered as

• This is a very very very very very very very very very very very very

very very very very very very very very very very very very very very very very very very very very long list item

Format=flowed property of plain-text email, specified in RFC 3676, deals with this problem.

Attachments options

Versions greater then 1.0.0 you can specify which attachments are saved or dropped, via:

• strip_content_types

The following configuration will drop pgp signature attachments and apple binhex40 attachments:

• strip_content_types: application/pgp-signature, application/mac-binhex40

The following option will be deprecated in a newer version of email2trac. For now it can be used as backward compatible option for the apple attachments. These options will set the parameter strip_content_types to drop these kind of attachments. So the option warn does not exists anymore:

• binhex
• applesingle
• appledouble

Version less or equal to 1.0.0

binhex

The BinHex encoding format is deprecated (in favor of AppleDouble MIME, see RFC 1740), but some older clients might still be using it. A file encoded with BinHex is annoying to decode unless you are on a Mac.

The binhex option can be set to one of:

• 'keep', in which case attachments encoded with BinHex will be included in the ticket
• 'warn', in which case attachments encoded with BinHex will be ignored, but a warning message to that effect will be included in the ticket description
• 'drop', in which case attachments encoded with BinHex will be silently ignored

The default is 'warn'.

applesingle

Same options and meaning as for binhex option above.

appledouble

The AppleDouble encoding format is the recommended way to include Mac-specific data in a MIME message, as per RFC 1740. A file encoded with AppleDouble can easily be presented usefully on all platforms.

The applesingle option can be set to one of:

• 'keep', in which case both the platform-neutral data and the Mac-specific data will be included in the ticket (as two separate attachments)
• 'warn', in which case only the platform-neutral file data will be included in the ticket. Mac-specific data will be left out, but a warning message will be included in the ticket description.
• 'strip', in which case only the platform-neutral file data will be included in the ticket. Mac-specific data will be left out with no warning.

The default is 'warn'.

Permission System

There are two options to choose from:

1. trac: This will honor the permission set via trac-admin or the web-interface
2. update_restricted_to_participants: This will only update a ticket if one the following conditions is met:
   • the updater is the ticket reporter
   • the updater is listed in the CC field of a ticket
   • the updater has trac permission to update the ticket

If the update is denied, a new ticket will be generated instead as to not lose the issue

Workflow

You can control which workflow must be executed when an ticket is updated. Per state you have to associate a workflow, eg:

• email2trac.conf

  [project]
  # workflow_<ticket status>: <workflow name>
  workflow_closed: reopen
  workflow_infoneeded: provideinfo
  

• trac.ini:

  reopen = closed -> reopened
  reopen.permissions = TICKET_CREATE
  reopen.operations = del_resolution
  
  provideinfo = infoneeded -> moreinfo
  provideinfo.permissions = TICKET_CREATE
  provideinfo.name = info provided
  

When a ticket update is received and the state of the ticket is:

• closed it will execute the reopen workflow.
• infoneeded it will execute the infoneeded workflow

Parentdir

This variable is set in the [DEFAULT] section of email2trac.conf, eg:

[DEFAULT]
parentdir: /data/trac/oss/projects

[email2trac]
debug: 1

[pbs-python]
project: /data/trac/pbs_python/project

In this example the parent directory is /data/trac/oss/projects. You can override the project directory per section, see section pbs-python. In the above example the project directory for section email2trac is /data/trac/oss/projects/email2trac

With this new feature you can use one script for aliases. Here is an example from sto add iti dot upvdot es

To avoid touching the postfix alias database I'm using addresses of the form trac+PROJECT@mail.domain 
(I have recipient_delimiter = + on the postfix main.cf file) and the alias file has an entry like the following:
 
 * trac: /usr/local/sbin/email2trac-alias

Where /usr/local/sbin/email2trac-alias is a script that does more or less the following:

#!/bin/sh
parentdir="/data/trac/oss/project"
if [ -f "$parentdir/$EXTENSION/conf/trac.ini" ]; then
  exec /usr/local/bin/run_email2trac --project="$EXTENSION"
fi
exit 67 # Unknown user