1 _ _ ____
2 _ __ ___ __ _(_) |___ \ ___ _ __ ___ ___
3 | '_ ` _ \ / _` | | | __) / __| '_ ` _ \/ __|
4 | | | | | | (_| | | |/ __/\__ \ | | | | \__ \
5 |_| |_| |_|\__,_|_|_|_____|___/_| |_| |_|___/
6
7Project: mail2sms
8Version: 1.3.x
9Date: February 12, 2001
10Author: Daniel Stenberg <daniel@haxx.se>
11Web: http://www.contactor.se/~dast/mail2sms/
12
13==============================================================================
14 Description
15==============================================================================
16
17 mail2sms reads a (MIME) mail and converts it to a short message. It offers
18search and replace, conditional rules, conditional search and replace etc to
19create a custom output. It can optionally pipe its output into a specified
20program.
21
22 mail2sms is entirely FREE. See the LEGAL file for details.
23
24 Table Of Contents
25 =================
26
27 1. Usage
28
29 2. Config File Format
30 In General
31 2.1 General Keywords
32 2.2 Search/Replace, Conditional Search/Replace
33 2.3 Conditional Config File Sections
34 2.4 Stop/Allow Message Forwarding
35 2.5 Conditional Actions and Variables
36 2.6 Logfile and Include
37
38 3. mail2sms internals
39
40==============================================================================
41 1. Usage
42==============================================================================
43
44 mail2sms [options] < mail
45
46 mail2sms reads the config file /usr/local/mail2sms/config first and then
47 $HOME/.mail2sms by default.
48
49 Available options:
50
51 -c [file] specifies what config file to read. It can be used repeatedly.
52 -d switch on debug messages in the log file
53 -I [dir] adds a directory to the include path.
54 -l [file] log everything to the specified file, this overrides 'logfile'
55 entries on the config file
56 -n prevents reading the default config files
57 -o makes mail2sms write the sms message to stdout when completed (and
58 not invoke any sub-command).
59 -p sets the $phone variable (see the run command)
60 -q shuts off all logging
61 -v prints version number and quits
62
63==============================================================================
64 2. Config File Format
65==============================================================================
66
67Each line should be in the format:
68
69 <keyword> [ : <value> ]
70
71Values are either written plainly and whitespaces left and right of the words
72are cut off, or within quotes ("). If the value is quoted, you must escape
73quotes to be able to have them in the string, as in: " \" ".
74
75Lines beginning with '#' are treated as comments.
76
77Basically, there are two kinds of keywords. The first is the one read and
78dealt with in real-time when read from the config file, they may also build
79strings that define output format, specify command to run etc.. The other type
80is the keywords that build a tree of regular expressions with accompanying
81actions. Those actions might be performed when the regexes match contents of
82the input mail. It is important to understand the difference.
83
84------------------------------------------------------------------------------
85 2.1 General Keywords
86------------------------------------------------------------------------------
87
88options
89=======
90 Usage:
91 options: <options>
92
93 (may be specified as o:)
94
95 Options are single words separated with spaces or commas. The options
96 control the following search/replace or if operation. Available
97 options are:
98
99 1perline (previously: "noloop")
100 - only one replace per line
101 once
102 - only one replace per mail
103 subject (*)
104 - replace in subject
105 from (*)
106 - replace in from (the name or if not available, the email address)
107 fromaddress (*)
108 - replace in from address (the email address)
109 to (*)
110 - replace in to (the name or if not available, the email address)
111 toaddress (*)
112 - replace in the to field (the email address)
113 body (*)
114 - replace in body
115 fullbody (*)
116 - replace in the full body, as one large buffer without newlines
117 header (*)
118 - search/replace in header! Must be specifily specified, if not
119 specified no searching will be done in headers.
120 nocase
121 - case insensitive search. Only the letters A-Z will be treated
122 case insensitively.
123 prio <1-5>
124 - lower prio value makes the regex be done before higher values.
125 Default prio is 3.
126
127 (*) = when one or more of these are used, the search/replace or if
128 is only valid for the specified parts.
129
130log
131===
132 Usage:
133 log: <message>
134
135 This is a message that will be added to the log file when the action
136 specified after this is performed. 'log' is used by search, if,
137 not, begin and many other keywords.
138
139------------------------------------------------------------------------------
140 2.2 Search/Replace, Conditional Search/Replace
141------------------------------------------------------------------------------
142search
143======
144 Usage:
145 search: <search regex>
146
147 (may be specified as s:) The search regex is a full posix egrep style
148 regex. Must be used BEFORE the replace command.
149
150 This regex may in fact match many times, not just one.
151
152replace
153=======
154 Usage:
155 replace: <replacement>
156
157 (may be specified as r:) Replace is the replacement for the
158 search. \<num> can be used to insert "registers" from the search. Must
159 be used AFTER a search command. This must also be the last line in a
160 search/replace action.
161
162 One search/replace pair may be used many times if the search pattern
163 is general enough.
164
165if
166==
167 Usage:
168 if: <trigging regex>
169
170 Starts a conditional sub-section. This sub-section that MUST be ended
171 with an 'endif' keyword, is an ordinary sequence of config items that
172 won't be considered until the if-regex has first matched once. Once
173 the if-regex has matched, all the sub-sections' expressions (like
174 search/replace within this sub-section) are all moved to the "normal"
175 list and are then treated just as normal items.
176
177 You can control the if-regex with the 'options' keyword. The 'log'
178 keyword is also used.
179
180 You can "append" actions to this keyword by using one or more of the
181 following keywords within the if/endif block:
182
183 abort, outsize, create, delete, system, config, run, program,
184 progargs, output, phone, server, port, multipart, maxparts
185
186 When you use these keywords within an if/endif block, they will all
187 take effect the first time the IF regex matches (and only then).
188
189 Do not confuse the IF keyword with BEGIN. The IF/ENDIF is for
190 conditions against mail content like if you want different behaviour
191 for different kinds of mails. BEGIN/END is used for making parts of
192 the config file conditional.
193
194 You MUST end this sub-section with 'endif'
195
196endif
197=====
198 Usage:
199 endif
200
201 Closes a conditional sub-section previously started with the 'if'
202 keyword.
203
204not
205===
206 Usage:
207 not: <regex>
208
209 This keyword can only be used within an if-endif section, or after a
210 'replace' keyword. Each time this keyword is used, it adds a regex to
211 the list on the the preceeding regex keyword (i.e search/replace, or
212 if) that must NOT match for the regex to match. 'not' can be used any
213 number of times.
214
215 You may specify a separate 'log' line for the NOT expression. The
216 'not' expression will always be tried on the exact same context that
217 the previous regex-expression just matched.
218
219 Example, if the subject includes Daniel but NOT Stenberg, add a
220 special search/replace rule:
221
222 options: subject
223 if: Daniel
224 Not: Stenberg
225 search: Daniel
226 replace: Fake-Danman
227 endif
228
229 Make a search/replace like the above without the if:
230
231 options: subject
232 search: Daniel
233 replace: Fake-Danman
234 not: Stenberg
235
236------------------------------------------------------------------------------
237 2.3 Conditional Config File Sections
238------------------------------------------------------------------------------
239 These keywords control what parts of a config file that is read.
240
241when
242whennot
243=======
244 Usage:
245 when: <expression>
246 whennot: <expression>
247
248 If the given when expression matches current conditions, it sets the
249 condition flag.
250
251 If a whennot expression matches current conditions it clears the
252 condition flag.
253
254 You can also reverse the expression by prefixing it with !.
255
256 NOTE: a 'when' command only defines what sections to read from the
257 config file.
258
259 The condition flag controls whether a following sub-section shall be
260 parsed or skipped. If the condition flag is set, the section is
261 parsed, otherwise it is skipped!
262
263 A sub section is specified within 'begin', 'else' and 'end'
264 keywords. The condition flag is always undefined after a begin, end
265 or else.
266
267 Default state of the condition flag is undefined, and the first when
268 command will set it.
269
270 The EXPRESSION may involve:
271
272 day <sequence 1 - 31>
273 Day of the month.
274 hour <sequence 0 - 23 or 0000 - 2359>
275 Note that the size of the numbers are used to figure out which
276 of these formats to use. 0-23 means full hours, 0-26 would
277 mean from 00:00 to 00:26>
278 min <sequence 0000 - 2359>
279 Note that this is hour+minutes and not plain minutes
280 wday <sequence 1 - 7>
281 Day of the week. 1 is Monday, 7 is Sunday.
282 month <sequence 1 - 12>
283 Month of the year. 1 is January, 12 is December.
284 year <sequence 1998 - 2038>
285 Year number. Only full 4-digit years are supported.
286 file <filename>
287 TRUE if the file is present
288 always
289 Always set TRUE
290 never
291 Always set FALSE
292
293 Sequences can be specified as:
294
295 1-4,2,9-4,3 (no whitespace)
296
297 Filename is a filename without whitespace.
298
299 You can combine the different parts of an expression to a combined
300 expression as in:
301
302 day 1-3 hour 8-14 wday 1,3,6
303
304 The file keyword makes the operation dependent on the presense of
305 a named file:
306
307 when: file /etc/passwd
308
309 ... requires that named file to be there for the program to
310 continue.
311
312 Expressions are read top to bottom.
313
314 You can mix when and whennot keywords to make complex expressions.
315
316 Example, make a special search expression friday the 13th 1999:
317
318 # place condition
319 when: year 1999
320 when: day 13 wday 5
321 begin
322 # start sub section
323 options: nocase
324 search: .*
325 replace: friday the 13th!
326 end
327begin
328=====
329 Usage:
330 begin
331
332 Starts a config file sub section. If the condition flag is set or
333 undefined, this section will be parsed. If the condition flag is
334 cleared, this section will be skipped all the way to the following end
335 (or else) keyword (not counting sub sections within this section). You
336 MUST end a sub section with a corresponding 'end'.
337
338 It is important to remember that begin/end keywords only change what
339 to read in the config file. The section's "condition flag" is set by
340 conditions found when reading the config. The begin/end section can
341 *NEVER* depend on particular mail contents, since the config file is
342 scanned long before any mail content is known. To make conditional
343 actions depending on mail content, see the IF keyword.
344
345 If 'log' was used for this keyword, it will be logged together with
346 the condition flag status.
347
348 You can use '{' instead of 'begin'.
349
350end
351===
352 Usage:
353 end
354
355 Ends a sub section. See 'begin' and 'when' for more details. This
356 shall not be used without a preceeding 'begin' or 'else' keyword.
357
358 You can NOT have the 'end' keyword of section appear in another file
359 than the one with the initiating 'begin'.
360
361 You can use '}' instead of 'end'.
362
363else
364====
365 Usage:
366 special
367
368 This must be preceeded with a begin keyword and an end keyword should
369 end this section. This keyword ends a section and if the previous one
370 was parsed, the one following this won't be and vice verse.
371
372 You can NOT have the 'else' keyword of section appear in another file
373 than the one with the initiating 'begin'.
374
375 'else' shall not be used without a preceeding 'begin' keyword.
376
377------------------------------------------------------------------------------
378 2.4 Stop/Allow Message Forwarding
379------------------------------------------------------------------------------
380 These commands are taken care of when the config file is read, and the
381decision whether to continue or not will be taken before the mail is read at
382all.
383
384break
385=====
386 Usage:
387 break
388
389 Sets the BREAK flag. If all config files have been read and the BREAK
390 flag is set, no SMS will be sent.
391
392 To abort the SMS sending depending on some mail content, use the abort
393 keyword within an if/endif section.
394
395unbreak
396=======
397 Usage:
398 unbreak
399
400 Clears the BREAK flag. See 'break'.
401
402exit
403=====
404 Usage:
405 exit: <exit code>
406
407 Sets the BREAK flag and sets what return code mail2sms should return
408 to the invoking process/shell. If all config files have been read and
409 the BREAK flag is set, no SMS will be sent.
410
411 Note that this keyword can also be used within IF/ENDIF sections and
412 if so, it will be treated as a ABORT keyword with an added exitcode
413 specifier.
414
415------------------------------------------------------------------------------
416 2.5 Conditional Actions and Variables
417------------------------------------------------------------------------------
418
419 These actions can be put on root-level, within begin-end sections or within
420if-endif section. When set within if/endif sections, they take effect at first
421when that IF expression matches.
422
423 All these keywords take advantage of the log string in case there is one set
424before the actual keyword. The logging will take place when the action is
425performed.
426
427
428abort
429=====
430 Usage:
431 abort: <message>
432
433 The abort keyword aborts the sms creation immediately. This keyword
434 can't be used on root-level, abort MUST be put within an if/endif
435 section. The message will simply be logged.
436
437config
438======
439 Usage:
440 config: <file name>
441
442 Reads the specified config file if the previous 'if' regex matches.
443
444create
445======
446 Usage:
447 create: <filename>
448
449 Creates the file if it isn't already created.
450
451delete
452======
453 Usage:
454 delete: <filename>
455
456 Deletes the specified file.
457
458exit (see the upper section for full details)
459====
460
461maxparts
462========
463 Usage:
464 maxparts: <num>
465
466 This specifies the maximum number of output parts that mail2sms is
467 allowed to generate. Default is 1. Each part is maximum 'outsize'
468 bytes long.
469
470multipart
471=========
472 Usage:
473 multipart: <format>
474
475 Specifies how to deal with multipart prefixes or suffixes. If the
476 message is sent in more than one part, this string is used to define
477 the prefix or suffix to include in every single part. If this format
478 starts with a dash (-) the rest of the string will be used as a
479 suffix, otherwise it will be a prefix.
480
481 The format string has two "variables" that will be replaced with the
482 numbers that goes for each part and message:
483
484 $index starts at 1 and is increased for every part
485 $numparts the amount of parts that this message uses
486
487 Other characters that can be used in the string are:
488
489 \t Tab character
490 \n Newline character
491 \r Carriage return character
492
493output
494======
495 Usage:
496 output: <output>
497
498 Specifies what to output and in what order. Available variables are:
499
500 $from The name or the email of the sender
501 $fromaddress The email address of the sender
502 $to The name or the email of the receiver
503 $toaddress The email address of the receiver
504 $subject The subject field
505 $body The body of the mail
506
507 Other characters that can be used in the string are:
508
509 \t Tab character
510 \n Newline character
511 \r Carriage return character
512
513 Default output string is "F: $from S: $subject B: $body". Note that
514 as much as possible of all variables will be output. I.e if the first
515 variable used is very big, no other output will be shown.
516
517outsize
518=======
519 Usage:
520 outsize: <number of bytes>
521
522 Specifies the maximum size of the output message. Default is 160.
523 There is at max 'maxparts' parts of this size sent.
524
525system
526======
527 Usage:
528 system: <command line>
529
530 Runs the specified shell command line.
531
532phone
533port
534progargs
535program
536server
537=======
538 Usage:
539 <keyword> : <value>
540
541 These keywords all set the variable with the same name as the keyword.
542 The variable can be used in the 'run' string to specify what command
543 line to use when passing the SMS to a client program.
544
545run
546===
547 Usage:
548 run : <command line to run>
549
550 This command line is a string with the possibility to insert different
551 variables. All non-variable characters are inserted as specified. The
552 'output' string will be passed to the program on its stdin.
553
554 There is no default run string. If no string is specified, no program
555 will be run by mail2sms.
556
557 Available variables are:
558
559 Name Contains
560 ---- --------
561 $message The entire SMS message.
562 $phone What has been specified with the phone keyword.
563 $port What has been specified with the port keyword.
564 $progargs What has been specified with the progargs keyword.
565 $program What has been specified with the program keyword.
566 $server What has been specified with the server keyword.
567
568filter
569======
570 Usage:
571 filter : <filter instruction>
572
573 The filter can only be used conditionally. It cannot be set on the
574 root-level. A filter is set on a section on a line-by-line basis. When
575 the filter is switched on, it is in use until it is again switched
576 off. The filter instruction that is written on the right side should
577 be in this format:
578
579 <name> <status> [lines <num>] [exclude/include]
580
581 'name' is the filter name. Currently 'ignore' is the only available
582 supported filter. 'ignore' effectively cuts off the lines in the
583 filtered section. Note that the theory here is that you should be able
584 to switch on and off different filters independently. As soon as there
585 is more filters available that is.
586
587 'status' is either "on" or "off". Setting a filter to "on" means it
588 takes effect, it gets in use. Switched "off" a filter means that the
589 filter is turned off and things go back to normal (non-filtered).
590
591 'lines <num>' (for 'on' entries only) sets the filter to remain valid
592 for a certain number of lines, the matching one counted. This makes
593 the filter to automatically get switched off after this amount of lines
594 have been sent through the filter.
595
596 'exclude' in the line means that the matching line in itself should
597 not be considered as part of the filtered section. Exclude it from the
598 section.
599
600 'include' is the opposite of 'exclude'. It is the default behaviour
601 and it makes the matching line of a filter expression to be included
602 in the filter section.
603
604------------------------------------------------------------------------------
605 2.6 Logfile and Include
606------------------------------------------------------------------------------
607 These can only be made conditional within begin/end sections.
608
609logfile
610=======
611 Usage:
612 logfile: <filename>
613
614 Logs all messages to the specified logfile instead of stderr.
615
616showlog
617=======
618 Usage:
619 showlog: <what to include>
620
621 Sets what kinds of log messages to include in the logfile. The format
622 for the control string is:
623
624 <[+/-]LOGTYPE1>, <[+/-]LOGTYPE2>
625
626 Available log types are: ALL, INFO, BREAK, ERROR, DEBUG, WARNING,
627 ABORT, IF, SEARCH, NOT, DELETE, CREATE, SYSTEM, CONFIG, REGEX, ACTION
628
629 A few examples explain this best:
630
631 To see all log entries:
632
633 showlog: +all
634
635 To see all except the DELETE ones:
636
637 showlog: +all, -delete
638
639 To see the default set but not the WARNING ones:
640
641 showlog: -warning
642
643 To disable if, search and not:
644
645 showlog: -if,search,not
646
647 Switch off everything:
648
649 showlog: -all
650
651 NOTE: the -d command line flag enables "ALL" (including DEBUG). Normal
652 defaults are "+ALL,-DEBUG".
653
654path
655====
656 Usage:
657 path: <directory name without trailing slash>
658
659 Adds the specified directory to the include path. The include path is
660 a list of directories that mail2sms will search through for the
661 specified file when include is used. By default, no directory is in
662 the include path.
663
664include
665=======
666 Usage:
667 include: <file>
668
669 Makes that specified conf file get read.
670
671==============================================================================
672 3. mail2sms Internals
673==============================================================================
674
675 The Regex Loop
676 --------------
677 When traversing the config files, mail2sms creates a linked list of regex
678nodes. One node is added for each IF or SEARCH/REPLACE.
679
680 Each regex node may have sub-list (that themselves are actal regex nodes)
681that if the main node matches, are moved into the main list. They're not taken
682into account until they're in the main list.
683
684 Each sublist node may itself have subnodes of course, which can make it
685pretty advanced.
686
687 Each regex node may also have a list of not-matches. If any of the entries in
688the not-list matches, the main node is considered not a match. An attempt to
689draw this situation looks like:
690
691 Search/Replace #1
692 |
693 |
694 If #2 ----- Subsearch/replace #1 - Subsearch/replace #2 - ...
695 |
696 |
697 Search/Replace #3
698 | \__
699 | \__
700 | Not #1 - Not #2 - ...
701 |
702 Search/Replace #4
703 |
704 ...
705
706 The list is built when the config files are read. mail2sms then goes through
707the input mail and for each line of the mail it does the following:
708
709We start at the beginning with the highest prio; number 1.
710
711 1. If the node isn't of this prio, get the next. If we reach the end of the
712 list, increase the prio to check for and restart the list. If the prio
713 to check for reaches max, end the loop.
714
715 2. Check if the condition is dependent on what kind of input (header, from,
716 subject, etc). If it isn't supposed to replace/match the current type,
717 loop.
718
719 3. Make sure that we haven't looped this too many times.
720
721 4. Check if the regex matches. Otherwise, loop.
722
723 5. Make sure we haven't found exactly this match too many times.
724
725 6. Check the type of the regex.
726
727 6.1 If it is an 'IF':
728
729 o Check that it hasn't already been "done".
730
731 o Check the not-list. If any of them matches, treat this as a
732 non-match.
733
734 o Perform all the actions that were specified within this if/endif
735 block.
736
737 o Move the sublist to the "main list".
738
739 6.2 If it is a 'SEARCH/REPLACE', perform the replace.
740
741 7. Reset to start-of-list at prio 1.
742
743 8. Loop
744
745 Order Of Tests
746 --------------
747
748 First all headers are read.
749
750 Each header is first tested as a 'header' and then secondly, if it is a known
751 header (like To:, From: etc) it is tested as that kind of header.
752
753 When all headers are done the body gets read.
754
755 Each line of the body is tested as 'body', one line at a time. This goes on
756 until mail2sms has collected a body-"buffer" that is ten times the size of
757 the output text (by default that means 10*160 bytes). It then tests the whole
758 body-buffer as 'fullbody'.
759
760 In each of these many tests, the low prio tests are performed before the high
761 prio tests. But this order described here is important to understand since
762 the prio system only changes importance within the same test.
763