Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
cyrus2dovecot(1)	   cyrus2dovecot user guide	      cyrus2dovecot(1)

NAME
       cyrus2dovecot - convert Cyrus folders to	Dovecot

SYNOPSIS
       cyrus2dovecot [-bcdmvq[q]] [-A cyrus-database-dir] [-C cyrus-inbox]
       [-Q cyrus-quota]	[-B cyrus-quota-dir] [-O cyrus-quota-format]
       [-S cyrus-seen] [-U cyrus-sub] [-H dovecot-host]	[-D dovecot-inbox]
       [-F dovecot-uidlist-format] [-z dovecot-zlib] [-N default-quota]
       [-E edit-foldernames] [user ...]

       cyrus2dovecot -h	| -v

DESCRIPTION
       cyrus2dovecot converts the e-mails of one or more users from Cyrus
       format to Dovecot Maildir++ folders.  If	no user	is specified, the user
       names are read from the standard	input, one per line.  Message "UID"s,
       "INTERNALDATE"s,	IMAP folder subscriptions, the "UIDVALIDITY" and
       "UIDNEXT" values	for each folder, as well as all	IMAP flags (including
       the first 26 user-defined keywords) are preserved during	the
       conversion.  The	generated e-mail filenames include the Maildir++
       extensions "S=<size>" and "W=<vsize>" (which are	used by	Dovecot	for
       better performance).  Optionally, Maildir++ maildirsize files are
       created.

OPTIONS
       Within the specified PATHs, any occurrence of %u	will be	replaced by
       the current user	name, any occurrence of	"%nu" will be replaced by the
       n'th character of that user name, any occurrence	of %h will be replaced
       by Cyrus' directory "hash" character for	that user name (i.e., %h is
       equivalent to %1u if the	first character	of the user name is a
       lowercase letter), and any occurrence of	%x will	be replaced by Cyrus'
       "fulldirhash" character for that	user name.  However, within the
       specified --cyrus-quota PATH (if	any), these replacements will only be
       done if the --cyrus-quota-format	VERSION	is set to 1.

       The default settings can	be found (and modified)	at the top of the
       cyrus2dovecot script.

       -A, --cyrus-database-dir=PATH
	       Set --cyrus-seen=PATH/%u.seen and --cyrus-sub=PATH/%u.sub.  The
	       latter options override this one.

       -C, --cyrus-inbox=PATH
	       Use this	PATH to	the user's INBOX folder	in Cyrus.

       -Q, --cyrus-quota=PATH
	       Use this	PATH to	the quota database file	in Cyrus, and create a
	       Maildir++ maildirsize file for each user	whose quota limit is
	       found in	that file.

       -B, --cyrus-quota-dir=PATH
	       Set --cyrus-quota=PATH/user.%u and --cyrus-quota-format=1.  The
	       latter options override this one.

       -O, --cyrus-quota-format=VERSION
	       Expect Cyrus' quota database(s) to be present in	this format
	       VERSION,	where VERSION 1	denotes	the "quotalegacy" format and
	       VERSION 2 denotes the "skiplist"	or the "flat" text format
	       (which of those two formats is used will	be autodetected	if
	       VERSION 2 is specified).	 This option is	ignored	if
	       --cyrus-quota is	not specified.

       -S, --cyrus-seen=PATH
	       Use this	PATH to	the user's seen	database file in Cyrus.	 If an
	       "old-style" cyrus.seen file exists within each Cyrus folder (as
	       opposed to a central cyrus.seen database	for all	folders	of a
	       user), cyrus.seen must be specified (literally) as the PATH.

       -U, --cyrus-sub=PATH
	       Use this	PATH to	the user's subscription	database file in
	       Cyrus.

       -c, --dovecot-crlf
	       Store e-mails with "CR+LF" instead of plain "LF".  This flag
	       should be specified if the "mail_save_crlf" option is set to
	       "yes" in	the Dovecot configuration.

       -H, --dovecot-host=NAME
	       Use this	host NAME for the Maildir++ e-mail file's basename.

       -D, --dovecot-inbox=PATH
	       Use this	PATH to	the user's INBOX folder	in Dovecot.

       -F, --dovecot-uidlist-format=VERSION
	       Create the dovecot-uidlist files	using this format VERSION.
	       For Dovecot releases older than 1.0.2, VERSION 1	must be
	       specified; otherwise, VERSION 3 can be used.

       -z, --dovecot-zlib
	       Store e-mails zlib compressed instead of	plain.

       -E, --edit-foldernames=SUBSTITUTION
	       Apply the specified SUBSTITUTION	to the name of each Maildir++
	       folder and subscription using Perl code such as
	       "eval('$name=~'.$substitution)",	where $name holds either the
	       string "INBOX" (which denotes the main Maildir) or the full
	       Maildir++ folder	name (e.g., .sub.folder), and $substitution
	       holds the specified SUBSTITUTION.  The resulting	$name will be
	       used as the Maildir++ folder's name.  This option may be
	       specified multiple times, in which case each of the
	       SUBSTITUTIONs will be applied to	each Maildir++ folder name in
	       the order specified on the command line.	 Note that while
	       Dovecot stores the subscribed folder names without the leading
	       "." of Maildir++	subfolders, cyrus2dovecot adds a leading "."
	       to each subscribed subfolder name before	applying the specified
	       SUBSTITUTION(s) and removes it afterwards (if it	still exists)
	       in order	to simplify the	matching.

       -N, --default-quota=BYTES
	       Create a	Maildir++ maildirsize file for each user, and set the
	       quota limit to the specified number of BYTES unless
	       --cyrus-quota is	also specified,	in which case a	user-specific
	       quota would override the	--default-quota	limit.	Specifying 0
	       BYTES disables the creation of maildirsize files	unless
	       --cyrus-quota is	also specified.

       -m, --dump-meta
	       Print a dump of the data	structure which	holds the metadata
	       gathered	from scanning the Cyrus	folders	of a user to the
	       standard	output.

       -d, --debug
	       Print information which is usually only useful for debugging to
	       the standard output.

       -q, --quiet
	       Suppress	any messages usually printed to	the standard output
	       (namely regarding nonexistent Cyrus database files) except for
	       the line	generated for each user	whose e-mails were
	       successfully converted.	If this	option is specified twice, the
	       latter line will	also be	omitted.  In either case, warning and
	       error messages, if any, will still be printed to	the standard
	       error output.

       -b, --bail
	       Bail out	immediately on any warnings and	errors.	 If this flag
	       is not specified	and a warning occurs, cyrus2dovecot prints a
	       message to the standard error output and	then tries to continue
	       the conversion.	If this	flag is	not specified and a non-fatal
	       error occurs, cyrus2dovecot prints a message to the standard
	       error output and	then tries to convert the e-mails of the
	       remaining users (if any).  (Note	that cyrus2dovecot always
	       bails out immediately on	warnings generated by the Perl
	       interpreter, as they indicate cyrus2dovecot bugs.)

       -h, --help
	       Print usage information to the standard output and exit.

       -v, --version
	       Print version information to the	standard output	and exit.

