mirror
/
archivemail
mirror of https://git.code.sf.net/p/archivemail/code
1
0
Fork 0
Code Issues Releases Wiki Activity

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
This commit is contained in:
Nikolaus Schulz 2007-10-24 14:58:47 +00:00
parent d566d6c8f3
commit 9b7768e073
2 changed files with 92 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
archivemail.1
View File

@ -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 <URL:http://archivemail.sourceforge.net>
.SH "AUTHOR"
.PP
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>

67
archivemail.sgml
View File

@ -35,7 +35,7 @@
<RefEntry>
<DocInfo><Date>23 October 2007</Date></DocInfo>
<DocInfo><Date>24 October 2007</Date></DocInfo>
<RefMeta>
<RefEntryTitle>archivemail</RefEntryTitle>
@ -80,6 +80,22 @@ mailboxes, but it will always write archive files to <application/mbox/-format
mailboxes that are compressed with &gzip;.
</Para>
<Para>
To archive an <application/IMAP/-format mailbox, use the format
<replaceable>imap://username:password@server/mailbox
</replaceable> to specify the mailbox.
You can omit the password from the <acronym/URL/; use the
<option>--pwfile</option> option to make <command/archivemail/ read the
password from a file, or alternatively just enter it upon request.
If the <option>--pwfile</option> option is set, <command/archivemail/ does not
look for a password in the <acronym/URL/, and the colon is not considered a
delimiter.
Substitute '<userinput/imap/' with '<userinput/imaps/', and
<command/archivemail/ will establish a secure <acronym/SSL/ connection.
See below for more <application/IMAP/ peculiarities.
</Para>
<Para>
<Command/archivemail/ has some support for being run as the root user on
user mailboxes. When running as root, it will &seteuid; to the owner of the
@ -346,19 +362,6 @@ Display brief summary information about how to run <Command/archivemail/.
<Command/archivemail/ requires &python; version 2.3 or later.
</Para>
<Para>
To archive an <application/IMAP/-format mailbox, use the format
<command>imap://username:password@server/mailbox</command> to specify the
mailbox. If your username or password contains the '@' or ':' character,
you can double-quote it like this:
<command>imap://"username@bogus.com":"password"@server/mailbox</command>. Use a
backslash to escape double-quotes that are part of a quoted username or password.
You can omit the password from the <acronym/URL/; use the <option>--pwfile</option>
option to make <command/archivemail/ read the password from a file, or just
enter it upon request. Substitute '<acronym/imap/' with '<acronym/imaps/', and
<command/archivemail/ will establish a secure <acronym/SSL/ connection.
</Para>
<Para>
When reading an <application/mbox/-format mailbox, <command/archivemail/ will
create a lockfile with the extension <filename>.lock</filename> so that
@ -396,6 +399,26 @@ will use the last-modified file timestamp on <application/MH/ and
links or create tempfiles or archives in world-writable directories.
</Para>
<RefSect2>
<Title><acronym/IMAP/ <acronym/URL/s</Title>
<Para>
<command/archivemail/'s <application/IMAP/ <acronym/URL/ parser was written
with the <acronym>RFC</acronym> 2882 (<citetitle>Internet Message
Format</citetitle>) rules for the <token>local-part</token> of email addresses
in mind.
So, rather than enforcing an <acronym/URL/-style encoding of non-<acronym/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:
<replaceable>imap://"username@bogus.com":"password"@imap.bogus.com/mailbox
</replaceable>.
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.
</Para>
</RefSect2>
</RefSect1>
<RefSect1>
@ -471,6 +494,19 @@ that are older than 90 days to compressed mailboxes in the
</screen>
</Para>
<Para>
To archive all mails older than 180 days from the given <application/IMAP/
INBOX to a compressed mailbox INBOX_archive.gz in the
<filename>$HOME/Mail/Archive</filename> directory, quoting the password and
reading it from the environment variable <envar>PASSWORD</envar>:
</Para>
<!-- I'm open to suggestions how to avoid making such a super-long line here. -->
<screen>
<prompt>bash$ </prompt><userinput>archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX</userinput>
</screen>
<Para>
Note the protected quotes.
</Para>
</RefSect1>
<RefSect1>
@ -527,7 +563,8 @@ removal.
<RefSect1>
<Title>Author</Title>
<SimPara> This manual page was written by Paul Rodger &lt;paul at paulrodger dot
com&gt;. Updated by Nikolaus Schulz <email>microschulz@web.de</email></SimPara>
com&gt;. Updated and supplemented by Nikolaus Schulz
<email>microschulz@web.de</email></SimPara>
</RefSect1>
</RefEntry>