From 9b7768e07318f3c75e957024db8407191354764a Mon Sep 17 00:00:00 2001 From: Nikolaus Schulz Date: Wed, 24 Oct 2007 14:58:47 +0000 Subject: Rewrote and reordered parts of the manpage: * Move paragraph about archiving IMAP folders before the option list * Added section subsection about IMAP URL handling * Added IMAP example command line --- archivemail.1 | 52 +++++++++++++++++++++++++++++++++---------- archivemail.sgml | 67 +++++++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 92 insertions(+), 27 deletions(-) diff --git a/archivemail.1 b/archivemail.1 index 27b53ce..75194cd 100644 --- a/archivemail.1 +++ b/archivemail.1 @@ -26,6 +26,18 @@ with \fBgzip\fR(1)\&. mailboxes, but it will always write archive files to \fBmbox\fR-format mailboxes that are compressed with \fBgzip\fR(1)\&. .PP +To archive an \fBIMAP\fR-format mailbox, use the format +\fIimap://username:password@server/mailbox\fR to specify the mailbox. +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. +.PP \fBarchivemail\fR has some support for being run as the root user on user mailboxes. When running as root, it will \fBseteuid\fR(2) to the owner of the mailbox it is reading, creating any archive files as that user. @@ -218,17 +230,6 @@ Display brief summary information about how to run \fBarchivemail\fR\&. .PP \fBarchivemail\fR requires \fBpython\fR(1) version 2.3 or later. .PP -To archive an \fBIMAP\fR-format mailbox, use the format -\fBimap://username:password@server/mailbox\fR to specify the -mailbox. If your username or password contains the '@' or ':' character, -you can double-quote it like this: -\fBimap://"username@bogus.com":"password"@server/mailbox\fR\&. Use a -backslash to escape double-quotes that are part of a quoted username or password. -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 just -enter it upon request. Substitute 'imap\&' with 'imaps\&', and -\fBarchivemail\fR will establish a secure SSL connection. -.PP 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 @@ -255,6 +256,21 @@ will use the last-modified file timestamp on \fBMH\fR and .PP \fBarchivemail\fR will refuse to operate on mailboxes that are symbolic links or create tempfiles or archives in world-writable directories. +.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. .SH "EXAMPLES" .PP To archive all messages in the mailbox \fIdebian-user\fR that @@ -318,6 +334,17 @@ that are older than 90 days to compressed mailboxes in the .nf bash$ \fBarchivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*\fR .fi +.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: + +.nf +bash$ \fBarchivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX\fR +.fi +.PP +Note the protected quotes. .SH "TIPS" .PP Probably the best way to run \fBarchivemail\fR is from your \fBcrontab\fR(5) @@ -350,4 +377,5 @@ sourceforge .SH "AUTHOR" .PP This manual page was written by Paul Rodger \&. Updated by Nikolaus Schulz +com>\&. Updated and supplemented by Nikolaus Schulz + diff --git a/archivemail.sgml b/archivemail.sgml index ff3ecd5..3ef7fac 100644 --- a/archivemail.sgml +++ b/archivemail.sgml @@ -35,7 +35,7 @@ -23 October 2007 +24 October 2007 archivemail @@ -80,6 +80,22 @@ mailboxes, but it will always write archive files to + +To archive an imap://username:password@server/mailbox + to specify the mailbox. +You can omit the password from the --pwfile option to make --pwfile option is set, + + - -To archive an imap://username:password@server/mailbox to specify the -mailbox. If your username or password contains the '@' or ':' character, -you can double-quote it like this: -imap://"username@bogus.com":"password"@server/mailbox. Use a -backslash to escape double-quotes that are part of a quoted username or password. -You can omit the password from the --pwfile -option to make - When reading an .lock so that @@ -396,6 +399,26 @@ will use the last-modified file timestamp on + +<acronym/IMAP/ <acronym/URL/s + +RFC 2882 (Internet Message +Format) rules for the local-part of email addresses +in mind. +So, rather than enforcing an imap://"username@bogus.com":"password"@imap.bogus.com/mailbox +. +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. + + + @@ -471,6 +494,19 @@ that are older than 90 days to compressed mailboxes in the + + To archive all mails older than 180 days from the given $HOME/Mail/Archive directory, quoting the password and + reading it from the environment variable PASSWORD: + + + +bash$ archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX + + + Note the protected quotes. + @@ -527,7 +563,8 @@ removal. Author This manual page was written by Paul Rodger <paul at paulrodger dot -com>. Updated by Nikolaus Schulz microschulz@web.de +com>. Updated and supplemented by Nikolaus Schulz +microschulz@web.de -- cgit v1.2.3