RETURN VALUE
       cyrus2dovecot exits 0 on	success, and >0	if one or more errors occur
       during the conversion of	the e-mails of one or more users.

EXAMPLES
       Given that the path to the INBOX	folders	in Cyrus is
       /var/spool/imap/user/%u (where %u denotes the user name), that Cyrus
       stores the seen and subscription	databases within the directory
       /var/imap/user/%h, and that Cyrus stores	"quotalegacy" files within the
       directory /var/imap/quota/%h (where %h denotes Cyrus' directory "hash"
       character for that user name, respectively), the	following command
       would convert all e-mails of the	users "bill" and "george" from Cyrus
       to Dovecot, and the result would	be stored below	/tmp/dovecot
       (including maildirsize files for	both users if their quota limits are
       found):

	       cyrus2dovecot --cyrus-database-dir /var/imap/user/%h    \
			     --cyrus-quota-dir /var/imap/quota/%h      \
			     --cyrus-inbox /var/spool/imap/user/%u     \
			     --dovecot-inbox /tmp/dovecot/%u/Maildir   \
			     bill george

       Given that the default settings specified at the	top of the
       cyrus2dovecot script are	correct, and that /tmp/users holds the names
       of all users whose e-mails should be converted (one per line), the
       following command would convert all e-mails of those users:

	       cyrus2dovecot < /tmp/users

       Given that the default settings specified at the	top of the
       cyrus2dovecot script are	correct, a command such	as the following could
       be used in order	to convert all e-mails of all users (of	course,	the
       path to the INBOX folders in Cyrus may have to be adjusted; e.g., if
       the "hashimapspool" option is not enabled in the	Cyrus configuration,
       /? must be removed from the path):

	       find /var/spool/imap/user/?/. \!	-name .	-prune \
		    -exec basename \{\}	\; | cyrus2dovecot

       Cyrus transparently replaces any	"." character in folder	names with a
       "^" character.  Dovecot supports	"." characters in Maildir++ folder
       names if	the "listescape" plugin	is used, which replaces	any "."
       character in folder names with the string "\2e".	 The following
       argument	could be added to the cyrus2dovecot command line in order to
       replace any "^" character in Cyrus folder names with "\2e" for the
       Maildir++ folder	name:

	       --edit-foldernames 's/\^/\\2e/g'

       Dovecot 1.1 and newer support using folders such	as Maildir/sub/folder
       (as opposed to Maildir/.sub.folder) if ":LAYOUT=fs" was added to	the
       "mail_location" in the Dovecot configuration.  The following
       cyrus2dovecot arguments could be	specified in order to create such
       folders by removing the leading dot from	Maildir++ subfolder names and
       then substituting any following dots with slashes:

	       --edit-foldernames 's/^\.//'    \
	       --edit-foldernames 's/\./\//g'

       If the seen states, subscriptions, or quotas are	stored in Berkeley
       databases, they must first be converted to one of the formats supported
       by cyrus2dovecot	using a	command	such as	the following:

	       cvt_cyrusdb /var/imap/user/b/bill.seen berkeley \
			   /tmp/imap/user/b/bill.seen skiplist

