Changes between Version 70 and Version 71 of Email2tracConfiguration


Ignore:
Timestamp:
01/08/10 11:14:55 (12 years ago)
Author:
bas
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Email2tracConfiguration

    v70 v71  
    22
    33= Configuration =
    4 
    5 After installation, edit [wiki:Email2tracConfiguration email2trac.conf]
    6 for your site.  The
    7 most important parameter is ''project''.  Below is a table
    8 of options with short descriptions and their default value:
    9 || NAME             || DEFAULT VALUE  || Description ||
    10 || [DEFAULT]        ||                ||  REQUIRED ||
    11 || project:         || `/data/trac/jouvin` || REQUIRED ||
    12 || alternate_notify_template          || None || OPTIONAL if set then use this style sheet for notify.  E.g., `ticket_alternate` ||
    13 || alternate_notify_template_update   || None || OPTIONAL if set then use this style sheet for notify ticket updates.  E.g., `ticket_alternate_update` ||
    14 || applesingle      || warn           || OPTIONAL, [#Attachmentsoptions  Attachments options], default: warn ||
    15 || appledouble      || warn           || OPTIONAL, [#Attachmentsoptions Attachments options], default: warn ||
    16 || binhex           || warn           || OPTIONAL, [#Attachmentsoptions Attachments options], default: warn ||
    17 || black_list       ||                || Drop mail if sender/domain matches. Can have multiple values separated by '',''. ||
    18 || debug:           || 0              ||  OPTIONAL, if set print some DEBUG info ||
    19 || drop_spam:       || 0              || OPTIONAL: if set then reject mail marked as SPAM ||
    20 || 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 ||
    21 || email_header:    || 0              || OPTIONAL, if set then show TO/CC fields in description ||
    22 || email_comment    || >              || OPTIONAL, prefix used to comment original text of ticket when using mailto_link ||
    23 || email_quote      || >              || OPTIONAL, if strip_quote is set, then remove email starting with this quote char ||
    24 || enable_syslog    || 0              || OPTIONAL, if set log errors to syslog, note they are ''not'' mailed back to the reporter ||
    25 || ignore_trac_user_settings || 0     || OPTIONAL, if set it will skip the email address to trac user login name mapping ||
    26 || mailto_cc:       ||                || OPTIONAL, use this address as CC in mailto line.  E.g., `ticket@test.nl` ||
    27 || mailto_link:     || 0              || OPTIONAL, if set then {{{[mailto:reporter]}}} in description ||
    28 || python_egg_cache || `$PYTHON_EGG_CACHE` || OPTIONAL, if set use this setting as environment variable; some installations depend on this. ||
    29 || recipient_list   ||                || If set then only accept mail when the ''to-field'' is in this list, usually only used in a dropbox configuration ||
    30 || 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 ||
    31 || reply_all:       || 0              || OPTIONAL, if set then put all CC-addresses in ticket CC-field ||
    32 || spam_level:      || 0              || OPTIONAL, if set check for SPAM mail ||
    33 || spam_header      || X-Spam-Score   || OPTIONAL, Check this email header field for SPAM ||
    34 || strip_quotes     || 0              || OPTIONAL, if set strip quotes from the email, useful when replying to tickets (see also email_quote), default: 0 ||
    35 || strip_signature  || 0              || OPTIONAL, if set try to remove the user signature from the mail, default: 0 ||
    36 || ticket_update:   || 0              || OPTIONAL, if set then check if this is an update for a ticket (see below) ||
    37 || tmpdir           || `/tmp`         || OPTIONAL, if set use this as temporary directory, default: ''/tmp'' ||
    38 || trac_version:    || 0.10           || OPTIONAL, if set then use this as version number ||
    39 || umask:           || process's umask  || OPTIONAL, if set use this umask for saving attachments.  E.g., `022`. ||
    40 || use_textwrap     || 0              || OPTIONAL, if set wrap text lines longer then the indicated number of characters.  A value of 0 disables wrapping. ||
    41 || verbatim_format  || 1              || OPTIONAL, default: 1, if unset then do not use format: ''{{{'' mail body text ''}}]'' ||
    42 || white_list       ||                || If set only accept mail when sender matches. Can have multiple values separated by '','' ||
    43 
    44 || FURTHER ENTRIES || EXAMPLE VALUE  || DESCRIPTION ||
    45 ||                 ||                ||             ||
    46 || [bas]           ||                || OPTIONAL next project declaration, also set project and use --project option  ||
    47 || project:        || `/data/trac/bas` || path to Trac project `bas` ||
    48 || spam_level:     || 2              || Override DEFAULT spam_level for project `bas`.  All above settings also can be set for project `bas`. ||
    49 
     4After 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:
     5
     6||NAME||DEFAULT VALUE||Description||version||
     7||[DEFAULT]||||REQUIRED||||
     8||project:||`/data/trac/jouvin`||REQUIRED||||
     9||alternate_notify_template||None||OPTIONAL if set then use this style sheet for notify.  E.g., `ticket_alternate`|| ||
     10||alternate_notify_template_update||None||OPTIONAL if set then use this style sheet for notify ticket updates.  E.g., `ticket_alternate_update`|| ||
     11||applesingle||warn||OPTIONAL, [#Attachmentsoptions Attachments options], default: warn||deprecated  in 1.1.0||
     12||appledouble||warn||OPTIONAL, [#Attachmentsoptions Attachments options], default: warn||deprecated in 1.1.0||
     13||binhex||warn||OPTIONAL, [#Attachmentsoptions Attachments options], default: warn||deprecated in 1.1.0||
     14||black_list||||Drop mail if sender/domain matches. Can have multiple values separated by '',''.|| ||
     15||debug:||0||OPTIONAL, if set print some DEBUG info||||
     16||drop_spam:||0||OPTIONAL: if set then reject mail marked as SPAM||||
     17||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|| ||
     18||email_header:||0||OPTIONAL, if set then show TO/CC fields in description|| ||
     19||email_comment||>||OPTIONAL, prefix used to comment original text of ticket when using mailto_link|| ||
     20||email_quote||>||OPTIONAL, if strip_quote is set, then remove email starting with this quote char|| ||
     21||enable_syslog||0||OPTIONAL, if set log errors to syslog, note they are ''not'' mailed back to the reporter|| ||
     22||ignore_trac_user_settings||0||OPTIONAL, if set it will skip the email address to trac user login name mapping|| ||
     23||mailto_cc:||||OPTIONAL, use this address as CC in mailto line.  E.g., `ticket@test.nl`|| ||
     24||mailto_link:||0||OPTIONAL, if set then `[mailto:reporter]` in description|| ||
     25||python_egg_cache||`$PYTHON_EGG_CACHE`||OPTIONAL, if set use this setting as environment variable; some installations depend on this.|| ||
     26||recipient_list||||If set then only accept mail when the ''to-field'' is in this list, usually only used in a dropbox configuration|| ||
     27||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|| ||
     28||reply_all:||0||OPTIONAL, if set then put all CC-addresses in ticket CC-field|| ||
     29||spam_level:||0||OPTIONAL, if set check for SPAM mail|| ||
     30||spam_header||X-Spam-Score||OPTIONAL, Check this email header field for SPAM|| ||
     31||strip_quotes||0||OPTIONAL, if set strip quotes from the email, useful when replying to tickets (see also email_quote), default: 0|| ||
     32||strip_signature||0||OPTIONAL, if set try to remove the user signature from the mail, default: 0|| ||
     33||ticket_update:||0||OPTIONAL, if set then check if this is an update for a ticket (see below)|| ||
     34||tmpdir||`/tmp`||OPTIONAL, if set use this as temporary directory, default: ''/tmp''|| ||
     35||trac_version:||0.10||OPTIONAL, if set then use this as version number|| ||
     36||umask:||process's umask||OPTIONAL, if set use this umask for saving attachments.  E.g., `022`.|| ||
     37||use_textwrap||0||OPTIONAL, if set wrap text lines longer then the indicated number of characters.  A value of 0 disables wrapping.|| ||
     38||verbatim_format||1||OPTIONAL, default: 1, if unset then do not use format: ''{{{'' mail body text ''}}]''|| ||
     39||white_list||||If set only accept mail when sender matches. Can have multiple values separated by '',''|| ||
     40
     41||FURTHER ENTRIES||EXAMPLE VALUE||DESCRIPTION||
     42||||||||
     43||[bas]||||OPTIONAL next project declaration, also set project and use --project option||
     44||project:||`/data/trac/bas`||path to Trac project `bas`||
     45||spam_level:||2||Override DEFAULT spam_level for project `bas`.  All above settings also can be set for project `bas`.||
    5046
    5147== Spam ==
    52 
    53 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.
     48There 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.
    5449
    5550For example, with the configuration:
     51
    5652{{{
    5753spam_level: 4
     
    5955spam_header: X-Spam-Level
    6056}}}
    61 Email2trac drops all email with ''Spam-score'' greater the 4. 
    62 Given this setting, an email with the below header is rejected:
     57Email2trac drops all email with ''Spam-score'' greater the 4.   Given this setting, an email with the below header is rejected:
     58
    6359{{{
    6460From lijuydru@example.com Tue Dec  5 12:47:04 2006
     
    7773        WEIRD_PORT, autolearn=spam
    7874}}}
    79 
    8075== Default values for ticket fields ==
    81 
    8276In [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:
     77
    8378 1. email2trac.conf
    8479 1. trac.ini
    8580
    8681The format is the same as for ''trac.ini'', eg:
     82
    8783{{{
    8884[test_project]
     
    9086default_version : 0.20
    9187}}}
    92 
    9388Email2trac check if the given values are allowed for this field. If it is not allowed then the ''trac.ini'' default value is used.
    9489
    9590=== Multiple email addresses setup ===
    96 
    9791When there are more then one email address to the same project. You can configure it to have different default values for a ticket, eg:
    9892
     
    110104}}}
    111105
    112 
    113 
    114106== Ticket Update ==
    115 
    116 If you have enabled ''ticket_update'' in
    117 [wiki:Email2tracConfiguration email2trac.conf] then you have to configure
    118 one of the two options explained below.  Email2trac will scan the subject field of
    119 all emails to determine if a given email is a ticket update, and consequently it
    120 must update ticket fields.
     107If you have enabled ''ticket_update'' in  [wiki:Email2tracConfiguration 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.
    121108
    122109For example:
     110
    123111 * This subject line will trigger an update of ticket number 1529:
    124112{{{
     
    132120
    133121=== Email address ===
    134 
    135 This is the preferred method. This will setup an email address
    136 where the ticket information will be sent to. This is a different
    137 email address than the ticket email address.  When you reply on
    138 this email a copy will be sent to the ticket email address.
     122This 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.
    139123
    140124Here is an example setup '''for the trac.ini''' of the respective trac project:
     125
    141126{{{
    142127      (ticket address: ticket@test.nl)
     
    148133      always_notify_reporter = true
    149134}}}
    150 ''smtp_always_cc'' is the address where the ticket information is
    151 sent to and ''smtp_from'' is the ticket email address. So if
    152 somebody replies a copy of the ticket is sent to this address.
    153 
     135''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.
    154136
    155137=== html code ===
    156  
    157 Use the ''mailto_cc'' and ''mailto_link'' in
    158 [wiki:Email2tracConfiguration email2trac.conf].
    159 This will add a ''HTML mailto link'' in the description field.
    160 If you click on this link it will open the default mail program
    161 which will send an email to the reporter and Carbon Copy to
    162 the ticket address.
     138 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.
    163139
    164140== Formatting options ==
    165 
    166 There are several options that control the behavior of the
    167 format of a ticket. Below there is a brief explanation of the options:
     141There are several options that control the behavior of the  format of a ticket. Below there is a brief explanation of the options:
    168142
    169143verbatim_format::
    170  By default, this option is enabled. When mail is inserted in the
    171 trac ticket system the message's body is inserted as plain text
    172 in between !{{{ ''body_text'' }}}. Thus, Trac does not process
    173 the body text. You can disable this option in
    174 [wiki:Email2tracConfiguration email2trac.conf]:
     144
     145  By default, this option is enabled. When mail is inserted in the
     146
     147trac 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]:
     148
    175149{{{
    176150verbatim_format : 0
    177151}}}
    178 
    179152strip_signature::
    180  When enabled it will try to strip the signatures from the email.
    181 It scans the message for a line containing the string `--`.  All lines after this
    182 line will be skipped.
     153
     154  When enabled it will try to strip the signatures from the email.
     155
     156It scans the message for a line containing the string `--`.  All lines after this  line will be skipped.
     157
    183158{{{
    184159strip_signature : 1
    185160}}}
    186 
    187161use_textwrap::
    188  When enabled it will break lines greater then the the number specified.
     162
     163  When enabled it will break lines greater then the the number specified.
     164
    189165For example:
     166
    190167{{{
    191168use_textwrap : 40
     
    202179
    203180reflow::
    204  Most email clients wrap long lines to <80 characters. In some cases, this breaks Trac wiki formatting (when verbatim_format is off). For example:
     181
     182  Most email clients wrap long lines to <80 characters. In some cases, this breaks Trac wiki formatting (when verbatim_format is off). For example:
    205183{{{
    206184  * 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
     
    209187may get incorrectly rendered as
    210188
    211   * This is a very very very very very very very very very very very very
     189 * This is a very very very very very very very very very very very very
     190
    212191very very very very very very very very very very very very very very very very very very very very long list item
    213192
    214193Format=flowed property of plain-text email, specified in RFC 3676, deals with this problem.
    215194
    216 
    217 
    218 == Attachments options ==
    219 
     195== Attachments options ==
    220196Versions greater then 1.0.0 you can specify which attachments are saved or dropped, via:
     197
    221198 * strip_content_types
    222199
    223200The following configuration will drop pgp signature attachments and apple binhex40 attachments:
    224   * strip_content_types: application/pgp-signature, application/mac-binhex40
    225 
     201
     202 * strip_content_types: application/pgp-signature, application/mac-binhex40
    226203
    227204The following option will be deprecated in a newer version of email2trac. For now the 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:
    228   * binhex
    229   * applesingle
    230   * appledouble
    231 
     205
     206 * binhex
     207 * applesingle
     208 * appledouble
    232209
    233210=== Version less or equal to 1.0.0 ===
    234 
    235 ==== binhex  ====
    236 
     211==== binhex ====
    237212The !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.
    238213
    239214The binhex option can be set to one of:
     215
    240216 * 'keep', in which case attachments encoded with !BinHex will be included in the ticket
    241217 * '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
     
    245221
    246222==== applesingle ====
    247 
    248223Same options and meaning as for binhex option above.
    249224
    250225==== appledouble ====
    251 
    252226The !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.
    253227
    254228The applesingle option can be set to one of:
     229
    255230 * 'keep', in which case both the platform-neutral data and the Mac-specific data will be included in the ticket (as two separate attachments)
    256231 * '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.