[[PageOutline]] = Configuration = After installation, edit [wiki:Email2tracConfiguration 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 file as style sheet for notification emails. E.g., `email_ticket_template` || || alternate_notify_template_update || None || OPTIONAL if set use this file as style sheet for ticket update notification emails. E.g., `email_ticket_update` || || applesingle || warn || OPTIONAL, [#Attachmentsoptions Attachments options], default: warn || deprecated in 1.1.0 || || appledouble || warn || OPTIONAL, [#Attachmentsoptions Attachments options], default: warn || deprecated in 1.1.0 || || binhex || warn || OPTIONAL, [#Attachmentsoptions Attachments options], default: warn || deprecated in 1.1.0 || || black_list || None || Drop mail if sender 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 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 || < 2.6.0 || || email_quote || ^> .* || OPTIONAL, if strip_quote is set. Remove email if it matche regular expression || => 2.6.0 || || email_triggers_workflow || 1 || OPTIONAL, If set to 0 it will prevent closed tickets to be reopened or trigger a [#Workflow 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 || || html2text_cmd || None || OPTIONAL. If set will convert html mail to text, See for [#HTMLtotextconversion examples] || 2.0.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 [wiki:Email2tracParse#Updateticketfields 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 [wiki:Email2tracParse#Updateticketfields body text parsing] || 2.0.0 || || log_file || email2trac.log || OPTIONAL, can be set to the same values as [wiki:TracLogging trac logging] || 1.5.0 || || log_format || Emailtrac: %(message)s || OPTIONAL, can be set to the same values as [wiki:TracLogging trac logging] || 1.5.0 || || log_level || INFO || OPTIONAL, can be set to the same values as [wiki:TracLogging trac logging] || 1.5.0 || || log_type || syslog || OPTIONAL, can be set to the same values as [wiki:TracLogging 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 || || only_strip_on_update || False || OPTIONAL, if set then only strip signature and/or quote for ticket updates || 2.6.0 || || parentdir || || OPTIONAL, Is the root directory of all trac projects, see [#Parentdir 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 || None || 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 Spam configuration] || || spam_header || X-Spam-Score || OPTIONAL, see [#Spam 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 || || strip_signature_regex || -----Original Message-----$|^-- $ || Strip signature when it matches this regular expression, NOTE all lines after this match will be deleted || 2.6.0 || || subject_field_separator || & || OPTIONAL. This is used to split the subject line, see [wiki:Email2tracParse#Subjectfield Subject field parsing] || 1.1.0 || || ticket_permission_system |||| OPTIONAL. Select which [#PermissionSystem 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 '','' || || white_list_file || None || When set read allowed user from a file. One email address per line. || 2.5.0 || || white_list_registered_users || False || This will allow registered user to create/update a ticket even if 'white_list' is set in the configuration file and the user email address is not added to this parameter || 2.5.0 || || 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 [wiki:Email2tracConfiguration 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 1. 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 devel_owner : dteam }}} == Ticket Update == If you have enabled ''ticket_update''in [wiki:Email2tracConfiguration email2trac.conf] then it will parse the subject line to determine if this a reply mail. Optional you can set ''ticket_update_by_subject'' option to see if we have matching subject line. See [wiki:Email2tracParse How an email message is parsed] There are two options to enable ticket replies: 1. A ticket email address 1. Html code in the ticket description field. === Ticket 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 [wiki:Email2tracConfiguration 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 [wiki:Email2tracConfiguration 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 == If the ticket_permission_system option is not set, everybody is allowed ticket updates and creation, otherwise it can be set to one of two options: * '''trac''': This will honor the permission set via ''trac-admin'' or the web-interface * '''update_restricted_to_participants''': Anyone can create a ticket, but this option will only allow the updating of 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 {{{ [DEFAULT] # workflow_: 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 }}} == HTML to text conversion == email2trac use an external program to convert HTML to ASCII/text. This conversion must output the result to ''stdout''. Here are some examples which programs can be used for the conversion: * html2text_cmd: /usr/bin/html2text -nobs * html2text_cmd: /usr/bin/w3m -dump * html2text_cmd: /usr/bin/lynx -dump * html2text_cmd: /usr/bin/links -dump