CAVEATS
       cyrus2dovecot assumes that the user has no e-mails in Dovecot yet and
       that neither his	Cyrus folders nor his Dovecot folders will be accessed
       by another process during the conversion.

       If "%nu"	is specified within any	PATH on	the command line, all user
       names must have a length	of at least n characters.  Otherwise,
       cyrus2dovecot will die with an exception.

       If folder name substitutions are	specified via --edit-foldernames, the
       resulting Maildir++ folder names	must be	unique.

RESTRICTIONS
       Cyrus' seen and subscription databases must be present either in	the
       "skiplist" format or in the "flat" text format, and Cyrus' quota
       database(s) (if any) must be present either in one of those formats or
       in the "quotalegacy" format, as cyrus2dovecot doesn't support Berkeley
       databases.  However, Berkeley databases can be converted	to one of the
       supported formats using cvt_cyrusdb(8), see the "EXAMPLES".

       In maildirsize files created by cyrus2dovecot, no limit for the number
       of messages is specified	(as such a limit does not seem useful).

       Cyrus' ACL settings are not converted.

COMPATIBILITY
       cyrus2dovecot is	supposed to work with all Cyrus	releases up to (at
       least) version 2.3.x.  So far, it has been tested with Cyrus 1.4,
       2.1.18, 2.2.12, and 2.3.12p2.

SEE ALSO
       Other tools for converting e-mails from Cyrus to	Dovecot	can be found
       at <http://wiki.dovecot.org/Migration/Cyrus>.

AUTHOR
       Written by Holger Weiss <holger@ZEDAT.FU-Berlin.DE> at Freie
       Universitaet Berlin, Germany, Zentraleinrichtung	fuer Datenverarbeitung
       (ZEDAT).

COPYRIGHT AND LICENSE
       Copyright (c) 2008 Freie	Universitaet Berlin.  All rights reserved.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See perlartistic.	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.

HISTORY
	       $Log: cyrus2dovecot,v $
	       Revision	1.3  2008/10/05	17:45:06  holger
	       If a seen state,	subscription, or quota database	is not found, a
	       message will now	be printed.  As	this does not necessarily
	       indicate	a problem, such	messages can be	suppressed by
	       specifying the "--quiet"	option.	 Apart from that, the
	       "--cyrus-database-dir" and "--cyrus-quota-dir" options (which
	       are merely convenience aliases) have been added,	and various
	       minor enhancements have been applied.

	       Revision	1.2  2008/09/24	09:52:33  holger
	       Message seen states are now parsed more efficiently with	regard
	       to performance and memory usage.	 Apart from that, minor	code
	       cleanups	have been applied.

	       Revision	1.1  2008/09/22	08:36:44  holger
	       Initial release.

1.3				  2020-08-10		      cyrus2dovecot(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN VALUE | EXAMPLES | CAVEATS | RESTRICTIONS | COMPATIBILITY | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cyrus2dovecot&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help