diff options
Diffstat (limited to 'archivemail.1')
| -rw-r--r-- | archivemail.1 | 1284 |
1 files changed, 842 insertions, 442 deletions
diff --git a/archivemail.1 b/archivemail.1 index 0daa264..34a13f0 100644 --- a/archivemail.1 +++ b/archivemail.1 @@ -1,486 +1,886 @@ -.\" This manpage has been automatically generated by docbook2man -.\" from a DocBook document. This tool can be found at: -.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> -.\" Please send any bug reports, improvements, comments, patches, -.\" etc. to Steve Cheng <steve@ggi-project.org>. -.TH "ARCHIVEMAIL" "1" "09 August 2010" "SP" "" - -.SH NAME +'\" t +.\" Title: archivemail +.\" Author: [see the "Author" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 9 August 2010 +.\" Manual: SP +.\" Source: SP +.\" Language: English +.\" +.TH "ARCHIVEMAIL" "1" "9 August 2010" "SP" "SP" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" archivemail \- archive and compress your old email -.SH SYNOPSIS - -\fBarchivemail\fR [ \fBoptions\fR ] \fB\fIMAILBOX\fB\fR\fI ...\fR - +.SH "SYNOPSIS" +.HP \w'\fBarchivemail\fR\ 'u +\fBarchivemail\fR [\fBoptions\fR] {\fIMAILBOX\fR...} .SH "DESCRIPTION" .PP -archivemail is a tool for archiving and compressing old email in mailboxes. -By default it will read the mailbox \fIMAILBOX\fR, moving messages -that are older that the specified number of days (180 by default) to a -\fBmbox\fR(5)-format mailbox in the same directory that is compressed -with \fBgzip\fR(1)\&. -It can also just delete old email rather than archive it. -.PP -By default, \fBarchivemail\fR derives the archive filename from the -mailbox name by appending an \fI_archive\fR suffix to the mailbox -name. For example, if you run \fBarchivemail\fR on a mailbox called -\fIexsouthrock\fR, the archive will be created with the -filename \fIexsouthrock_archive.gz\fR\&. -This default behavior can be overridden with command line options, choosing -a custom suffix, a prefix, or a completely custom name for the archive. -.PP -\fBarchivemail\fR supports reading \fBIMAP\fR, -\fBMaildir\fR, \fBMH\fR and \fBmbox\fR-format -mailboxes, but always writes \fBmbox\fR-format archives. -.PP -Messages that are flagged important are not archived or deleted unless -explicitely requested with the \fB--include-flagged\fR option. -Also, \fBarchivemail\fR can be configured not to archive unread mail, or -to only archive messages larger than a specified size. -.PP -To archive an \fBIMAP\fR-format mailbox, use the format -\fIimap://username:password@server/mailbox\fR to specify the mailbox. -\fBarchivemail\fR will expand wildcards in \fBIMAP\fR mailbox -names according to RFC 3501, which says: ``The character "*" is a wildcard, and matches zero or more characters at this -position. The character "%" is similar to "*", but it does not match a -hierarchy delimiter.'' -You can omit the password from the URL; use the -\fB--pwfile\fR option to make \fBarchivemail\fR read the -password from a file, or alternatively just enter it upon request. -If the \fB--pwfile\fR option is set, \fBarchivemail\fR does not -look for a password in the URL, and the colon is not considered a -delimiter. -Substitute '\fBimap\fR\&' with '\fBimaps\fR\&', and -\fBarchivemail\fR will establish a secure SSL connection. -See below for more \fBIMAP\fR peculiarities. -.SH "OPTIONS" -.TP -\fB -d \fINUM\fB, --days=\fINUM\fB\fR -Archive messages older than \fINUM\fR days. -The default is 180. This option is incompatible with the -\fB--date\fR option below. -.TP -\fB -D \fIDATE\fB, --date=\fIDATE\fB\fR -Archive messages older than \fIDATE\fR\&. -\fIDATE\fR can be a date string in ISO format (eg '2002-04-23'), -Internet format (eg '23 Apr 2002') or Internet format with full month names -(eg '23 April 2002'). Two-digit years are not supported. -This option is incompatible with the \fB--days\fR option above. -.TP -\fB -o \fIPATH\fB, --output-dir=\fIPATH\fB\fR -Use the directory name \fIPATH\fR to store the -mailbox archives. The default is the same directory as the mailbox to be -read. -.TP -\fB -P \fIFILE\fB, --pwfile=\fIFILE\fB\fR -Read IMAP password from file \fIFILE\fR -instead of from the command line. Note that this will probably not work if you -are archiving folders from more than one IMAP account. -.TP -\fB -F \fISTRING\fB, --filter-append=\fISTRING\fB\fR -Append \fISTRING\fR to the IMAP filter string. -For IMAP wizards. -.TP -\fB -p \fINAME\fB, --prefix=\fINAME\fB\fR -Prefix \fINAME\fR to the archive name. -\fINAME\fR is expanded by the \fBpython\fR(1) function -\fBtime.strftime()\fR, which means that you can specify special -directives in \fINAME\fR to make an archive named after the archive -cut-off date. -See the discussion of the \fB--suffix\fR option for a list of valid -\fBstrftime()\fR directives. -The default is not to add a prefix. -.TP -\fB -s \fINAME\fB, --suffix=\fINAME\fB\fR -Use the suffix \fINAME\fR to create the filename used for archives. -The default is \fI_archive\fR, unless a prefix is specified. +archivemail is a tool for archiving and compressing old email in mailboxes\&. By default it will read the mailbox +\fIMAILBOX\fR, moving messages that are older that the specified number of days (180 by default) to a +\fBmbox\fR(5)\-format mailbox in the same directory that is compressed with +\fBgzip\fR(1)\&. It can also just delete old email rather than archive it\&. +.PP +By default, +\fBarchivemail\fR +derives the archive filename from the mailbox name by appending an +_archive +suffix to the mailbox name\&. For example, if you run +\fBarchivemail\fR +on a mailbox called +exsouthrock, the archive will be created with the filename +exsouthrock_archive\&.gz\&. This default behavior can be overridden with command line options, choosing a custom suffix, a prefix, or a completely custom name for the archive\&. +.PP -Like a prefix, the suffix \fINAME\fR is expanded by the \fBpython\fR(1) -function \fBtime.strftime()\fR with the archive cut-off date. -\fBtime.strftime()\fR understands the following directives: -.RS -.TP 0.2i -\(bu -\fB%a\fR -Locale's abbreviated weekday name. -.TP 0.2i -\(bu -\fB%A\fR -Locale's full weekday name. -.TP 0.2i -\(bu -\fB%b\fR -Locale's abbreviated month name. -.TP 0.2i -\(bu -\fB%B\fR -Locale's full month name. -.TP 0.2i -\(bu -\fB%c\fR -Locale's appropriate date and time representation. -.TP 0.2i -\(bu -\fB%d\fR -Day of the month as a decimal number [01,31]. -.TP 0.2i -\(bu -\fB%H\fR -Hour (24-hour clock) as a decimal number [00,23]. -.TP 0.2i -\(bu -\fB%I\fR -Hour (12-hour clock) as a decimal number [01,12]. -.TP 0.2i -\(bu -\fB%j\fR -Day of the year as a decimal number [001,366]. -.TP 0.2i -\(bu -\fB%m\fR -Month as a decimal number [01,12]. -.TP 0.2i -\(bu -\fB%M\fR -Minute as a decimal number [00,59]. -.TP 0.2i -\(bu -\fB%p\fR -Locale's equivalent of either AM or PM. -.TP 0.2i -\(bu -\fB%S\fR -Second as a decimal number [00,61]. (1) -.TP 0.2i -\(bu -\fB%U\fR -Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. -.TP 0.2i -\(bu -\fB%w\fR -Weekday as a decimal number [0(Sunday),6]. -.TP 0.2i -\(bu -\fB%W\fR -Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. -.TP 0.2i -\(bu -\fB%x\fR -Locale's appropriate date representation. -.TP 0.2i -\(bu -\fB%X\fR -Locale's appropriate time representation. -.TP 0.2i -\(bu -\fB%y\fR -Year without century as a decimal number [00,99]. -.TP 0.2i -\(bu -\fB%Y\fR -Year with century as a decimal number. -.TP 0.2i -\(bu -\fB%Z\fR -Time zone name (or by no characters if no time zone exists). -.TP 0.2i -\(bu -\fB%%\fR -A literal "%" character. -.RE -.TP -\fB -a \fINAME\fB, --archive-name=\fINAME\fB\fR -Use \fINAME\fR as the archive name, ignoring the name -of the mailbox that is archived. -Like prefixes and suffixes, \fINAME\fR is expanded by -\fBstrftime()\fR with the archive cut-off date. -Because it hard-codes the archive name, this option cannot be used when -archiving multiple mailboxes. -.TP -\fB -S \fINUM\fB, --size=\fINUM\fB\fR -Only archive messages that are \fINUM\fR bytes or -greater. -.TP -\fB -n, --dry-run\fR -Don't write to any files -- just show what would have been done. This is -useful for testing to see how many messages would have been archived. -.TP -\fB -u, --preserve-unread\fR -Do not archive any messages that have not yet been read. \fBarchivemail\fR -determines if a message in a \fBmbox\fR-format or -\fBMH\fR-format mailbox has been read by looking at the -\fBStatus\fR header (if it exists). If the status -header is equal to 'RO' or 'OR' then \fBarchivemail\fR assumes the -message has been read. \fBarchivemail\fR determines if a -\fBmaildir\fR message has -been read by looking at the filename. If the filename contains an 'S' after -\fI:2,\fR then it assumes the message has been read. -.TP -\fB --dont-mangle\fR -Do not mangle lines in message bodies beginning with "From ". When archiving -a message from a mailbox not in \fBmbox\fR format, by default -\fBarchivemail\fR mangles such lines by prepending a '>' to them, since mail -user agents might otherwise interpret these lines as message separators. -Messages from \fBmbox\fR folders are never mangled. See \fBmbox\fR(5) for more -information. -.TP -\fB --delete\fR -Delete rather than archive old mail. Use this option with caution! -.TP -\fB --copy\fR -Copy rather than archive old mail. -Creates an archive, but the archived messages are not deleted from the -originating mailbox, which is left unchanged. -This is a complement to the \fB--delete\fR option, and mainly useful for -testing purposes. -Note that multiple passes will create duplicates, since messages are blindly -appended to an existing archive. -.TP -\fB --all\fR -Archive all messages, without distinction. -.TP -\fB --include-flagged\fR -Normally messages that are flagged important are not archived or deleted. If -you specify this option, these messages can be archived or deleted just like -any other message. -.TP -\fB --no-compress\fR -Do not compress any archives. -.TP -\fB --warn-duplicate\fR -Warn about duplicate \fBMessage-ID\fRs that appear in the input -mailbox. -.TP -\fB -v, --verbose\fR -Reports lots of extra debugging information about what is going on. -.TP -\fB --debug-imap=\fINUM\fB\fR -Set IMAP debugging level. This makes \fBarchivemail\fR dump its -conversation with the IMAP server and some internal IMAP -processing to stdout\&. Higher values for \fINUM\fR give more -elaborate output. Set \fINUM\fR to 4 to see all exchanged -IMAP commands. (Actually, \fINUM\fR is just passed -literally to imaplib.Debug\&.) -.TP -\fB -q, --quiet\fR -Turns on quiet mode. Do not print any statistics about how many messages were -archived. This should be used if you are running \fBarchivemail\fR from -cron. -.TP -\fB -V, --version\fR -Display the version of \fBarchivemail\fR and exit. -.TP -\fB -h, --help\fR -Display brief summary information about how to run \fBarchivemail\fR\&. +\fBarchivemail\fR +supports reading +IMAP, +Maildir, +MH +and +mbox\-format mailboxes, but always writes +mbox\-format archives\&. +.PP +Messages that are flagged important are not archived or deleted unless explicitly requested with the +\fB\-\-include\-flagged\fR +option\&. Also, +\fBarchivemail\fR +can be configured not to archive unread mail, or to only archive messages larger than a specified size\&. +.PP +To archive an +IMAP\-format mailbox, use the format +\fIimap://username:password@server/mailbox \fR +to specify the mailbox\&. +archivemail +will expand wildcards in +IMAP +mailbox names according to +RFC +3501, which says: +\(lq The character "*" is a wildcard, and matches zero or more characters at this position\&. The character "%" is similar to "*", but it does not match a hierarchy delimiter\&.\(rq +You can omit the password from the +URL; use the +\fB\-\-pwfile\fR +option to make +\fBarchivemail\fR +read the password from a file, or alternatively just enter it upon request\&. If the +\fB\-\-pwfile\fR +option is set, +\fBarchivemail\fR +does not look for a password in the +URL, and the colon is not considered a delimiter\&. Substitute \*(Aq\fBimap\fR\*(Aq with \*(Aq\fBimaps\fR\*(Aq, and +\fBarchivemail\fR +will establish a secure +SSL +connection\&. See below for more +IMAP +peculiarities\&. +.SH "OPTIONS" +.PP +\fB\-d \fR\fB\fINUM\fR\fR\fB, \-\-days=\fR\fB\fINUM\fR\fR +.RS 4 +Archive messages older than +\fINUM\fR +days\&. The default is 180\&. This option is incompatible with the +\fB\-\-date\fR +option below\&. +.RE +.PP +\fB\-D \fR\fB\fIDATE\fR\fR\fB, \-\-date=\fR\fB\fIDATE\fR\fR +.RS 4 +Archive messages older than +\fIDATE\fR\&. +\fIDATE\fR +can be a date string in ISO format (eg \*(Aq2002\-04\-23\*(Aq), Internet format (eg \*(Aq23 Apr 2002\*(Aq) or Internet format with full month names (eg \*(Aq23 April 2002\*(Aq)\&. Two\-digit years are not supported\&. This option is incompatible with the +\fB\-\-days\fR +option above\&. +.RE +.PP +\fB\-o \fR\fB\fIPATH\fR\fR\fB, \-\-output\-dir=\fR\fB\fIPATH\fR\fR +.RS 4 +Use the directory name +\fIPATH\fR +to store the mailbox archives\&. The default is the same directory as the mailbox to be read\&. +.RE +.PP +\fB\-P \fR\fB\fIFILE\fR\fR\fB, \-\-pwfile=\fR\fB\fIFILE\fR\fR +.RS 4 +Read +IMAP +password from file +\fIFILE\fR +instead of from the command line\&. Note that this will probably not work if you are archiving folders from more than one IMAP account\&. +.RE +.PP +\fB\-F \fR\fB\fISTRING\fR\fR\fB, \-\-filter\-append=\fR\fB\fISTRING\fR\fR +.RS 4 +Append +\fISTRING\fR +to the +IMAP +filter string\&. For +IMAP +wizards\&. +.RE +.PP +\fB\-p \fR\fB\fINAME\fR\fR\fB, \-\-prefix=\fR\fB\fINAME\fR\fR +.RS 4 +Prefix +\fINAME\fR +to the archive name\&. +\fINAME\fR +is expanded by the +\fBpython\fR(1) +function +time\&.strftime(), which means that you can specify special directives in +\fINAME\fR +to make an archive named after the archive cut\-off date\&. See the discussion of the +\fB\-\-suffix\fR +option for a list of valid +strftime() +directives\&. The default is not to add a prefix\&. +.RE +.PP +\fB\-s \fR\fB\fINAME\fR\fR\fB, \-\-suffix=\fR\fB\fINAME\fR\fR +.RS 4 +Use the suffix +\fINAME\fR +to create the filename used for archives\&. The default is +_archive, unless a prefix is specified\&. +.sp +Like a prefix, the suffix +\fINAME\fR +is expanded by the +\fBpython\fR(1) +function +time\&.strftime() +with the archive cut\-off date\&. +time\&.strftime() +understands the following directives: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%a\fR +Locale\*(Aqs abbreviated weekday name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%A\fR +Locale\*(Aqs full weekday name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%b\fR +Locale\*(Aqs abbreviated month name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%B\fR +Locale\*(Aqs full month name\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%c\fR +Locale\*(Aqs appropriate date and time representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%d\fR +Day of the month as a decimal number [01,31]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%H\fR +Hour (24\-hour clock) as a decimal number [00,23]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%I\fR +Hour (12\-hour clock) as a decimal number [01,12]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%j\fR +Day of the year as a decimal number [001,366]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%m\fR +Month as a decimal number [01,12]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%M\fR +Minute as a decimal number [00,59]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%p\fR +Locale\*(Aqs equivalent of either AM or PM\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%S\fR +Second as a decimal number [00,61]\&. (1) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%U\fR +Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]\&. All days in a new year preceding the first Sunday are considered to be in week 0\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%w\fR +Weekday as a decimal number [0(Sunday),6]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%W\fR +Week number of the year (Monday as the first day of the week) as a decimal number [00,53]\&. All days in a new year preceding the first Sunday are considered to be in week 0\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%x\fR +Locale\*(Aqs appropriate date representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%X\fR +Locale\*(Aqs appropriate time representation\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%y\fR +Year without century as a decimal number [00,99]\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%Y\fR +Year with century as a decimal number\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%Z\fR +Time zone name (or by no characters if no time zone exists)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fB%%\fR +A literal "%" character\&. +.RE +.sp +.RE +.PP +\fB\-a \fR\fB\fINAME\fR\fR\fB, \-\-archive\-name=\fR\fB\fINAME\fR\fR +.RS 4 +Use +\fINAME\fR +as the archive name, ignoring the name of the mailbox that is archived\&. Like prefixes and suffixes, +\fINAME\fR +is expanded by +strftime() +with the archive cut\-off date\&. Because it hard\-codes the archive name, this option cannot be used when archiving multiple mailboxes\&. +.RE +.PP +\fB\-S \fR\fB\fINUM\fR\fR\fB, \-\-size=\fR\fB\fINUM\fR\fR +.RS 4 +Only archive messages that are +\fINUM\fR +bytes or greater\&. +.RE +.PP +\fB\-n, \-\-dry\-run\fR +.RS 4 +Don\*(Aqt write to any files \-\- just show what would have been done\&. This is useful for testing to see how many messages would have been archived\&. +.RE +.PP +\fB\-u, \-\-preserve\-unread\fR +.RS 4 +Do not archive any messages that have not yet been read\&. +\fBarchivemail\fR +determines if a message in a +mbox\-format or +MH\-format mailbox has been read by looking at the +Status +header (if it exists)\&. If the status header is equal to \*(AqRO\*(Aq or \*(AqOR\*(Aq then +archivemail +assumes the message has been read\&. +\fBarchivemail\fR +determines if a +maildir +message has been read by looking at the filename\&. If the filename contains an \*(AqS\*(Aq after +:2, +then it assumes the message has been read\&. +.RE +.PP +\fB\-\-dont\-mangle\fR +.RS 4 +Do not mangle lines in message bodies beginning with "From "\&. When archiving a message from a mailbox not in +mbox +format, by default +\fBarchivemail\fR +mangles such lines by prepending a \*(Aq>\*(Aq to them, since mail user agents might otherwise interpret these lines as message separators\&. Messages from +mbox +folders are never mangled\&. See +\fBmbox\fR(5) +for more information\&. +.RE +.PP +\fB\-\-delete\fR +.RS 4 +Delete rather than archive old mail\&. Use this option with caution! +.RE +.PP +\fB\-\-copy\fR +.RS 4 +Copy rather than archive old mail\&. Creates an archive, but the archived messages are not deleted from the originating mailbox, which is left unchanged\&. This is a complement to the +\fB\-\-delete\fR +option, and mainly useful for testing purposes\&. Note that multiple passes will create duplicates, since messages are blindly appended to an existing archive\&. +.RE +.PP +\fB\-\-all\fR +.RS 4 +Archive all messages, without distinction\&. +.RE +.PP +\fB\-\-include\-flagged\fR +.RS 4 +Normally messages that are flagged important are not archived or deleted\&. If you specify this option, these messages can be archived or deleted just like any other message\&. +.RE +.PP +\fB\-\-no\-compress\fR +.RS 4 +Do not compress any archives\&. +.RE +.PP +\fB\-\-warn\-duplicate\fR +.RS 4 +Warn about duplicate +Message\-IDs that appear in the input mailbox\&. +.RE +.PP +\fB\-v, \-\-verbose\fR +.RS 4 +Reports lots of extra debugging information about what is going on\&. +.RE +.PP +\fB\-\-debug\-imap=\fR\fB\fINUM\fR\fR +.RS 4 +Set +IMAP +debugging level\&. This makes +\fBarchivemail\fR +dump its conversation with the +IMAP +server and some internal +IMAP +processing to +stdout\&. Higher values for +\fINUM\fR +give more elaborate output\&. Set +\fINUM\fR +to 4 to see all exchanged +IMAP +commands\&. (Actually, +\fINUM\fR +is just passed literally to +imaplib\&.Debug\&.) +.RE +.PP +\fB\-q, \-\-quiet\fR +.RS 4 +Turns on quiet mode\&. Do not print any statistics about how many messages were archived\&. This should be used if you are running +\fBarchivemail\fR +from cron\&. +.RE +.PP +\fB\-V, \-\-version\fR +.RS 4 +Display the version of +\fBarchivemail\fR +and exit\&. +.RE +.PP +\fB\-h, \-\-help\fR +.RS 4 +Display brief summary information about how to run +\fBarchivemail\fR\&. +.RE .SH "NOTES" .PP -\fBarchivemail\fR requires \fBpython\fR(1) version 2.3 or later. -When reading an \fBmbox\fR-format mailbox, \fBarchivemail\fR will -create a lockfile with the extension \fI\&.lock\fR so that -procmail will not deliver to the mailbox while it is being processed. It will -also create an advisory lock on the mailbox using \fBlockf\fR(2)\&. -The archive is locked in the same way when it is updated. -\fBarchivemail\fR will also complain and abort if a 3rd-party modifies the -mailbox while it is being read. -.PP -\fBarchivemail\fR will always attempt to preserve the -last-access and last-modify times of the input mailbox. Archive -mailboxes are always created with a mode of \fB0600\fR\&. -If \fBarchivemail\fR finds a pre-existing archive mailbox it -will append rather than overwrite that archive. -\fBarchivemail\fR will refuse to operate on mailboxes that are symbolic -links. -.PP -\fBarchivemail\fR attempts to find the delivery date of a message by -looking for valid dates in the following headers, in order of precedence: -\fBDelivery-date\fR, -\fBReceived\fR, -\fBResent-Date\fR and -\fBDate\fR\&. -If it cannot find any valid date in these headers, it -will use the last-modified file timestamp on \fBMH\fR and -\fBMaildir\fR format mailboxes, or the date on the -\fBFrom\fR line on \fBmbox\fR-format mailboxes. + +\fBarchivemail\fR +requires +\fBpython\fR(1) +version 2\&.3 or later\&. When reading an +mbox\-format mailbox, +\fBarchivemail\fR +will create a lockfile with the extension +\&.lock +so that procmail will not deliver to the mailbox while it is being processed\&. It will also create an advisory lock on the mailbox using +\fBlockf\fR(2)\&. The archive is locked in the same way when it is updated\&. +\fBarchivemail\fR +will also complain and abort if a 3rd\-party modifies the mailbox while it is being read\&. +.PP + +\fBarchivemail\fR +will always attempt to preserve the last\-access and last\-modify times of the input mailbox\&. Archive mailboxes are always created with a mode of +0600\&. If +\fBarchivemail\fR +finds a pre\-existing archive mailbox it will append rather than overwrite that archive\&. +\fBarchivemail\fR +will refuse to operate on mailboxes that are symbolic links\&. +.PP + +\fBarchivemail\fR +attempts to find the delivery date of a message by looking for valid dates in the following headers, in order of precedence: +Delivery\-date, +Received, +Resent\-Date +and +Date\&. If it cannot find any valid date in these headers, it will use the last\-modified file timestamp on +MH +and +Maildir +format mailboxes, or the date on the +From +line on +mbox\-format mailboxes\&. .PP When archiving mailboxes with leading dots in the name, -\fBarchivemail\fR will strip the dots off the archive name, so -that the resulting archive file is not hidden. -This is not done if the \fB--prefix\fR or -\fB--archive-name\fR option is used. -Should there really be mailboxes distinguished only by leading dots in the -name, they will thus be archived to the same archive file by default. -.PP -A conversion from other formats to \fBmbox\fR(5) will silently overwrite existing -\fBStatus\fR and \fBX-Status\fR message headers. +archivemail +will strip the dots off the archive name, so that the resulting archive file is not hidden\&. This is not done if the +\fB\-\-prefix\fR +or +\fB\-\-archive\-name\fR +option is used\&. Should there really be mailboxes distinguished only by leading dots in the name, they will thus be archived to the same archive file by default\&. +.PP +A conversion from other formats to +\fBmbox\fR(5) +will silently overwrite existing +Status +and +X\-Status +message headers\&. .SS "IMAP" .PP -When \fBarchivemail\fR processes an \fBIMAP\fR folder, all messages -in that folder will have their \\Recent flag unset, and they will -probably not show up as 'new' in your user agent later on. -There is no way around this, it's just how \fBIMAP\fR works. -This does not apply, however, if you run \fBarchivemail\fR with the options -\fB--dry-run\fR or \fB--copy\fR\&. -.PP -\fBarchivemail\fR relies on server-side searches to determine the messages -that should be archived. -When matching message dates, \fBIMAP\fR servers refer to server internal -message dates, and these may differ from both delivery time of a message and -its \fBDate\fR header. -Also, there exist broken servers which do not implement server side searches. -.SS "IMAP URLS" -.PP -\fBarchivemail\fR\&'s \fBIMAP\fR URL parser was written -with the RFC 2882 (\fIInternet Message -Format\fR) rules for the local-part of email addresses -in mind. -So, rather than enforcing an URL-style encoding of non-ascii -and reserved characters, it allows to double-quote the username and password. -If your username or password contains the delimiter characters '@' or ':', just -quote it like this: -\fIimap://"username@bogus.com":"password"@imap.bogus.com/mailbox\fR\&. -You can use a backslash to escape double-quotes that are part of a quoted -username or password. -Note that quoting only a substring will not work, and be aware that your shell -will probably remove unprotected quotes or backslashes. -.PP -\fBarchivemail\fR tries to be smart when handling mailbox paths. -In particular, it will automatically add an IMAP NAMESPACE -prefix to the mailbox path if necessary; and if you are archiving a subfolder, -you can use the slash as a path separator instead of the IMAP server's -internal representation. -.SH "EXAMPLES" -.PP +When +\fBarchivemail\fR +processes an +IMAP +folder, all messages in that folder will have their +\eRecent +flag unset, and they will probably not show up as \*(Aqnew\*(Aq in your user agent later on\&. There is no way around this, it\*(Aqs just how +IMAP +works\&. This does not apply, however, if you run +\fBarchivemail\fR +with the options +\fB\-\-dry\-run\fR +or +\fB\-\-copy\fR\&. .PP -To archive all messages in the mailbox \fIdebian-user\fR that -are older than 180 days to a compressed mailbox called -\fIdebian-user_archive.gz\fR in the current directory: -.nf -bash$ \fBarchivemail debian-user\fR -.fi +\fBarchivemail\fR +relies on server\-side searches to determine the messages that should be archived\&. When matching message dates, +IMAP +servers refer to server internal message dates, and these may differ from both delivery time of a message and its +Date +header\&. Also, there exist broken servers which do not implement server side searches\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBIMAP URLS\fR +.RS 4 .PP + +\fBarchivemail\fR\*(Aqs +IMAP +URL +parser was written with the +RFC +2882 (Internet Message Format) rules for the +local\-part +of email addresses in mind\&. So, rather than enforcing an +URL\-style encoding of non\-ascii +and reserved characters, it allows to double\-quote the username and password\&. If your username or password contains the delimiter characters \*(Aq@\*(Aq or \*(Aq:\*(Aq, just quote it like this: +\fIimap://"username@bogus\&.com":"password"@imap\&.bogus\&.com/mailbox \fR\&. You can use a backslash to escape double\-quotes that are part of a quoted username or password\&. Note that quoting only a substring will not work, and be aware that your shell will probably remove unprotected quotes or backslashes\&. .PP -To archive all messages in the mailbox \fIdebian-user\fR that -are older than 180 days to a compressed mailbox called -\fIdebian-user_October_2001.gz\fR (where the current month and -year is April, 2002) in the current directory: +\fBarchivemail\fR +tries to be smart when handling mailbox paths\&. In particular, it will automatically add an +IMAP +NAMESPACE +prefix to the mailbox path if necessary; and if you are archiving a subfolder, you can use the slash as a path separator instead of the +IMAP +server\*(Aqs internal representation\&. +.RE +.SH "EXAMPLES" +.PP +To archive all messages in the mailbox +debian\-user +that are older than 180 days to a compressed mailbox called +debian\-user_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --suffix '_%B_%Y' debian-user\fR +bash$ \fBarchivemail debian\-user\fR .fi -.PP -.PP -To archive all messages in the mailbox \fIcm-melb\fR that -are older than the first of January 2002 to a compressed mailbox called -\fIcm-melb_archive.gz\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +debian\-user +that are older than 180 days to a compressed mailbox called +debian\-user_October_2001\&.gz +(where the current month and year is April, 2002) in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --date'1 Jan 2002' cm-melb\fR +bash$ \fBarchivemail \-\-suffix \*(Aq_%B_%Y\*(Aq debian\-user\fR .fi -.PP +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +cm\-melb +that are older than the first of January 2002 to a compressed mailbox called +cm\-melb_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} +.nf +bash$ \fBarchivemail \-\-date\*(Aq1 Jan 2002\*(Aq cm\-melb\fR +.fi +.if n \{\ +.RE +.\} .PP Exactly the same as the above example, using an ISO date format instead: - +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --date=2002-01-01 cm-melb\fR +bash$ \fBarchivemail \-\-date=2002\-01\-01 cm\-melb\fR .fi -.PP -.PP -To delete all messages in the mailbox \fIspam\fR that -are older than 30 days: - +.if n \{\ +.RE +.\} +.PP +To delete all messages in the mailbox +spam +that are older than 30 days: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --delete --days=30 spam\fR +bash$ \fBarchivemail \-\-delete \-\-days=30 spam\fR .fi -.PP -.PP -To archive all read messages in the mailbox \fIincoming\fR that -are older than 180 days to a compressed mailbox called -\fIincoming_archive.gz\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all read messages in the mailbox +incoming +that are older than 180 days to a compressed mailbox called +incoming_archive\&.gz +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --preserve-unread incoming\fR +bash$ \fBarchivemail \-\-preserve\-unread incoming\fR .fi -.PP -.PP -To archive all messages in the mailbox \fIreceived\fR that -are older than 180 days to an uncompressed mailbox called -\fIreceived_archive\fR in the current directory: - +.if n \{\ +.RE +.\} +.PP +To archive all messages in the mailbox +received +that are older than 180 days to an uncompressed mailbox called +received_archive +in the current directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail --no-compress received\fR +bash$ \fBarchivemail \-\-no\-compress received\fR .fi +.if n \{\ +.RE +.\} .PP -.PP -To archive all mailboxes in the directory \fI$HOME/Mail\fR +To archive all mailboxes in the directory +$HOME/Mail that are older than 90 days to compressed mailboxes in the -\fI$HOME/Mail/Archive\fR directory: - +$HOME/Mail/Archive +directory: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*\fR +bash$ \fBarchivemail \-d90 \-o $HOME/Mail/Archive $HOME/Mail/*\fR .fi -.PP -.PP -To archive all mails older than 180 days from the given \fBIMAP\fR -INBOX to a compressed mailbox INBOX_archive.gz in the -\fI$HOME/Mail/Archive\fR directory, quoting the password and -reading it from the environment variable \fBPASSWORD\fR: - +.if n \{\ +.RE +.\} +.PP +To archive all mails older than 180 days from the given +IMAP +INBOX to a compressed mailbox INBOX_archive\&.gz in the +$HOME/Mail/Archive +directory, quoting the password and reading it from the environment variable +\fBPASSWORD\fR: +.sp +.if n \{\ +.RS 4 +.\} .nf -bash$ \fBarchivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX\fR +bash$ \fBarchivemail \-o $HOME/Mail/Archive imaps://user:\*(Aq"\*(Aq$PASSWORD\*(Aq"\*(Aq@example\&.org/INBOX\fR .fi -.PP -Note the protected quotes. -.PP -.PP -To archive all mails older than 180 days in subfolders of "foo" on the -given \fBIMAP\fR server to corresponding archives in the current -working directory, reading the password from the file -\fI~/imap-pass.txt\fR: - +.if n \{\ +.RE +.\} +.PP +Note the protected quotes\&. +.PP +To archive all mails older than 180 days in subfolders of "foo" on the given +IMAP +server to corresponding archives in the current working directory, reading the password from the file +~/imap\-pass\&.txt: +.sp +.if n \{\ +.RS 4 +.\} .nf - bash$ \fBarchivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*\fR +bash$ \fBarchivemail \-\-pwfile=~/imap\-pass\&.txt imaps://user@example\&.org/foo/*\fR .fi +.if n \{\ +.RE +.\} .SH "TIPS" .PP -Probably the best way to run \fBarchivemail\fR is from your \fBcrontab\fR(5) -file, using the \fB--quiet\fR option. -Don't forget to try the \fB--dry-run\fR and perhaps the -\fB--copy\fR option for non-destructive testing. +Probably the best way to run +\fBarchivemail\fR +is from your +\fBcrontab\fR(5) +file, using the +\fB\-\-quiet\fR +option\&. Don\*(Aqt forget to try the +\fB\-\-dry\-run\fR +and perhaps the +\fB\-\-copy\fR +option for non\-destructive testing\&. .SH "EXIT STATUS" -.PP -Normally the exit status is 0. Nonzero indicates an unexpected error. +.sp +Normally the exit status is 0\&. Nonzero indicates an unexpected error\&. .SH "BUGS" -.PP -If an \fBIMAP\fR mailbox path contains slashes, the archive filename -will be derived from the basename of the mailbox. -If the server's folder separator differs from the Unix slash and is used in the -\fBIMAP\fR URL, however, the whole path will be considered -the basename of the mailbox. -E.g. the two URLs -\fBimap://user@example.com/folder/subfolder\fR and -\fBimap://user@example.com/folder.subfolder\fR will be -archived in \fIsubfolder_archive.gz\fR and -\fIfolder.subfolder_archive.gz\fR, respectively, although they -might refer to the same \fBIMAP\fR mailbox. -.PP -\fBarchivemail\fR does not support reading \fBMMDF\fR or -\fBBabyl\fR-format mailboxes. In fact, it will probably think it is -reading an \fBmbox\fR-format mailbox and cause all sorts of problems. -.PP -\fBarchivemail\fR is still too slow, but if you are running from \fBcrontab\fR(5) -you won't care. Archiving \fBmaildir\fR-format mailboxes should be -a lot quicker than \fBmbox\fR-format mailboxes since it is less -painful for the original mailbox to be reconstructed after selective message -removal. +.sp +If an IMAP mailbox path contains slashes, the archive filename will be derived from the basename of the mailbox\&. If the server\*(Aqs folder separator differs from the Unix slash and is used in the IMAP URL, however, the whole path will be considered the basename of the mailbox\&. E\&.g\&. the two URLs \fBimap://user@example\&.com/folder/subfolder\fR and \fBimap://user@example\&.com/folder\&.subfolder\fR will be archived in subfolder_archive\&.gz and folder\&.subfolder_archive\&.gz, respectively, although they might refer to the same IMAP mailbox\&. +.sp +\fBarchivemail\fR does not support reading MMDF or Babyl\-format mailboxes\&. In fact, it will probably think it is reading an mbox\-format mailbox and cause all sorts of problems\&. +.sp +\fBarchivemail\fR is still too slow, but if you are running from \fBcrontab\fR(5) you won\*(Aqt care\&. Archiving maildir\-format mailboxes should be a lot quicker than mbox\-format mailboxes since it is less painful for the original mailbox to be reconstructed after selective message removal\&. .SH "SEE ALSO" - -\fBpython\fR(1), \fBgzip\fR(1), \fBmutt\fR(1), \fBprocmail\fR(1) +.RS 4 + \fBpython\fR(1), \fBgzip\fR(1), \fBmutt\fR(1), \fBprocmail\fR(1) +.RE .SH "URL" -.PP -The \fBarchivemail\fR home page is currently hosted at -sourceforge <URL:http://archivemail.sourceforge.net> +.sp +The \fBarchivemail\fR home page is currently hosted at \m[blue]\fBsourceforge\fR\m[]\&\s-2\u[1]\d\s+2 .SH "AUTHOR" -.PP -This manual page was written by Paul Rodger <paul at paulrodger dot -com>\&. Updated and supplemented by Nikolaus Schulz -<microschulz@web.de> +.sp +This manual page was written by Paul Rodger <paul at paulrodger dot com>\&. Updated and supplemented by Nikolaus Schulz microschulz@web\&.de +.SH "NOTES" +.IP " 1." 4 +sourceforge +.RS 4 +\%http://archivemail.sourceforge.net +.RE |