123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344 |
- .ig
- \" isync - IMAP4 to maildir mailbox synchronizer
- \" Copyright (C) 2000-2002 Michael R. Elkins <me@mutt.org>
- \"
- \" This program is free software; you can redistribute it and/or modify
- \" it under the terms of the GNU General Public License as published by
- \" the Free Software Foundation; either version 2 of the License, or
- \" (at your option) any later version.
- \"
- \" This program is distributed in the hope that it will be useful,
- \" but WITHOUT ANY WARRANTY; without even the implied warranty of
- \" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- \" GNU General Public License for more details.
- \"
- \" You should have received a copy of the GNU General Public License
- \" along with this program; if not, write to the Free Software
- \" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- \"
- \" As a special exception, isync may be linked with the OpenSSL library,
- \" despite that library's more restrictive license.
- ..
- .TH isync 1 "2002 Dec 22"
- ..
- .SH NAME
- isync - synchronize IMAP4 and maildir mailboxes
- ..
- .SH SYNOPSIS
- \fBisync\fR [\fIoptions...\fR] \fImailbox\fR [\fImailbox ...\fR]
- .br
- \fBisync\fR [\fIoptions...\fR] \fI-a\fR
- .br
- \fBisync\fR [\fIoptions...\fR] \fI-l\fR
- ..
- .SH DESCRIPTION
- \fBisync\fR is a command line application which synchronizes a local
- maildir-style mailbox with a remote IMAP4 mailbox, suitable for use in
- IMAP-disconnected mode. Multiple copies of the remote IMAP4 mailbox can
- be maintained, and all flags are synchronized.
- ..
- .SH OPTIONS
- .TP
- \fB-c\fR, \fB--config\fR \fIfile\fR
- Read configuration from \fIfile\fR.
- By default, the configuration is read from ~/.isyncrc if it exists.
- .TP
- \fB-1\fR, \fB--one-to-one\fR
- Instead of using the mailbox specifications in ~/.isyncrc, isync will pick up
- all mailboxes from the local directory and remote folder and map them 1:1
- onto each other according to their names.
- .TP
- \fB-I\fR, \fB--inbox\fR \fImailbox\fR
- Exception to the 1:1 mapping created by -1: the special IMAP mailbox \fIINBOX\fR
- is mapped to the local \fImailbox\fR (relative to the maildir).
- .TP
- \fB-a\fR, \fB--all\fR
- Synchronize all mailboxes (either specified in ~/.isyncrc or determined by the
- 1:1 mapping).
- .TP
- \fB-l\fR, \fB--list\fR
- Don't synchronize anything, but list all mailboxes and exit.
- .TP
- \fB-L\fR, \fB--create-local\fR
- Automatically create the local maildir-style mailbox if it doesn't already
- exist.
- .TP
- \fB-R\fR, \fB--create-remote\fR
- Automatically create the remote IMAP mailbox if it doesn't already exist.
- .TP
- \fB-C\fR, \fB--create\fR
- Automatically create any mailboxes if they don't already exist.
- This is simply a combination of -L and -R.
- .TP
- \fB-d\fR, \fB--delete\fR
- Causes \fBisync\fR to delete messages from the local maildir mailbox
- which do not exist on the IMAP server. By default, \fIdead\fR messages
- are \fBnot\fR deleted.
- .TP
- \fB-e\fR, \fB--expunge\fR
- Causes \fBisync\fR to permanently remove all messages marked for deletion
- in both the local maildir mailbox and the remote IMAP mailbox. By default,
- \fIdeleted\fR messages are \fBnot\fR expunged.
- .TP
- \fB-f\fR, \fB--fast\fR
- Causes \fBisync\fR to skip the step of synchronzing message flags between the
- local maildir mailbox and the IMAP mailbox. Only new messages existing on the
- server will be fetched into the local mailbox.
- .TP
- \fB-h\fR, \fB--help\fR
- Displays a summary of command line options
- .TP
- \fB-p\fR, \fB--port\fR \fIport\fR
- Specifies the port on the IMAP server to connect to (default: 143)
- .TP
- \fB-q\fR, \fB--quiet\fR
- Suppress informational messages.
- If specified twice, suppress warning messages as well.
- .TP
- \fB-r\fR, \fB--remote\fR \fIbox\fR
- Specifies the name of the remote IMAP mailbox to synchronize with
- (Default: INBOX)
- .TP
- \fB-s\fR, \fB--host\fR \fB[\fRimaps:\fB]\fR\fIhost\fR
- Specifies the hostname of the IMAP server
- .TP
- \fB-u\fR, \fB--user\fR \fIuser\fR
- Specifies the login name to access the IMAP server (default: $USER)
- .TP
- \fB-M\fR, \fB--maildir\fR \fIdir\fR
- Specifies the location for your local mailboxes.
- .TP
- \fB-F\fR, \fB--folder\fR \fIfolder\fR/
- Specifies the location for your remote mailboxes.
- .TP
- \fB-v\fR, \fB--version\fR
- Displays \fBisync\fR version information.
- .TP
- \fB-V\fR, \fB--verbose\fR
- Enables \fIverbose\fR mode, which displays the IMAP4 network traffic.
- ..
- .SH CONFIGURATION
- \fBisync\fR reads \fI~/.isyncrc\fR to load default configuration data.
- Each line of the configuration file consists of a command.
- The following commands are understood:
- .TP
- \fBMailbox\fR \fIpath\fR
- Defines a local maildir mailbox. All configuration commands following this
- line, up until the next \fIMailbox\fR command, apply to this mailbox only.
- ..
- .TP
- \fBHost\fR \fB[\fRimaps:\fB]\fR\fIname\fR
- Defines the DNS name or IP address of the IMAP server. If the hostname is
- prefixed with \fIimaps:\fR the connection is assumed to be a SSL connection
- to port 993 (though you can change this by placing a \fBPort\fR command
- \fBafter\fR the \fBHost\fR command. Note that some servers support SSL on
- the default port 143. \fBisync\fR will always attempt to use SSL if available.
- ..
- .TP
- \fBPort\fR \fIport\fR
- Defines the TCP port number on the IMAP server to use (Default: 143)
- ..
- .TP
- \fBBox\fR \fImailbox\fR
- Defines the name of the remote IMAP mailbox associated with the local
- maildir mailbox (Default: INBOX)
- ..
- .TP
- \fBUser\fR \fIusername\fR
- Defines the login name on the IMAP server (Default: current user)
- ..
- .TP
- \fBPass\fR \fIpassword\fR
- Defines the password for \fIusername\fR on the IMAP server.
- Note that this option is \fBNOT\fR required.
- If no password is specified in the configuration file, \fBisync\fR
- will prompt you for it.
- ..
- .TP
- \fBAlias\fR \fIstring\fR
- Defines an alias for the mailbox which can be used as a shortcut on the
- command line.
- ..
- .TP
- \fBCopyDeletedTo\fR \fImailbox\fR
- Specifies the remote IMAP mailbox to copy deleted messages prior to
- expunging (Default: none).
- ..
- .TP
- \fBDelete\fR \fIyes\fR|\fIno\fR
- Specifies whether messages in the local copy of the mailbox which don't
- exist on the server are automatically deleted. (Default: no).
- \fBNOTE:\fR The \fI-d\fR command line option overrides this setting when
- set to \fIno\fR.
- ..
- .TP
- \fBExpunge\fR \fIyes\fR|\fIno\fR
- Specifies whether deleted messages are expunged by default (Default: no).
- \fBNOTE:\fR The \fI-e\fR command line option overrides this setting when
- set to \fIno\fR.
- ..
- .TP
- \fBMailDir\fR \fIdirectory\fR
- Specifies the location of your local mailboxes if a relative path is
- specified in a \fIMailbox\fR command (Default: \fI~\fR).
- \fBNOTE:\fR This directive is only meaningful in the \fIglobal\fR
- section (see below).
- ..
- .TP
- \fBFolder\fR \fIdirectory\fR/
- Specifies the location of your IMAP mailboxes
- specified in \fIBox\fR commands (Default: \fI""\fR).
- \fBNOTE:\fR You \fBmust\fR append the hierarchy delimiter (usually
- a slash) to this specification.
- \fBNOTE 2:\fR This directive is only meaningful in the \fIglobal\fR
- section (see below).
- ..
- .TP
- \fBMaxMessages\fR \fIcount\fR
- Sets the number of messages \fBisync\fR should keep in a mailbox.
- This is useful for mailboxes where you keep a complete archive on the
- server, but want to mirror only the last messages (for instance, for mailing
- lists.)
- The messages that were the first to arrive in the mailbox (independent of the
- actual date of the message) will automatically be deleted if you
- pass \fBisync\fR the delete (-d, --delete) flag.
- Messages that are flagged (marked as important) will not be automatically
- deleted.
- If \fIcount\fR is 0, the maximum number of messages is \fBunlimited\fR
- (Default: 0).
- ..
- .TP
- \fBMaxSize\fR \fIbytes\fR
- Sets a threshold for the maximum message size (in bytes) for which \fBisync\fR
- should transfer over the wire. This is useful for weeding out messages with
- large attachments. If \fIbytes\fR is 0, the maximum file size is \fBunlimited\fR.
- ..
- .TP
- \fBTunnel\fR \fIcommand\fR
- Specify a command to run to establish a connection rather than opening a TCP
- socket. This allows you to run an IMAP session over an SSH tunnel, for
- example.
- .TP
- \fBUseNamespace\fR \fIyes\fR|\fIno\fR
- Selects whether \fBisync\fR should select mailboxes using the namespace given
- by the NAMESPACE command. This is useful with broken IMAP servers. (Default:
- \fIyes\fR)
- ..
- .TP
- \fBRequireCRAM\fR \fIyes\fR|\fIno\fR
- If set to \fIyes\fR, \fBisync\fR will require that the server accept CRAM-MD5
- intead of PLAIN to authenticate the user.
- ..
- .TP
- \fBRequireSSL\fR \fIyes\fR|\fIno\fR
- \fBisync\fR will abort the connection if a TLS/SSL session to the IMAP
- server can not be established. (Default: \fIyes\fR)
- ..
- .TP
- \fBCertificateFile\fR \fIpath\fR
- File containing X.509 CA certificates used to verify server identities.
- ..
- .TP
- \fBUseSSLv2\fR \fIyes\fR|\fIno\fR
- Should \fBisync\fR use SSLv2 for communication with the IMAP server over SSL?
- (Default: \fIyes\fR if the imaps port is used, otherwise \fIno\fR)
- ..
- .TP
- \fBUseSSLv3\fR \fIyes\fR|\fIno\fR
- Should \fBisync\fR use SSLv3 for communication with the IMAP server over SSL?
- (Default: \fIyes\fR if the imaps port is used, otherwise \fIno\fR)
- ..
- .TP
- \fBUseTLSv1\fR \fIyes\fR|\fIno\fR
- Should \fBisync\fR use TLSv1 for communication with the IMAP server over SSL?
- (Default: \fIyes\fR)
- ..
- .TP
- \fBOneToOne\fR
- \fBisync\fR will ignore any \fIMailbox\fR specifications and instead pick up
- all mailboxes from the local \fIMailDir\fR and remote \fIFolder\fR and map
- them 1:1 onto each other according to their names.
- \fBNOTE:\fR This directive is only meaningful in the \fIglobal\fR
- section (see below).
- ..
- .TP
- \fBInbox\fR \fImailbox\fR
- Exception to the OneToOne mapping: the special IMAP mailbox \fIINBOX\fR
- is mapped to the local \fImailbox\fR (relative to the \fIMailDir\fR).
- \fBNOTE:\fR This directive is only meaningful in the \fIglobal\fR
- section (see below).
- ..
- .P
- Configuration commands that appear prior to the first \fBMailbox\fR
- command are considered to be \fIglobal\fR
- options which are used as defaults when those specific options are not
- specifically set for a defined Mailbox. For example, if you use the same
- login name for several IMAP servers, you can put a \fBUser\fR command before
- the first \fBMailbox\fR command, and then leave out the \fBUser\fR command
- in the sections for each mailbox.
- \fBisync\fR will then use the global value by default.
- ..
- .SH MAIL USER AGENT INTERACTION
- To use \fBisync\fR effectively, you need a mail client that sets the T
- (trashed) flag when it deletes a message from a maildir mailbox, instead of
- just removing it altogether. Without such a client, \fBisync\fR will refetch the
- locally deleted messages from the server since they will never get expunged.
- Mutt (starting with version 1.3.27) is known to support this. Be sure to put
- .IP "" 2
- set maildir_trash
- .PP
- in your ~/.muttrc when using Mutt.
- .br
- \fBisync\fR can be integrated into Mutt fairly easily with a few hooks:
- .IP "" 2
- .nf
- folder-hook ~A bind index $ <sync-mailbox>
- .br
- folder-hook +\fImdir\fR 'macro index $ "<sync-mailbox>!isync -e \fImdir\fR\\n"'
- .fi
- .PP
- where \fImdir\fR is the name of the local mailbox (or its \fIalias\fR).
- This works well so long as you are not modifying the IMAP mailbox outside of
- Mutt. However, if you are using another mail program simultaneously Mutt
- will have the wrong idea of the local mailbox flags and messages will start
- disappearing from its index display (don't worry, they are still on disk).
- ..
- .SH FILES
- .TP
- .B ~/.isyncrc
- Default configuration file
- ..
- .SH BUGS
- No support for IMAP subfolders.
- .P
- \fBisync\fR does not use NFS-safe locking. It will correctly prevent
- concurrent synchronization of a mailbox on the same host, but not across NFS.
- .P
- When synchronizing multiple mailboxes on the same IMAP server, it is not
- possible to select different SSL options for each mailbox. Only the options
- from the first mailbox are applied since the SSL session is reused.
- .P
- If new mail arrives in the IMAP mailbox after \fBisync\fR
- has retrieved the initial message list, the new mail will not be fetched
- until the next time \fBisync\fR is invoked.
- .P
- It is currently impossible to unset the \\Flagged attribute of a message
- once it is set. It has to be manually unset everywhere since isync
- doesn't have enough information to know which was the last status of the
- message.
- .P
- The ndbm database created for each mailbox is not portable across different
- architectures. It currently stores the UID in host byte order.
- .P
- The configuration file takes precedence over command line options.
- .br
- Use -c /dev/null to work around.
- .SH SEE ALSO
- mutt(1), maildir(5)
- .P
- Up to date information on \fBisync\fR can be found at http://isync.sf.net/
- ..
- .SH AUTHOR
- Written by Michael R. Elkins <me@mutt.org>,
- .br
- maintained by Oswald Buddenhagen <ossi@users.sf.net>.
|