# HG changeset patch # User Pascal Volk # Date 1277733399 0 # Node ID be2b7d2901a046f5c8acf726c59b05b585da9143 # Parent 9be162cc2c52b75e3a76467a2c8ebede65ad2d01 doc: added manual pages diff -r 9be162cc2c52 -r be2b7d2901a0 .hgignore --- a/.hgignore Mon Jun 28 13:30:32 2010 +0100 +++ b/.hgignore Mon Jun 28 13:56:39 2010 +0000 @@ -95,3 +95,5 @@ syntax: regexp src/.*/test-[^\.]*$ +doc/man/doveadm-(altmove|auth|director|dump|expunge|fetch|force-resync|help|kick|log|mailbox|penalty|purge|pw|quota|search|user|who)\.1$ +doc/man/(doveadm|doveconf|dovecot-lda|dovecot|dsync)\.1$ diff -r 9be162cc2c52 -r be2b7d2901a0 Makefile.am --- a/Makefile.am Mon Jun 28 13:30:32 2010 +0100 +++ b/Makefile.am Mon Jun 28 13:56:39 2010 +0000 @@ -1,13 +1,9 @@ aclocaldir = $(datadir)/aclocal -if BUILD_DOCS -DOCS = doc -endif - SUBDIRS = \ . \ src \ - $(DOCS) + doc dist_pkginclude_HEADERS = \ dovecot-version.h diff -r 9be162cc2c52 -r be2b7d2901a0 configure.in --- a/configure.in Mon Jun 28 13:30:32 2010 +0100 +++ b/configure.in Mon Jun 28 13:56:39 2010 +0000 @@ -2614,6 +2614,7 @@ AC_CONFIG_FILES([ Makefile doc/Makefile +doc/man/Makefile doc/wiki/Makefile doc/example-config/Makefile doc/example-config/conf.d/Makefile diff -r 9be162cc2c52 -r be2b7d2901a0 doc/Makefile.am --- a/doc/Makefile.am Mon Jun 28 13:30:32 2010 +0100 +++ b/doc/Makefile.am Mon Jun 28 13:56:39 2010 +0000 @@ -1,4 +1,8 @@ -SUBDIRS = wiki example-config +if BUILD_DOCS +DOCDIRS = wiki example-config +endif + +SUBDIRS = man $(DOCDIRS) docfiles = \ auth-protocol.txt \ diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/Makefile.am --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/Makefile.am Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,68 @@ +dist_man1_MANS = \ + deliver.1 \ + doveadm-reload.1 \ + doveadm-stop.1 + +dist_man7_MANS = \ + doveadm-search-query.7 + +nodist_man1_MANS = \ + doveadm.1 \ + doveadm-altmove.1 \ + doveadm-auth.1 \ + doveadm-director.1 \ + doveadm-dump.1 \ + doveadm-expunge.1 \ + doveadm-fetch.1 \ + doveadm-force-resync.1 \ + doveadm-help.1 \ + doveadm-kick.1 \ + doveadm-log.1 \ + doveadm-mailbox.1 \ + doveadm-penalty.1 \ + doveadm-purge.1 \ + doveadm-pw.1 \ + doveadm-quota.1 \ + doveadm-search.1 \ + doveadm-user.1 \ + doveadm-who.1 \ + doveconf.1 \ + dovecot.1 \ + dovecot-lda.1 \ + dsync.1 + +EXTRA_DIST = \ + doveadm.1.in \ + doveadm-altmove.1.in \ + doveadm-auth.1.in \ + doveadm-director.1.in \ + doveadm-dump.1.in \ + doveadm-expunge.1.in \ + doveadm-fetch.1.in \ + doveadm-force-resync.1.in \ + doveadm-help.1.in \ + doveadm-kick.1.in \ + doveadm-log.1.in \ + doveadm-mailbox.1.in \ + doveadm-penalty.1.in \ + doveadm-purge.1.in \ + doveadm-pw.1.in \ + doveadm-quota.1.in \ + doveadm-search.1.in \ + doveadm-user.1.in \ + doveadm-who.1.in \ + doveconf.1.in \ + dovecot.1.in \ + dovecot-lda.1.in \ + dsync.1.in \ + global-options-formatter.inc \ + global-options.inc \ + option-A.inc \ + option-u-user.inc \ + reporting-bugs.inc \ + sed.sh + +CLEANFILES = $(nodist_man1_MANS) + +%.1: $(srcdir)/%.1.in Makefile + $(SHELL) $(srcdir)/sed.sh $(srcdir) $(rundir) $(sysconfdir) < $< > $@ diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/deliver.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/deliver.1 Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,1 @@ +.so man1/dovecot-lda.1 \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-altmove.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-altmove.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-ALTMOVE 1 "2010-06-23" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-altmove \- Move matching mails to the alternative storage (dbox\-only) +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " altmove +.I search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] " "altmove \-A" +.I search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] " "altmove \-u" +.I user search_query +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +This command can be used with dbox or mdbox storage to move mails to +alternative storage path when :ALT= is specified for the mail +location. +.PP +In the first form, +.BR doveadm (1) +will executed the +.B altmove +action with the environment of the logged in system user. +.PP +In the second form, the command will be performed for all users. +.PP +In the third form, only matching mails of the given +.IR user (s) +will be moved to the alternative storage. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I search_query +Messages matching this search query will be moved to alt storage. +See +.BR doveadm\-search\-query (7) +for details. +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/conf.d/10\-mail.conf +Mailbox locations and namespaces. +.TP +.I @sysconfdir@/dovecot/conf.d/auth\-*.conf.ext +Authentication processes, including userdb settings. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example moves seen mails older than one week to alternative storage +under /nfsmount: +.br +.nf +mail_location = mdbox:~/mdbox:ALT=/nfsmount/%h/mdbox +.fi +.PP +.nf +.B doveadm altmove \-u johnd@example.com seen savedbefore 1w +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-search\-query (7) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-auth.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-auth.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-AUTH 1 "2010-06-09" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-auth \- Test authentication for a user +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " auth +[\fB\-a\fP \fIauth_socket_path\fP] +[\fB\-x\fP \fIauth_info\fP] +.I user +[\fIpassword\fP] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B auth +command can be used to test the authentication for the given +.IR user . +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.BI \-a\ auth_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/auth\-client . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------- +.TP +.BI \-x\ auth_info +.I auth_info +specifies additional conditions for the +.B auth +command. +The +.I auth_info +option string has to be given as +.IB name = value +pair. +For multiple conditions the +.B \-x +option could be supplied multiple times. +.br +Possible names for the +.I auth_info +are: +.RS +.TP +.B service +The service for which the authentication lookup should be tested. +The value may be the name of a service, commonly used with Dovecot. +For example: +.BR imap , +.BR pop3\ or +.BR smtp . +.TP +.B lip +The local IP address (server) for the test. +.TP +.B rip +The remote IP address (client) for the test. +.TP +.B lport +The local port, e.g. 143 +.TP +.B rport +The remote port, e.g. 24567 +.RE +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.\"------------------------------------- +.TP +.I user +The +.IR user \(aqs +login name. +Depending on the configuration, the login name may be for example +.BR jane " or " john@example.com . +.\"------------------------------------- +.TP +.I password +Optionally the user\(aqs password. +.BR doveadm (1) +will prompt for the password, if none was given. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example demonstrates an imap authentication test for user john, +assuming the user is connected from the host with the IP address +192.0.2.143. +.PP +.nf +.B doveadm auth \-x service=imap \-x rip=192.0.2.143 john johns_password +passdb: john auth succeeded +extra fields: + user=john +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveconf (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-director.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-director.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,181 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-DIRECTOR 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-director \- Manage Dovecot directors +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " "director add" +[\fB\-a\fP \fIdirector_socket_path\fP] +.IR host " [" vhost_count ] +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "director flush" +[\fB\-a\fP \fIdirector_socket_path\fP] +\fIhost\fP|\fBall\fP +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "director remove" +[\fB\-a\fP \fIdirector_socket_path\fP] +.I host +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "director status" +[\fB\-a\fP \fIdirector_socket_path\fP] +.RI [ user ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveadm director +can be used to manage and query the status of the list of backend mail +servers where Dovecot proxy can redirect connections to. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.BI \-a\ director_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/director\-admin . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I host +A mail server\(aqs hostname or IP address. +.\"------------------------------------- +.TP +.I user +Is a +.IR user \(aqs +login name. +Depending on the configuration, a login name may be for example +.BR jane " or " john@example.com . +.\"------------------------------------- +.TP +.I vhost_count +The number of \(dqvirtual hosts\(dq to assign to this server. The higher +the number is relative to other servers, the more connections it gets. The +default is 100. +.\"------------------------------------------------------------------------ +.SH COMMANDS +.SS director add +.B doveadm director add +[\fB\-a\fP \fIdirector_socket_path\fP] +.I host +.RI [ vhost_count ] +.PP +The command\(aqs tasks are: +.TP 4 +* +assign a new mail server to the director. +.TP +* +increase/decrease the +.I vhost_count +of an already assigned server. +.PP +.\"------------------------------------- +.SS director flush +.B doveadm director flush +[\fB\-a\fP \fIdirector_socket_path\fP] +\fIhost\fP|\fBall\fP +.PP +.B doveadm director flush +drops all user associations either from the given +.I host +or +.B all +hosts. +This command is intended mainly for testing purposes. +.\"------------------------------------- +.SS director remove +.B doveadm director remove +[\fB\-a\fP \fIdirector_socket_path\fP] +.I host +.PP +Use this command in oder to remove the given +.I host +from the director. +.\"------------------------------------- +.SS director status +.B doveadm director status +[\fB\-a\fP \fIdirector_socket_path\fP] +.RI [ user ] +.PP +This command is used to show the current usage of all assigned mail +servers. +.br +When a user name is given, this command shows which server the +.I user +is currently assigned to, where the user will be assigned after the current +saved assignment gets removed and where the user would be assigned to if +the whole proxy cluster was restarted fresh. +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @sysconfdir@/dovecot/conf.d/10\-director.conf +Director specific settings. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Add a director with vhost count 150 (or change existing one\(aqs +vhost count to 150): +.PP +.nf +.B doveadm \-v director add x1357.imap.ha.example.net 150 +2001:db8:543:6861:143::1357: OK +.fi +.\"------------------------------------- +.PP +Remove a director: +.PP +.nf +.B doveadm director remove x1357.imap.ha.example.net +.fi +.\"------------------------------------- +.PP +Query the status of mail hosts in a director: +.PP +.nf +.B doveadm director status +mail server ip vhosts users +192.168.10.1 100 125 +192.168.10.2 100 144 +192.168.10.3 100 115 +.fi +.\"------------------------------------- +.PP +Query the status of a user\(aqs assignment: +.PP +.nf +.B doveadm director status user@example.com +Current: 192.168.10.1 (expires 2010\-06\-18 20:17:04) +Hashed: 192.168.10.2 +Initial config: 192.168.10.3 +.fi +.PP +This means that the user is currently assigned to mail server on IP +192.168.10.1. After all of user\(aqs connections have logged out, the +assignment will be removed (currently it looks like at 20:17:04, but +that may be increased). After the assignment has expired, the user will +next time be redirected to 192.168.10.2 (assuming no changes to director +settings). If the entire Dovecot proxy cluster was restarted, so that all +of the director configuration would revert back to its initial values, the +user would be redirected to 192.168.10.3. +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-dump.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-dump.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,69 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-DUMP 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-dump \- Dump the content of Dovecot\(aqs binary mailbox index/log +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " dump " [" \-t +.IR type "] " path +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +Dovecot uses several binary index and log files in order to improve +performance for accessing mails. For some mailbox formats, such as dbox +and mdbox, the index files are part of the format itself. +For details about index files, see also: http://wiki.dovecot.org/IndexFiles +.PP +.B doveadm dump +is used to show the contents of those mailbox index/log files, in human +readable format. This is mainly useful for Dovecot developers when +debugging some problem. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.TP +.BI \-t\ type +the file type of the file to be dumped. +If the +.I type +was omitted, +.BR doveadm (1) +tries to detect the type of +.IR path . +.I type +can be: +.RS +.TP 12 +.B index +\(rA dovecot.index, dovecot.map.index +.TP +.B log +\(rA dovecot.index.log, dovecot.map.index.log +.TP +.B mailboxlog +\(rA dovecot.mailbox.log +.TP +.B thread +\(rA dovecot.index.thread +.RE +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I path +The path to the corresponding index or log file. If only a directory is +specified, doveadm tries to find and dump +.B index +type file under it. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Look at the contents of a mailbox\(aqs index: +.PP +.nf +.B doveadm dump ~/Maildir/.work/ +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-expunge.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-expunge.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-EXPUNGE 1 "2010-06-23" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-expunge \- Expunge messages matching given search query +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " expunge +.I search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] " "expunge \-A" +.I search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] " "expunge \-u" +.I user search_query +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +This command can be used to expunge mails matching the given search query. +It is typically used to expunge old mails from users\(aq Trash and/or Spam +mailboxes. To test which messages a given search query would match, you can +use +.I doveadm fetch +or +.I doveadm search +commands. +.PP +In the first form, +.BR doveadm (1) +will executed the +.B expunge +action with the environment of the logged in system user. +.PP +In the second form, the command will be performed for all users. +.PP +In the third form, only matching mails of the given +.IR user (s) +will be expunged. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I search_query +Expunge messages matching this search query. +See +.BR doveadm\-search\-query (7) +for details. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example expunges messages from Spam mailbox that were saved/copied +there more than two weeks ago: +.PP +.nf +.B doveadm expunge \-u jane.doe@example.org mailbox Spam savedbefore 2w +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-fetch (1), +.BR doveadm\-purge (1), +.BR doveadm\-search (1), +.BR doveadm\-search\-query (7) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-fetch.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-fetch.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,177 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-FETCH 1 "2010-06-26" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-fetch \- Fetch partial/full messages or message information +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.B fetch +.I fields search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.B fetch \-A +.I fields search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.B fetch \-u +.I user fields search_query +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveadm fetch +can be used to fetch messages\(aq contents and metadata. This can be useful +for scripts and for debugging. If you want to fetch messages one at a time, +see +.BR doveadm\-search (1). +.IP Important: +Please respect your users\(aq privacy. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\" --- command specific options --- "/. +.PP +This command uses by default the output formatter +.BR pager . +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I fields +One or more result field names to display, if the +.I search_query +matches any messages. +In order to specify multiple fields, enclose them in single or double +quotes. +.br +Supported +.I fields +are: +.RS +.TP +.B body +.\"----------------- +The body of a message. +.TP +.B date.received +Date and time of final delivery, when the message was delivered to a +user\(aqs mailbox for the first time. +.br +The internal date and time of the source message, when the message was +copied by the IMAP COPY command. +.br +The date\-time attribute when present, otherwise the current time, when the +message was saved by the IMAP APPEND command. +.\"----------------- +.TP +.B date.saved +Date and time when the message was saved to mailbox. +.\"----------------- +.TP +.B date.sent +Date and time of the message\(aqs Date: header. +.\"----------------- +.TP +.B flags +A message\(aqs IMAP flags, e.g. \(rsSeen +.\"----------------- +.TP +.B guid +A message\(aqs globally unique identifier. +.\"----------------- +.TP +.B hdr +The header of the message. +.\"----------------- +.TP +.B imap.body +IMAP BODY output of the message (see RFC 3501). +.\"----------------- +.TP +.B imap.bodystructure +IMAP BODYSTRUCTURE output of the message (see RFC 3501). +.\"----------------- +.TP +.B imap.envelope +IMAP ENVELOPE output of the message (see RFC 3501). +.\"----------------- +.TP +.B mailbox +Name of the mailbox, in which the message is stored. The name is in UTF\-8. +.\"----------------- +.TP +.B mailbox\-guid +The globally unique identifier of the mailbox, in which the message is +located. +.\"----------------- +.TP +.B seq +A message\(aqs sequence number in a mailbox. +.\"----------------- +.TP +.B size.physical +A message\(aqs physical size. +.\"----------------- +.TP +.B size.virtual +A message\(aqs virtual size, computed with CRLF line terminators. +.\"----------------- +.TP +.B text +The entire message (header and body). +.\"----------------- +.TP +.B uid +A message\(aqs unique (IMAP) identifier in a mailbox. +.\"----------------- +.TP +.B user +A message owner\(aqs login name. +.\"----------------- +.RE +.\"------------------------------------- +.TP +.I search_query +Fetch messages matching this search query. +See +.BR doveadm\-search\-query (7) +for details. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example based on the first example from +.BR doveadm\-search (1). +We are fetching the fields +.BR mailbox\ and\ date.sent +from user bob\(aqs mailbox with the guid +\(dq3a94c928d66ebe4bda04000015811c6a\(dq for the messages with the +UIDs +.BR 8 ,\ 25 \ and \ 45 . +.PP +.nf +.B doveadm fetch \-u bob \(dqmailbox date.sent\(dq \(rs +.B mailbox\-guid 3a94c928d66ebe4bda04000015811c6a uid 8,25,45 +mailbox: dovecot/pigeonhole/2.0 +date.sent: 2010\-01\-19 01:17:41 (+0100) +^L +mailbox: dovecot/pigeonhole/2.0 +date.sent: 2010\-01\-28 09:38:49 (+0100) +^L +mailbox: dovecot/pigeonhole/2.0 +date.sent: 2010\-03\-28 18:41:14 (+0200) +^L +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-search (1), +.BR doveadm\-search\-query (7) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-force-resync.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-force-resync.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,54 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-FORCE\-RESYNC 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-force\-resync \- Repair broken mailboxes +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " force\-resync +.I mailbox +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "force\-resync \-A" +.I mailbox +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "force\-resync \-u" +.I user mailbox +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +Under certain circumstances it may happen, that +.BR dovecot (1) +is unable to automatically solve problems with mailboxes. +In such situations the +.B force\-resync +command may be helpful. +It tries to fix all problems. +For dbox and mdbox mailboxes the storage files will be also checked. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I mailbox +The name of the mailbox to fix. With mdbox all of the mailboxes are fixed, +so you can use for example INBOX as the name. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Fix bob\(aqs INBOX: +.PP +.nf +.B doveadm force\-resync \-u bob INBOX +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-help.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-help.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,36 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-HELP 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-help \- Show information about doveadm commands +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " help +.RI [ command ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.br +With no +.I command +argument given, +.B doveadm help +will print: +.TP 4 +* +the synopsis for the most of the +.BR doveadm (1) +commands. +.TP +* +groups of commands, e.g. +.BR log " or " mailbox . +.PP +When the name of a +.I command +(or a group) was given, it will show the man page for that command. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-kick.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-kick.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-KICK 1 "2010-06-12" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-kick \- Disconnect users by user name and/or IP address +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " kick " [ \-a +.IR anvil_socket_path ] +.RB [ \-f ] +.I user +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " kick " [ \-a +.IR anvil_socket_path ] +.RB [ \-f ] +\fIip\fP[\fB/\fP\fImask\fP] +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " kick " [ \-a +.IR anvil_socket_path ] +.RB [ \-f ] +.I user +\fIip\fP[\fB/\fP\fImask\fP] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.BR doveadm \(aqs\ kick +command is used to disconnect users by +.I user +name and/or the +.I ip +address, from which they are connected. +.PP +In the first form, all users, whose login name matches the +.I user +argument, will be disconnected. +.PP +In the second form, all users, connected from the given IP address or +network range, will be disconnected. +.PP +In the last form, only users connected from the given IP address or +networks range and a matching login name will be disconnected. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.BI \-a\ anvil_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/anvil . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------- +.TP +.B \-f +Enforce the disconnect, even when there are multiple +.IR user s, +from different networks, connected to a single process. +This option may be only required when you have configured something like: +.sp +.nf +service imap { + ... + client_limit = \fI1+n\fP + service_count = 0 + ... +} +.fi +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.IR ip [/ mask ] +.I ip +or +.IB ip /\c +.I mask +is the host or network, from which the users are connected. +.\"------------------------------------- +.TP +.I user +Is a +.IR user \(aqs +login name. +Depending on the configuration, a login name may be for example +.BR jane " or " john@example.com . +It\(aqs also possible to use +.RB \(aq * \(aq +and +.RB \(aq ? \(aq +wildcards (e.g. \-u *@example.org). +.\"------------------------------------------------------------------------ +.SH EXAMPLE +If you don\(aqt want to disconnect all users at once, you can check +who\(aqs currently logged in. +The first example demonstrates how to disconnect all users whose login name +is 3 characters long and begins with +.BR ba . +.sp +.nf +.B doveadm who \-1 ja* +username proto pid ip +jane imap 8192 ::1 +james imap 8203 2001:db8:543:2::1 +.B doveadm kick ba? +kicked connections from the following users: +bar baz +.fi +.PP +The next example shows how to kick user foo\(aqs connections from 192.0.2.*. +.sp +.nf +.B doveadm who \-1 foo +username proto pid ip +foo imap 8135 fd95:4eed:38ba::25 +foo imap 9112 192.0.2.53 +foo imap 8216 192.0.2.111 +.B doveadm kick foo 192.0.2.0/24 +kicked connections from the following users: +foo +.B doveadm who f* +username # proto (pids) (ips) +foo 1 imap (8135) (fd95:4eed:38ba::25) +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-who (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-log.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-log.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-LOG 1 "2010-06-13" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-log \- Locate, test or reopen Dovecot\(aqs log files +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " "log find" +.RI [ directory ] +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "log reopen" +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "log test" +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B doveadm log +.I commands +are used to locate and reopen the log files of +.BR dovecot (1). +It\(aqs also possible to test the configured targets of the +.I *log_path +settings. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\"------------------------------------------------------------------------ +.SH COMMANDS +.SS log find +.B doveadm log find +.RI [ directory ] +.PP +The +.B log find +command is used to show the location of the log files, to which +.BR dovecot (1) +sends its log messages. +If +.BR dovecot (1) +logs its messages through +.BR syslogd (8) +and +.BR doveadm (1) +could not find any log files, you can specify the +.I directory +where your syslogd writes its log files. +.\"------------------------------------- +.SS log reopen +.B doveadm log reopen +.PP +This command causes +.B doveadm +to reopen all log files, configured in the +.IR log_path , +.I info_log_path +and +.I debug_log_path +settings. +These settings are configured in +.IR @sysconfdir@/dovecot/conf.d/10\-logging.conf . +.br +This is for example useful after manually rotating the log files. +.\"------------------------------------- +.SS log test +.B doveadm log test +.PP +This command causes +.B doveadm +to write the message \(dqThis is Dovecot\(aqs +.I priority +log +.RI ( timestamp )\(dq +to the configured log files. +The used priorities are: +.BR debug , +.BR info , +.BR warning , +.BR error +and +.BR fatal . +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example shows how to locate the log files used by +.BR dovecot (1). +.sp +.nf +.B doveadm log find +Looking for log files from /var/log +Debug: /var/log/dovecot.debug +Info: /var/log/mail.log +Warning: /var/log/mail.log +Error: /var/log/mail.log +Fatal: /var/log/mail.log +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-mailbox.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-mailbox.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,279 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-MAILBOX 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-mailbox \- Commands related to handling mailboxes +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter "] " mailbox_cmd " [" options "] [" arguments ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveadm mailbox +can be used to query and modify mailboxes. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I mailbox +Is the name of a +.IR mailbox , +as visible to IMAP clients, except in UTF\-8 format. The hierarchy +separator between a parent and child mailbox is commonly +.RB \(aq / \(aq +or +.RB \(aq . \(aq, +but this depends on your selected mailbox storage format and namespace +configuration. The mailbox names may also require a namespace prefix. +.\"------------------------------------------------------------------------ +.SH COMMANDS +.SS mailbox create +.B doveadm mailbox create +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.RB [ \-s ] +.IR mailbox\ ... +.PP +This command is used to create one or more mailboxes. +The mailbox format of the created mailboxes depends on the +.I mail_location +setting, or the user\(aqs +.I mail +field, returned by the userdb. +.PP +When the +.B \-s +option was given, the created mailboxes will be also added to the user\(aqs +subscriptions. +.\"------------------------------------------------------------------------ +.SS mailbox delete +.B doveadm mailbox delete +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.RB [ \-s ] +.IR mailbox\ ... +.PP +This command deletes a mailbox and expunges all the messages it contains. +If the mailbox has any children, they won\(aqt be deleted. +.br +When the +.B \-s +option is present, the deleted mailboxes will be also unsubscribed. +.\"------------------------------------------------------------------------ +.SS mailbox list +.B doveadm mailbox list +.RB [ \-7 | \-8 ] +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.RB [ \-s ] +[\fImailbox\fP ...] +.PP +To get an overview of existing mailboxes use this command. +It\(aqs also possible to use wildcards in the +.I mailbox +name. +.br +When the +.B \-s +option is present, only subscribed mailboxes will be listed. Listed +subscriptions may also contain mailboxes that are already deleted. +.PP +.\"------------------------------------- +.TP +.B \-7 +Lists the mailboxes with mUTF\-7 encoding. +.\"------------------------------------- +.TP +.B \-8 +Lists the mailboxes with UTF\-8 encoding. +.\"------------------------------------------------------------------------ +.SS mailbox mutf7 +.B doveadm mailbox mutf7 +.RB [ \-7 | \-8 ] +.IR name\ ... +.PP +The +.B mailbox mutf7 +command may be used to convert the international mailbox +.I name +into a modified version of the UTF\-7 encoding and vice versa. +See RFC 3501, section 5.1.3 (Mailbox International Naming Convention). +.PP +.\"------------------------------------- +.TP +.B \-7 +Indicates that the +.IR name \(aqs +string representation is mUTF\-7 encoded and it should be converted to +UTF\-8. +.\"------------------------------------- +.TP +.B \-8 +Indicates that the +.IR name \(aqs +is UTF\-8 encoded and should be converted to mUTF\-7 (default). +.TP +.I name +One or more mailbox names that should be converted. +.\"------------------------------------------------------------------------ +.SS mailbox rename +.B doveadm mailbox rename +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.RB [ \-s ] +.I old_name +.I new_name +.PP +The +.B mailbox rename +command is used to rename the mailbox +.I old_name +to +.IR new_name . +.br +When the +.B \-s +option is given, +.I old_name +will be unsubscribed +and +.I new_name +will be subscribed. +.\"------------------------------------------------------------------------ +.SS mailbox status +.BR doveadm " [" \-f +.IR formatter ] +.B mailbox status +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] [\fB\-t\fP] +.IR "fields mailbox\ " ... +.PP +Show the +.B status +of one or more mailboxes. +The +.I mailbox +name may also contain wildcards. +.br +This command uses by default the output +.I formatter +.BR flow . +.TP +.B \-t +Summarize the values of the status +.I fields +.BR messages , +.BR recent , +.BR unseen " and/or" +.B vsize +of multiple mailboxes to a sum (total). +.\"------------------------------------- +.TP +.I fields +Specify the status +.I fields +which should be shown. +In order to specify multiple status +.IR fields , +enclosed them in quotes. +.RS +.TP +.B all +This is a special status field name. +It means show all of the following +.IR fields . +When the +.B \-t +option is present, it means show only the +.BR messages , +.BR recent , +.BR unseen " and" +.B vsize +.IR fields . +.TP +.B guid +The +.IR mailbox \(aqs +globally unique identifier. +.TP +.B highestmodseq +The highest mod\-sequence value of all messages in the +.IR mailbox . +.TP +.B messages +The number of messages in the +.IR mailbox . +.TP +.B recent +The number of messages with the \(rsRecent flag set. +.TP +.B uidnext +The next unique identifier value. +.TP +.B uidvalidity +The unique identifier validity value. +.TP +.B unseen +The message sequence number of the first unseen message in the +.IR mailbox . +.TP +.B vsize +The +.IR mailbox \(aqs +virtual size, computed with CRLF line terminators. +.RE +.PP +.\"------------------------------------------------------------------------ +.SS mailbox subscribe +.B doveadm mailbox subscribe +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.IR mailbox\ ... +.PP +This command is used to subscribe one or more mailboxes. +.\"------------------------------------------------------------------------ +.SS mailbox unsubscribe +.B doveadm mailbox unsubscribe +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.IR mailbox\ ... +.PP +This command is used to unsubscribe one or more mailboxes. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +List subscribed mailboxes, beginning with \(aqdovecot\(aq, of user bob. +.sp +.nf +.B doveadm mailbox list \-s \-u bob dovecot* +dovecot +dovecot/pigeonhole +dovecot/pigeonhole/2.0 +.fi +.\"------------------------------------- +.PP +Now have a look at the status of user bob\(aqs dovecot mailboxes. +.sp +.nf +.B doveadm \-f table mailbox status \-u bob \(dqmessages vsize\(dq dovecot* +mailbox messages vsize +dovecot 20501 93968492 +dovecot/pigeonhole 0 0 +dovecot/pigeonhole/2.0 47 323474 +.fi +.\"------------------------------------- +.PP +Converting an internationalized mailbox name from mUTF\-7 to UTF\-8 and +vice versa. +.sp +.nf +.B doveadm mailbox mutf7 \-7 \(dq~peter/mail/&U,BTFw\-/&ZeVnLIqe\-\(dq +~peter/mail/台北/日本語 +.B doveadm mailbox mutf7 ~peter/mail/台北/日本語 +~peter/mail/&U,BTFw\-/&ZeVnLIqe\- +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-penalty.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-penalty.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-PENALTY 1 "2010-06-15" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-penalty \- Show current penalties +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " penalty " [" \-a +.IR anvil_socket_path ] +[\fIip\fP[\fB/\fP\fImask\fP]] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B doveadm penalty +command can be used to see the current penalties. +(Extend me!/explain it) +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.TP +.BI \-a\ anvil_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/anvil . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.IR ip [/ mask ] +To reduce/filter the output supply an IP address or a network range in +CIDR notation (ip/mask). +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Show current penalties +.sp +.nf +.B doveadm penalty +IP penalty last_penalty last_update +192.0.2.222 3 2010\-06\-15 15:19:27 15:19:27 +192.0.2.53 3 2010\-06\-15 15:19:34 15:19:34 +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-purge.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-purge.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-PURGE 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-purge \- Remove messages with refcount=0 from mdbox files +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " purge +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "purge \-A" +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " "purge \-u" +.I user +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B doveadm purge +command is used to remove all messages with refcount=0 from a user\(aqs +mail storage. +The refcount of a message is decreased to 0 when the user (or some +administration utility) has expunged all instances of a message from all +mailboxes. +.PP +In the first form, +.BR doveadm (1) +will perform the +.B purge +action for the currently logged in user. +.PP +In the second form, the command will be executed for all users +.PP +In the last form, only messages of the given +.IR user (s) +will be purged. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ + +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-expunge (1) +.PP +See http://wiki.dovecot.org/MailboxFormat/dbox#Multi\-dbox for some +details. diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-pw.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-pw.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,142 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-PW 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-pw \- Dovecot\(aqs password hash generator +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " "pw \-l" +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] " pw +[\fB\-p\fP \fIpassword\fP] +[\fB\-r\fP \fIrounds\fP] +[\fB\-s\fP \fIscheme\fP] +[\fB\-u\fP \fIuser\fP] +.RB [ \-V ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveadm pw +is used to generate password hashes for different password +.IR scheme s +and optionally verify the generated hash. +.PP +All generated password hashes have a +.RI { scheme } +prefix, for example +.RB { SHA512\-CRYPT.HEX }. +All passdbs have a default scheme for passwords stored without the +.RI { scheme } +prefix. +The default scheme can be overridden by storing the password with the +scheme prefix. +.PP +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.B \-l +List all supported password +.IR scheme s +and exit successfully. +.br +There are up to three optional password +.IR scheme s: +.BR BLF\-CRYPT " (Blowfish crypt)," +.BR SHA256\-CRYPT\ and +.BR SHA512\-CRYPT . +Their availability depends on the system\(aqs currently used libc. +.\"------------------------------------- +.TP +.BI \-p\ password +The plain text +.I password +for which the hash should be generated. +If no +.I password +was given +.BR doveadm (1) +will prompt interactively for one. +.\"------------------------------------- +.TP +.BI \-r\ rounds +The password +.IR scheme s +.BR BLF\-CRYPT , +.BR SHA256\-CRYPT\ and +.B SHA512\-CRYPT +supports a variable number of encryption +.IR rounds . +The following table shows the minimum/maximum number of encryption +.I rounds +per scheme. +When the +.B \-r +option was omitted the default number of encryption rounds will be applied. +.\" +.sp +.nf + Scheme | Minimum | Maximum | Default +---------------------------------------------- + BLF\-CRYPT | 4 | 31 | 5 + SHA256\-CRYPT | 1000 | 999999999 | 5000 + SHA512\-CRYPT | 1000 | 999999999 | 5000 +.fi +.\" +.\"------------------------------------- +.TP +.BI \-s\ scheme +The password +.I scheme +which should be used to generate the hashed password. +By default the +.BI CRAM\-MD5\ scheme +will be used. +It is also possible to append an encoding suffix to the +.IR scheme . +Supported encoding suffixes are: +.BR .b64 , +.BR .base64\ and +.BR .hex . +.br +See also http://wiki.dovecot.org/Authentication/PasswordSchemes for more +details about password schemes. +.\"------------------------------------- +.TP +.BI \-u\ user +When the +.BI DIGEST\-MD5\ scheme +is used, also the +.I user +name must be given, because the user name is a part of the generated hash. +For more information about Digest\-MD5 please read also: +http://wiki.dovecot.org/Authentication/Mechanisms/DigestMD5 +.\"------------------------------------- +.TP +.B \-V +When this option is given, the hashed password will be internally verified. +The result of the verification will be shown after the hashed password, +enclosed in parenthesis. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +The first password hash is a DIGEST\-MD5 hash for jane.roe@example.com. +The second password hash is a CRAM\-MD5 hash for john.doe@example.com. +.sp +.nf +.B doveadm pw \-s digest\-md5 \-u jane.roe@example.com +Enter new password: +Retype new password: +{DIGEST\-MD5}9b9dcb4466233a9307bbc33708dffda0 +.B doveadm pw +Enter new password: +Retype new password: +{CRAM\-MD5}913331d8782236a8ecba7764a63aa27b26437fd40ca878d887f11d81245c2c6b +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-quota.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-quota.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-QUOTA 1 "2010-06-23" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-quota \- Initialize/recalculate or show current quota usage +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.B quota +.I command +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.B quota +.IB command\ \-A +.\"------------------------------------- +.br +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.BI quota\ command\ \-u +.I user +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +In the first form, +.BR doveadm (1) +will execute the +.I command +for the currently logged in user. +.PP +In the second form, the +.I command +will be performed for all users. +.PP +In the third form, the +.I command +will affect only the matching +.IR user (s). +.IP Note: +The +.B quota get +and +.B quota recalc +commands are only available when the global +.I mail_plugins +setting contains the +.B quota +plugin. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH COMMANDS +.SS quota get +.BR doveadm " [" \-f +.IR formatter ] +.B quota get +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.PP +The +.B quota get +command is used to display the current quota usage. +.PP +This command uses by default the output formatter +.BR table . +.\"------------------------------------- +.SS quota recalc +.B doveadm quota recalc +[\fB\-A\fP|\fB\-u\fP \fIuser\fP] +.PP +The +.B quota recalc +command is used to recalculate the current quota usage. +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/dovecot.conf +Dovecot\(aqs main configuration file, including the +.I dict +section. +.TP +.I @sysconfdir@/dovecot/dovecot\-dict\-sql.conf.ext +SQL dictionary proxy settings. +.TP +.I @sysconfdir@/dovecot/conf.d/10\-mail.conf +Mailbox locations and namespaces, including global +.I mail_location +.TP +.I @sysconfdir@/dovecot/conf.d/90\-quota.conf +Quota configuration. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Get the current quota usage of user jane. +.sp +.nf +.B doveadm quota get \-u jane +Quota name Type Value Limit % +user STORAGE 90099 102400 87 +user MESSAGE 20548 30000 68 +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-reload.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-reload.1 Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,1 @@ +.so man1/doveadm.1 \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-search-query.7 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-search-query.7 Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,403 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-SEARCH\-QUERY 7 "2010-06-24" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-search\-query \- Overview of search queries for doveadm mailbox \ +commands +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +Several +.BR doveadm (1) +commands use a +.I search_query +in order to act only on matching messages. +This manual page describes all +.IR SEARCH\ KEYS , +which can be used in a +.IR search_query . +.PP +Each +.I search_query +consists at least of one +.IR SEARCH\ KEY . +Most of the +.I SEARCH KEYS +require an argument. +All +.I SEARCH\ KEYS +are case\-insensitive. +The shortest valid +.I search_query +is +.BR ALL . +For example: +.sp +.RS +.nf +doveadm search ALL +.fi +.RE +.PP +Multiple search query expressions will be combined with the +.B AND +operator by default. +To find all messages that are new and greater than 50 kilobyte, one can +use: +.sp +.RS +.nf +doveadm search NEW LARGER 50k +.fi +.RE +.PP +.BR OR \-ed +.I SEARCH KEYS +have to be written in parenthesis, when mixing ANDs and ORs. +Shells commonly require escaping for parentheses. +To find messages that were saved on the \(dq13th of April 2007\(dq AND +have the \(rsSeen and/or \(rsFlagged flag set, one +can use for example: +.sp +.RS +.nf +doveadm search SAVEDON 2007\-04\-13 \(rs( SEEN OR FLAGGED \(rs) +.fi +.RE +.PP +It\(aqs also possible to specify the mailbox, in which should be searched. +Use either the keyword +.B mailbox +and the name of the mailbox or the keyword +.B mailbox\-guid +and the mailbox\(aqs globally unique identifier at the beginning of the +.IR search_query . +To find all messages in the mailbox with the GUID +\(dq44f68b13ce97044b837f000035ca9452\(dq use: +.sp +.RS +.nf +doveadm search mailbox\-guid 44f68b13ce97044b837f000035ca9452 ALL +.fi +.RE +.PP +To list all deleted messages in the \(dqTrash\(dq folder use: +.sp +.RS +.nf +doveadm search mailbox Trash DELETED +.fi +.RE +.\"------------------------------------------------------------------------ +.SH SEARCH KEYS +The following search keys from the specification of IMAP version 4 revision +1 (see: RFC 3501, section 6.4.4) are supported: +.\"----------------- +.TP +.B ALL +Matches all messages. +.\"----------------- +.TP +.B ANSWERED +Matches messages with the IMAP flag \(rsAnswered set. +.\"----------------- +.TP +.BI BCC\ pattern +Matches messages, which contain +.I pattern +in the BCC field of the message\(aqs IMAP envelope structure. +.\"----------------- +.TP +.BI BEFORE \ date\ specification +Matches messages with an internal date before +.IR date\ specification . +.\"----------------- +.TP +.BI BODY\ pattern +Matches messages, which contain +.I pattern +in the body part. +.\"----------------- +.TP +.BI CC\ pattern +Matches messages, which contain +.I pattern +in the CC field of the message\(aqs IMAP envelope structure. +.\"----------------- +.TP +.B DELETED +Matches messages with the IMAP flag \(rsDeleted set. +.\"----------------- +.TP +.B DRAFT +Matches messages with the IMAP flag \(rsDraft set. +.\"----------------- +.TP +.B FLAGGED +Matches messages with the IMAP flag \(rsFlagged set. +.\"----------------- +.TP +.BI FROM\ pattern +Matches messages, which contain +.I pattern +in the FROM field of the message\(aqs IMAP envelope structure. +.\"----------------- +.TP +\fBHEADER\fP \fIfield\fP [\fIpattern\fP] +Matches messages, which either have the named header +.IR field , +when no +.I pattern +was given. +Or messages, where the given header +.IR field \(aqs +value contains the specified +.IR pattern . +.\"----------------- +.TP +.BI KEYWORD\ keyword +Matches messages with the given IMAP +.I keyword +(e.g. \(DoForwarded) flag set. +.\"----------------- +.TP +.BI LARGER\ size +Matches messages that are larger than the specified +.IR size . +.\"----------------- +.TP +.B NEW +Matches messages, which have the IMAP flag \(rsRecent set +.B but not +the IMAP flag \(rsSeen. +.\"----------------- +.TP +.BI NOT\ search\ key +Inverse matching \- matches massages, where the search doesn\(aqt match +the specified +.I search\ key +or its value. +.\"----------------- +.TP +.B OLD +Matches messages, which do not have the IMAP flag \(rsRecent set. +.\"----------------- +.TP +.BI ON\ date\ specification +Matches messages whose internal date matches the given +.IR date\ specification . +.\"----------------- +.TP +.IB search\ key\ OR\ search\ key +Matches messages where one of the OR\-ed search keys matches. +.br +Note: IMAP4rev1 uses the syntax: +.BI OR\ search\ key\ search\ key +.\"----------------- +.TP +.B RECENT +Matches messages with the IMAP flag \(rsRecent set. +.\"----------------- +.TP +.B SEEN +Matches messages with the IMAP flag \(rsSeen set. +.\"----------------- +.TP +.BI SENTBEFORE\ date\ specification +Matches messages with a Date: header before +.IR date\ specification . +.\"----------------- +.TP +.BI SENTON\ date\ specification +Matches messages with a Date: header matching the given +.IR date\ specification . +.\"----------------- +.TP +.BI SENTSINCE\ date\ specification +Matches messages with a Date: header matching or after the given +.IR date\ specification . +.\"----------------- +.TP +.BI SINCE\ date\ specification +Matches messages whose internal date is within or after the given +.IR date\ specification . +.\"----------------- +.TP +.BI SMALLER\ size +Matches messages with a size smaller than the given +.IR size . +.\"----------------- +.TP +.BI SUBJECT\ pattern +Matches messages, which contain +.I pattern +in the SUBJECT field of the message\(aqs IMAP envelope structure. +.\"----------------- +.TP +.BI TEXT\ pattern +Matches messages, which contain +.I pattern +in the message body. +.\"----------------- +.TP +.BI TO\ pattern +Matches messages, which contain +.I pattern +in the TO field of the message\(aqs IMAP envelope structure. +.\"----------------- +.TP +.BI UID\ sequence +Matches messages with the given UID(s). +A +.I sequence +may be a single UID. +Can be a sequence range, written as +.IR from : to , +.RB e.g.\ 100 : 125 . +As comma separated list of UIDs, e.g. +.BR 11,50,4 . +It\(aqs also possible to combine multiple sequences, e.g. +.BR 1,3,5,7,10:20 . +.\"----------------- +.TP +.B UNANSWERED +Matches messages, which do not have the IMAP flag \(rsAnswered set. +.\"----------------- +.TP +.B UNDELETED +Matches messages, which do not have the IMAP flag \(rsDeleted set. +.\"----------------- +.TP +.B UNDRAFT +Matches messages, which do not have the IMAP flag \(rsDraft set. +.\"----------------- +.TP +.B UNFLAGGED +Matches messages, which do not have the IMAP flag \(rsFlagged set. +.\"----------------- +.TP +.BI UNKEYWORD\ keyword +Matches messages, which do not have the given IMAP +.I keyword +flag set +.\"----------------- +.TP +.B UNSEEN +Matches messages, which do not have the IMAP flag \(rsSeen set. +.\"------------------------------------- +.SS DOVEADM SEARCH KEYS +Additional search keys, provided by +.BR doveadm (1). +.\"----------------- +.TP +.BI SAVEDBEFORE\ date\ specification +Matches messages, which were saved before +.IR date\ specification . +.\"----------------- +.TP +.BI SAVEDON\ date\ specification +Matches messages whose save date matches the given +.IR date\ specification . +.\"----------------- +.TP +.BI SAVEDSINCE\ date\ specification +Matches messages with a save date matching or after the given +.IR date\ specification . +.\"------------------------------------------------------------------------ +.SH DATE SPECIFICATION +.BR doveadm (1) +supports a few additional +.I date specification +formats. +They can be used anywhere, where a +.I date specification +value is obligatory. +.TP +.IB day \- month \- year +Default IMAP4rev1 date format. +.br +.IR day , +the day of month: +.BR 1 \- 31 . +.br +.IR month , +the abbreviated month name: +.BR Jan , +.BR Feb , +.BR Mar , +.BR Apr , +.BR May , +.BR Jun , +.BR Jul , +.BR Aug , +.BR Sep , +.BR Oct , +.BR Nov \ or +.BR Dec . +.br +.IR year , +four digits of year, e.g. +.BR 2007 . +.br +For example the \(dq13th of April 2007\(dq will be represented as +.BR 13\-Apr\-2007 . +. +.TP +.I interval +Combination of a positive integer +.I number +and a +.IR time\ unit . +.br +Available +.I time\ units +are: +.BR weeks " (abbr: " w ), +.BR days " (abbr: " d ), +.BR hours " (abbr: " h ), +.BR mins " (abbr: " m ") and" +.BR secs " (abbr: " s ). +.br +To match messages from last week, you may specify for example: +.BR since\ 1w , +.BR since\ 1weeks \ or +.BR since\ 7days . +. +.TP +.I Unix timestamp +A 10 digit Unix timestamp, seconds since the 1st of January 1970, 00:00:00 +UTC. +For example the \(dq13th of April 2007\(dq will be represented as +.BR 1176418800 . +. +.TP +.I YYYY\-MM\-DD +Extended ISO\-8601 calendar date format. +For example the \(dq13th of April 2007\(dq will be represented as +.BR 2007\-04\-13 . +.\"------------------------------------------------------------------------ +.SH SIZE +.BR doveadm (1) +provides also an additional +.I size +representation format. +The following formats can be used anywhere, where a +.I size +value is obligatory. +.TP +.I octets +The message size in octets, as specified in the IMAP4rev1 specification. +.TP +.I size +The message size in +.BR B \ (byte), +.BR k \ (kilobyte), +.BR M \ (megabyte), +.BR G \ (gigabyte)\ or +.BR T \ (terabyte). +.br +To match messages, bigger than 1 megabyte, you may specify for example: +.BR larger\ 1M \ or +.BR larger\ 1024k . +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-search (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-search.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-search.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-SEARCH 1 "2010-06-26" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-search \- Show a list of mailbox GUIDs and message UIDs matching \ +given search query. +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.BI search\ search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.BI "search \-A " search_query +.br +.\"------------------------------------- +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.BI "search \-u " "user search_query" +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B search +command is used to find matching messages. +.BR doveadm (1) +will print the mailbox\(aqs guid and the message\(aqs uid for each match. +.br +When used with the +.B \-A +or +.BI \-u \ wildcard +options, +.BR doveadm (1) +will print the fields +.BR username , +.BR mailbox\-guid \ and +.B uid +for each matching message. +.PP +In the first form, +.BR doveadm (1) +will executed the +.B search +action with the environment of the logged in system user. +.PP +In the second form, the command will be performed for all users. +.PP +In the third form, only matching mails of the given +.IR user (s) +will be searched. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\" --- command specific options --- "/. +.PP +This command uses by default the output formatter +.B flow +(without the +.IR key = +prefix). +.PP +Command specific +.IR options : +.\"------------------------------------- +@INCLUDE:option-A@ +.\"------------------------------------- +@INCLUDE:option-u-user@ +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I search_query +Show messages matching this search query. +See +.BR doveadm\-search\-query (7) +for details. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +This example demonstrates how to search in user bob\(aqs dovecot mailboxes +all messages, which contains the word \(dqtodo\(dq in the Subject: header. +.PP +.nf +.B doveadm search \-u bob mailbox dovecot\(rs* subject todo +3a94c928d66ebe4bda04000015811c6a 8 +3a94c928d66ebe4bda04000015811c6a 25 +3a94c928d66ebe4bda04000015811c6a 45 +.fi +.PP +The search command is mainly useful when used together with +.I doveadm\ fetch +command. For example to save message bodies of all messages from INBOX +that have "todo" in subject, use: +.PP +.nf +.B doveadm search \-u bob mailbox INBOX subject todo | +.B while read guid uid; do +.B \ \ doveadm fetch \-u bob body mailbox\-guid $guid uid $uid > msg.$uid +.B done +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-fetch (1), +.BR doveadm\-search\-query (7) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-stop.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-stop.1 Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,1 @@ +.so man1/doveadm.1 \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-user.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-user.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-USER 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-user \- Perform a user lookup in Dovecot\(aqs userdbs +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] " user +[\fB\-a\fP \fIuserdb_socket_path\fP] +[\fB\-x\fP \fIauth_info\fP] +.IR user\ ... +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B user +command is used to perform a user lookup \- to show what information +Dovecot sees about the +.IR user (s), +or if it exists at all in the configured +.IR userdb (s). +.PP +The +.I auth_info +may be useful when the userdb is for example a SQL database and you are +using %variables, like +.B %s +or +.BR %l , +in the +.I user_query +setting. +Or when you have configured the userdb in a way like this: +.sp +.nf +userdb { + driver = passwd\-file + args = /etc/%s.passwd +} +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:global-options@ +.\" --- command specific options --- "/. +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.BI \-a\ userdb_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/auth\-userdb . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------- +.TP +.BI \-x\ auth_info +.I auth_info +specifies additional conditions for the +.B user +command. +The +.I auth_info +option string has to be given as +.IB name = value +pair. +For multiple conditions the +.B \-x +option could be supplied multiple times. +.br +Possible names for the +.I auth_info +are: +.RS +.TP +.B service +The service for which the userdb lookup should be tested. +The value may be the name of a service, commonly used with Dovecot. +For example: +.BR imap , +.BR pop3\ or +.BR smtp . +.TP +.B lip +The local IP address (server) for the test. +.TP +.B rip +The remote IP address (client) for the test. +.TP +.B lport +The local port, e.g. 143 +.TP +.B rport +The remote port, e.g. 24567 +.RE +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I user +Is a +.IR user \(aqs +login name. +Depending on the configuration, a login name may be for example +.BR jane " or " john@example.com . +It\(aqs also possible to use +.RB \(aq * \(aq +and +.RB \(aq ? \(aq +wildcards (e.g. \-u *@example.org). +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Perform a user lookup for the users jane and john@example.com. +.sp +.nf +.B doveadm user jane john@example.com +userdb: jane + uid : 8001 + gid : 8001 + home : /home/jane + mail : dbox:~/dbox + plugins : sieve + quota_rule: *:storage=150M + +userdb: john@example.com + home : /srv/mail/8/70312/79832 + uid : 79832 + gid : 70312 + mail : mdbox:~/mdbox +.fi +.PP +The next example shows a user lookup, using wildcards. +.sp +.nf +.B doveadm user *.?oe@example.net +jane.doe@example.net +judy.roe@example.net +john.doe@example.net +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm-who.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm-who.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM\-WHO 1 "2010-06-23" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm\-who \- Show who is logged in to the Dovecot server +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.BR who\ [ \-1 ] +[\fB\-a\fP \fIanvil_socket_path\fP] +.RI [ user ] +[\fIip\fP[\fB/\fP\fImask\fP]] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B who +command is used to show which users from which hosts are currently +connected to which service. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\" --- command specific options --- "/. +.PP +This command uses by default the output formatter +.BR table . +.PP +Command specific +.IR options : +.\"------------------------------------- +.TP +.B \-1 +Print one line per user and connection. +Otherwise the connections are grouped by the username. +.\"------------------------------------- +.TP +.BI \-a\ anvil_socket_path +This option is used to specify an absolute path to an alternative UNIX +domain socket. +.sp +By default +.BR doveadm (1) +will use the socket +.IR @rundir@/anvil . +The socket may be located in another directory, when the default +.I base_dir +setting was overridden in +.IR @sysconfdir@/dovecot/dovecot.conf . +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +\fIip\fP[\fB/\fP\fImask\fP] +Specify an +.I ip +address or network range, in CIDR notation, to reduce the result to +matching connections. +.\"------------------------------------- +.TP +.I user +List only users, whose name match +.IR user . +It\(aqs also possible to use wildcards in the +.I user +name. +.\"------------------------------------------------------------------------ +.SH EXAMPLE +Show authenticated sessions, filtered by the client\(aqs IP address. +.sp +.nf +.B doveadm who ::1 +username # proto (pids) (ips) +jane 2 imap (30155 30412) (::1) +.B doveadm who 192.0.2.0/24 +username # proto (pids) (ips) +john@example.com 1 imap (30257) (192.0.2.34) +.fi +.PP +Show authenticated sessions, filtered by username. +.sp +.nf +.B doveadm who pvo +username # proto (pids) (ips) +pvo 1 sieve (30343) (fd95:4eed:38ba::25) +pvo 4 imap (25693 25686 25679 25669) (fd95:4eed:38ba::25) +.B doveadm who ja* +username # proto (pids) (ips) +james 1 imap (30091) (127.0.0.1) +jane 2 imap (30155 30412) (::1) +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveadm\-kick (1) \ No newline at end of file diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveadm.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveadm.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,169 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVEADM 1 "2010-06-24" "Dovecot v2.0" "Dovecot" +.SH NAME +doveadm \- Dovecot\(aqs administration utility +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.BR doveadm " [" \-Dv "] [" \-f +.IR formatter ] +.IR command " [" command_options "] [" command_arguments ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveadm +is the Dovecot administration tool. It can be used to manage various parts +of Dovecot, as well as access users\(aq mailboxes. +.br +Execute +.BR doveadm\ help , +for a command usage listing. +.\"------------------------------------------------------------------------ +@INCLUDE:global-options-formatter@ +.\"------------------------------------------------------------------------ +.SH COMMANDS +.\"------------------------------------------------------------------------ +This commands works directly with Dovecot\(aqs master process. +.\"------------------------------------- +.SS reload +.B doveadm reload +.PP +Force +.BR dovecot (1) +to reload the configuration. +.\"------------------------------------------------------------------------ +.SS stop +.B doveadm stop +.PP +Stop +.BR dovecot (1) +and all its child processes. +.\"------------------------------------------------------------------------ +.SS ADDITIONAL MASTER COMMANDS +.TP +.B doveadm director +.BR doveadm\-director (1), +Manage Dovecot directors (if used by proxy servers). +.\"------------------------------------- +.TP +.B doveadm kick +.BR doveadm\-kick (1), +Disconnect users by user name and/or IP address. +.\"------------------------------------- +.TP +.B doveadm log +.BR doveadm\-log (1), +Locate, test or reopen Dovecot\(aqs log files. +.\"------------------------------------- +.TP +.B doveadm penalty +.BR doveadm\-penalty (1), +Show current penalties. +.\"------------------------------------- +.TP +.B doveadm who +.BR doveadm\-who (1); +Show who is logged in to the Dovecot server. +.\"------------------------------------------------------------------------ +.SS AUTHENTICATION COMMANDS +.\"------------------------------------- +.TP +.B doveadm auth +.BR doveadm\-auth (1), +Test authentication for a user. +.\"------------------------------------- +.TP +.B doveadm pw +.BR doveadm\-pw (1), +Dovecot\(aqs password hash generator. +.\"------------------------------------- +.TP +.B doveadm user +.BR doveadm\-user (1), +Perform a user lookup in Dovecot\(aqs userdbs +.\"------------------------------------------------------------------------ +.SS MAILBOX COMMANDS +.TP +.B doveadm altmove +.BR doveadm\-altmove (1), +Move matching mails to the alternative storage. +.\"------------------------------------- +.TP +.B doveadm dump +.BR doveadm\-dump (1), +Dump the content of Dovecot\(aqs binary mailbox index/log. +.\"------------------------------------- +.TP +.B doveadm expunge +.BR doveadm\-expunge (1), +Expunge messages matching given search query. +.\"------------------------------------- +.TP +.B doveadm fetch +.BR doveadm\-fetch (1), +Fetch messages matching given search query. +.\"------------------------------------- +.TP +.B doveadm force\-resync +.BR doveadm\-force\-resync (1), +Repair broken mailboxes, in case Dovecot doesn\(aqt automatically do that. +.\"------------------------------------- +.TP +.B doveadm mailbox +.BR doveadm\-mailbox (1), +Various commands related to handling mailboxes. +.\"------------------------------------- +.TP +.B doveadm purge +.BR doveadm\-purge (1) +Remove messages with refcount=0 from mdbox files. +.\"------------------------------------- +.TP +.B doveadm quota +.BR doveadm\-quota (1), +Initialize/recalculate or show current quota usage. +.\"------------------------------------- +.TP +.B doveadm search +.BR doveadm\-search (1), +Show a list of mailbox GUIDs and message UIDs matching given search query. +.\"------------------------------------------------------------------------ +.SH "EXIT STATUS" +.B doveadm +will exit with one of the following values: +.TP 4 +.B 0 +Selected command was executed successful. +.TP +.B 1 +(doveadm || userdb lookup no perms) +.TP +.B 89 +Command failed in some way. +.\"------------------------------------------------------------------------ +.SH ENVIRONMENT +.TP +.B USER +This environment variable is used to determine the +.I user +if a command accepts a +.I user +but none was specified. +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @sysconfdir@/dovecot/conf.d/10\-mail.conf +Mailbox locations and namespaces. +.TP +.I @sysconfdir@/dovecot/conf.d/90\-plugin.conf +Plugin specific settings. +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm\-help (1), +.BR doveconf (1), +.BR dovecot (1), +.BR dsync (1), +.BR doveadm\-search\-query (7) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/doveconf.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/doveconf.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,180 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVECONF 1 "2010-06-26" "Dovecot v2.0" "Dovecot" +.SH NAME +doveconf \- Dovecot\(aqs configuration dumping utility +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.B doveconf +.RB [ \-anNx ] +[\fB\-c\fP \fIconfig\-file\fP] +[\fB\-f\fP \fIfilter\fP] +[\fB\-m\fP \fImodule\fP] +.\"------------------------------------- +.br +.B doveconf +.RB [ \-n ] +[\fB\-c\fP \fIconfig\-file\fP] +.IR section_name \ ... +.\"------------------------------------- +.br +.B doveconf +.RB [ \-h ] +[\fB\-c\fP \fIconfig\-file\fP] +[\fB\-f\fP \fIfilter\fP] +.IR setting_name \ ... +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B doveconf +reads and parses Dovecot\(aqs configuration files and converts them into a +simpler format used by the rest of Dovecot. All standalone programs, such +as +.BR dovecot (1) +and +.BR dovecot\-lda (1), +will first get their settings by executing doveconf. +.PP +For system administrators, +.B doveconf +is mainly useful for dumping the configuration in easy human readable +output. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.TP +.B \-a +Show all settings with their currently configured values. +.\"--------------------------------- +.TP +.BI \-c \ config\-file +read configuration from the given +.IR config\-file . +By default +.I @sysconfdir@/dovecot/dovecot.conf +will be used. +.\"--------------------------------- +.TP +.BI \-f \ filter +Show the matching configuration for the specified +.I filter +condition. +The +.I filter +option string has to be given as +.IB name = value +pair. +For multiple filter conditions the +.B \-f +option can be supplied multiple times. +.br +Possible names for the +.I filter +are: +.RS +.TP +.B lname +The local hostname, e.g. mail.example.com. +This will only match hostnames which were configured like: +.br +.B local_name mail.example.com { # special settings } +.TP +.B local +The server\(aqs hostname or IP address. +This will also match hostnames which were configured like: +.br +.B local imap.example.net { # special settings } +.TP +.B protocol, service +The protocol, e.g. imap or pop3 +.TP +.B remote +The client\(aqs hostname or IP address. +.RE +.\"--------------------------------- +.TP +.B \-h +Hide the setting\(aqs name, show only the setting\(aqs value. +.\"--------------------------------- +.TP +.BI \-m\ module +Show only settings for the given +.IR module . +.RS +e.g. +.BR imap , +.BR imap\-login , +.BR lmtp , +.BR pop3\ or +.B pop3\-login +.RE +.\"--------------------------------- +.TP +.B \-n +Show only settings with non\-default values. +.\"--------------------------------- +.TP +.B \-N +Show settings with non\-default values and explicitly set default values. +.\"--------------------------------- +.TP +.B \-x +Expand configuration variables (e.g. \(Domail_plugins \(rA quota) and show +file contents (from e.g. ssl_cert = \ +@sysconfdir@/dovecot/dovecot.conf.new +.fi +.\"------------------------------------- +.PP +This example shows how to ask +.B doveconf +for a global setting and a protocol specific setting. +The second command uses also the +.B \-h +option, in order to hide the setting\(aqs name. +.sp +.nf +.B doveconf mail_plugins +mail_plugins = quota +.B doveconf \-h \-f protocol=imap mail_plugins +quota imap_quota +.fi +.\"------------------------------------- +.PP +This example demonstrates how to dump a whole configuration section. +.sp +.nf +.B doveconf dict +dict { + quota = pgsql:@sysconfdir@/dovecot/dovecot\-dict\-sql.conf.ext +} +.fi +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR dovecot (1), +.BR dovecot\-lda (1), +.BR dsync (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/dovecot-lda.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/dovecot-lda.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,153 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVECOT\-LDA 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +dovecot\-lda \- Dovecot\(aqs local mail delivery agent +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.B dovecot\-lda +.RB [ \-ek ] +[\fB\-a\fP \fIaddress\fP] +[\fB\-c\fP \fIconfig_file\fP] +[\fB\-d\fP \fIusername\fP] +[\fB\-f\fP \fIenvelope_sender\fP] +[\fB\-m\fP \fImailbox\fP] +[\fB\-p\fP \fIpath\fP] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +The +.B dovecot\-lda +is a local mail delivery agent which takes mail from an MTA and delivers +it to a user\(aqs mailbox, while keeping Dovecot index files up to date. +.PP +Main features of the +.B dovecot\-lda +are: +.TP 4 +* +Mailbox indexing during mail delivery, providing faster mailbox access +later +.TP +* +Quota enforcing by the quota plugin +.TP +* +Sieve language support by the Pigeonhole sieve plugin +.\"------------------------------------------------------------------------ +.SH OPTIONS +Options accepted by +.BR dovecot\-lda : +.\"------------------------------------- +.TP +.BI \-a\ address +Destination address (e.g. user+ext@domain). Default is the same as +.IR username . +.\"------------------------------------- +.TP +.BI \-c\ config_file +Alternative configuration file path. +.\"------------------------------------- +.TP +.BI \-d\ username +Destination +.IR username . +If given, the user information is looked up from userdb. +Typically used with virtual users, but not necessarily with system users. +.\"------------------------------------- +.TP +.B \-e +If mail gets rejected, write the rejection reason to stderr and exit with +status 77 (EX_NOPERM). +The default is to send a rejection mail ourself. +.\"------------------------------------- +.TP +.BI \-f\ envelope_sender +Envelope sender address. +.\"------------------------------------- +.TP +.B \-k +Don\(aqt clear all environment at startup. +.\"------------------------------------- +.TP +.BI \-m\ mailbox +Destination mailbox (default is +.BR INBOX ). +If the mailbox doesn\(aqt exist, it will not be created (unless the +.I lda_mailbox_autocreate +setting is set to +.BR yes ). +If a message couldn\(aqt be saved to the +.I mailbox +for any reason, it\(aqs delivered to +.B INBOX +instead. +.\"------------------------------------- +.TP +.BI \-p\ path +Path to the mail to be delivered instead of reading from stdin. +If using maildir the file is hard linked to the destination if possible. +This allows a single mail to be delivered to multiple users using hard +links, but currently it also prevents deliver from updating cache file so +it shouldn\(aqt be used unless really necessary. +.\"------------------------------------------------------------------------ +.SH "EXIT STATUS" +.B dovecot\-lda +will exit with one of the following values: +.TP 4 +.B 0 +Delivery was successful. (EX_OK) +.TP +.B 64 +Invalid parameter given. (EX_USAGE) +.TP +.B 77 +.B \-e +option was used and mail was rejected. +Typically this happens when user is over quota and +.B quota_full_tempfail = no +is configured. (EX_NOPERM) +.TP +.B 75 +A temporary failure. This is returned for almost all failures. See the log +file for details. (EX_TEMPFAIL) +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @sysconfdir@/dovecot/conf.d/10\-mail.conf +Mailbox locations and namespaces. +.TP +.I @sysconfdir@/dovecot/conf.d/15\-lda.conf +LDA specific settings. +.TP +.I @sysconfdir@/dovecot/conf.d/90\-plugin.conf +Plugin specific settings. +.TP +.I @sysconfdir@/dovecot/conf.d/90\-quota.conf +Quota configuration. +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR dovecot (1), +.BR doveconf (1), +.BR dsync (1) +.PP +Related MTA specific documentation: +.\"------------------------------------- +.TP +Postfix: +.BR postconf (5), +.BR transport (5), +.BR pipe (8) +.\"------------------------------------- +.PP +Exim: +.IP "The accept router" +http://exim.org/exim\-html\-current/doc/html/spec_html/ch16.html +.IP "Generic options for transports" +http://exim.org/exim\-html\-current/doc/html/spec_html/ch24.html +.IP "The pipe transport" +http://exim.org/exim\-html\-current/doc/html/spec_html/ch29.html diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/dovecot.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/dovecot.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,152 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DOVECOT 1 "2010-06-01" "Dovecot v2.0" "Dovecot" +.SH NAME +dovecot \- a secure and highly configurable IMAP and POP3 server +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +\fBdovecot\fP [\fB\-Fp\fP] [\fB\-c\fP \fIconfig\-file\fP] +.br +.B dovecot \-a +[\fB\-c\fP \fIconfig\-file\fP] +.br +.B dovecot \-n +[\fB\-c\fP \fIconfig\-file\fP] +.br +.B dovecot \-\-build\-options +.br +.B dovecot \-\-help +.br +.B dovecot \-\-version +.br +.B dovecot reload +.br +.B dovecot stop +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +Dovecot is an open source IMAP and POP3 server for Linux/UNIX\-like +systems, written with security primarily in mind. +Dovecot is an excellent choice for both small and large installations. +It\(aqs fast, simple to set up, requires no special administration and it +uses very little memory. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.TP +.B \-a +Dump all configuration settings to stdout and exit successfully. +The same as +.IR doveconf\ \-a . +.TP +.BI \-c\ config\-file +Start +.B dovecot +with an alternative configuration. +.TP +.B \-F +Run +.B dovecot +in foreground, do not daemonize. +.TP +.B \-n +Dump non\-default settings to stdout and exit successfully. +The same as +.IR doveconf\ \-n . +.TP +.B \-p +Prompt for the ssl key password for the configured +.I ssl_key +on startup. +.TP +.B \-\-build\-options +Show Dovecot\(aqs build options and exit successfully. +.TP +.B \-\-help +Print a usage message to stdout and exit successfully. +.TP +.B \-\-version +Show Dovecot\(aqs version and exit successfully. +.\"------------------------------------------------------------------------ +.SH COMMANDS +.TP +.B reload +Force +.B dovecot +to reload its configuration. +.TP +.B stop +Shutdown +.B dovecot +and all its child processes. +.PP +When +.I shutdown_clients +is set to +.BR no , +existing sessions will continue to use the old settings, after a +.BR "dovecot reload" . +Also all sessions will keep alive after a +.BR "dovecot stop" . +.br +By default all active sessions will be shut down. +.\"------------------------------------------------------------------------ +.SH SIGNALS +Dovecot handles the following +.I signals +as described: +.TP +.B HUP +Force +.B dovecot +to reload its configuration. +.TP +.B INT +Shutdown +.B dovecot +and all its child processes. +.TP +.B TERM +Shutdown +.B dovecot +and all its child processes. +.TP +.B USR1 +Force +.B dovecot +to reopen all configured log files (\c +.IR log_path , +.IR info_log_path\ and +.IR debug_log_path ). +. +.PP +The +.I signals +.BR ALARM\ and +.B PIPE +are ignored. +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @sysconfdir@/dovecot/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @sysconfdir@/dovecot/dovecot\-ldap.conf.ext +Dovecot\(aqs LDAP authdb/userdb module configuration file. +.TP +.I @sysconfdir@/dovecot/dovecot\-sql.conf.ext +Dovecot\(aqs SQL authdb/userdb module configuration file. +.TP +.I @sysconfdir@/dovecot/dovecot\-dict\-sql.conf.ext +Dovecot\(aqs dict configuration with SQL\-backend. +.TP +.I @sysconfdir@/dovecot/conf.d/auth\-*\-conf.ext +Configuration files of different authentication modules. +.TP +.I @sysconfdir@/dovecot/conf.d/*.conf +Configuration files of different services and settings. +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveconf (1), +.BR dovecot\-lda (1), +.BR dsync (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/dsync.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/dsync.1.in Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,176 @@ +.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file +.TH DSYNC 1 "2010-06-22" "Dovecot v2.0" "Dovecot" +.SH NAME +dsync \- Dovecot\(aqs synchronization utility +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +\fBdsync\fP [\fB\-Dfrv\fP] [\fB\-C\fP \fIalt_char\fP] +[\fB\-m\fP \fImailbox\fP] [\fB\-o\fP \fIsetting\fP=\fIvalue\fP ...] +[\fB\-u\fP \fIuser\fP] \fIcommand\fP +\fIcommand_arguments\fP +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.B dsync +is Dovecot\(aqs synchronization utility. +It can be used for several different use cases: +Two\-way synchronization of mailboxes in different servers (via +.BR ssh (1)), +creating backups of mails to a remote server, and convert mailboxes +from/to different mailbox formats. +.PP +Any errors are written to stderr. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.B dsync +recognizes the following command line options: +.TP +.BI \-C\ alt_char +Specifies an alternative mailbox name character. +If source and destination mailbox formats are different, it\(aqs possible +that on one side there exists a mailbox name that isn\(aqt valid for the +other side. +These invalid mailbox names are fixed by replacing such invalid +characters with the given +.IR alt_char . +The default is +.RB \(aq _ \(aq. +.\"--------------------------------- +.TP +.B \-D +Activates debug messages and makes +.B dsync +more verbose. +.\"--------------------------------- +.TP +.B \-f +Makes +.B dsync +run in "full sync" mode rather than "fast sync" mode. +.\"--------------------------------- +.TP +.BI \-m\ mailbox +Specifies the +.I mailbox +that should be synchronized or from which mails should be converted. +The default is to synchronize all respectively convert from all mailboxes. +.\"--------------------------------- +.TP +.BI \-o\ setting = value +Overrides the configuration +.I setting +from +.I @sysconfdir@/dovecot/dovecot.conf +and from the userdb with the given +.IR value . +In order to override multiple settings to +.B \-o +option may be specified multiple times. +.\"--------------------------------- +.TP +.B \-r +Specifies that this side of +.B dsync +mirror runs read\-only. +(This probably gets removed when full backup functionality is implemented.) +.\"--------------------------------- +.TP +.BI \-u\ user +Specifies that the userdb lookup for the given +.I user +should be done and used to set up the environment (uid, gid, home, etc.). +By default the system user\(aqs current environment will be used. +.\"--------------------------------- +.TP +.B \-v +Makes +.B dsync +more verbose. +.\"------------------------------------------------------------------------ +.SH COMMANDS +.B dsync +provides the following commands: +.\"------------------------------------------------------------------------ +.SS convert +. +\fBdsync\fP [\fIdsync options\fP] \fBconvert\fP \fIsource_mail_location\fP +.PP +The +.B convert +command is used to convert mailboxes from one mailbox format to another. +The +.B \-r +option is ignored by the +.B convert +command. +.TP +.I source_mail_location +Specifies the source mail_location, from which the mails should be +converted. +The syntax for the +.I source_mail_location +is: +.IB type : path\c +[\c +.BI : modifier\c +\ ...] +.br +For details see: http://wiki.dovecot.org/MailLocation +.PP +The destination mail_location is configured in +@sysconfdir@/dovecot/conf.d/10\-mail.conf. +The global mail_location setting will be overridden by the mail field from +the userdb lookup for +.IR user , +if it returns one. +The mail_location from the userdb and/or from the configuration file may be +overridden by specifying a different mail_location using the +.B \-o +option. +.\"------------------------------------------------------------------------ +.SS mirror +. +\fBdsync\fP [\fIdsync options\fP] \fBmirror\fP +\fB\(dqssh\fP [\fIssh options\fP] [\fIuser\fP\fB@\fP]\fIhostname\fP +\fBdsync\fP [\fIdsync options\fP]\fB\(dq\fP + +.\" remote: -o mail_location=... ??? +.\" remote: mbox && local: mdbox ??? +.\" ssh -C su - dsyny -u mail@user ... +.\" ssh -t el-presidente 'su -c "vmm di example.com" -' +.\" ssh -t el-presidente 'sudo vmm di example.com' +.\"------------------------------------------------------------------------ +.SH EXAMPLE +.SS convert +.PP +Assuming that the +.I mail_location +setting in +.I @sysconfdir@/dovecot/conf.d/10\-mail.conf +is set to: +.B mail_location = mdbox:~/mdbox\c +\ , a logged in system user may convert her/his mails from its Maildir in +her/his home directory to the mdbox mailbox format. +The user has to execute the command: +.PP +.RS +.nf +.B dsync convert maildir:~/Maildir +.fi +.RE + +.SS mirror +Synchronize user\(aqs mails between local server and imap2 server: +.PP +.RS +.nf +.B dsync \-u user@example.com mirror \(rs +.B \(dqssh imap2.example.com dsync \-u user@example.com\(dq +.fi +.RE +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH SEE ALSO +.BR doveadm (1), +.BR doveconf (1), +.BR dovecot (1) diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/global-options-formatter.inc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/global-options-formatter.inc Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,35 @@ +.SH OPTIONS +Global +.BR doveadm (1) +.IR options : +.TP +.B \-D +Enables verbosity and debug messages. +.TP +.BI \-f\ formatter +Specifies the +.I formatter +for formatting the output. +Supported formatters are: +.RS +.TP +.B flow +prints each line with +.IB key = value +pairs. +.TP +.B pager +prints each +.IR key :\ value +pair on its own line and separates records with form feed character +.RB ( ^L ). +.TP +.B tab +prints a table header followed by tab separated value lines. +.TP +.B table +prints a table header followed by adjusted value lines. +.RE +.TP +.B \-v +Enables verbosity, including progress counter. diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/global-options.inc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/global-options.inc Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,10 @@ +.SH OPTIONS +Global +.BR doveadm (1) +.IR options : +.TP +.B \-D +Enables verbosity and debug messages. +.TP +.B \-v +Enables verbosity, including progress counter. diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/option-A.inc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/option-A.inc Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,22 @@ +.TP +.B \-A +If the +.B \-A +option is present, the +.I command +will be performed for all users. +Using this option in combination with system users from +.B userdb { driver = passwd } +is not recommended, because it contains also users with a lower UID than +the one configured with the +.I first_valid_uid +setting. +.sp +When the sql userdb module is used make sure that the +.I iterate_query +setting in the +.I @sysconfdir@/dovecot/dovecot\-sql.conf.ext +matches your database layout. +Otherwise +.BR doveadm (1) +will be unable to iterate over all users. diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/option-u-user.inc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/option-u-user.inc Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,20 @@ +.TP +.BI \-u\ user/mask +Run the +.I command +only for the given +.IR user . +It\(aqs also possible to use +.RB \(aq * \(aq +and +.RB \(aq ? \(aq +wildcards (e.g. \-u *@example.org). +.br +When neither the +.B \-A +option nor +.BI \-u\ user +was specified, the +.I command +will be executed with the environment of the +currently logged in user. diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/reporting-bugs.inc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/reporting-bugs.inc Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,6 @@ +.SH REPORTING BUGS +Report bugs, including +.I doveconf \-n +output, to the Dovecot Mailing List . +Information about reporting bugs is available at: +http://dovecot.org/bugreport.html diff -r 9be162cc2c52 -r be2b7d2901a0 doc/man/sed.sh --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/man/sed.sh Mon Jun 28 13:56:39 2010 +0000 @@ -0,0 +1,27 @@ +#!/bin/sh + +SRCDIR="${1:-`pwd`}" +RUNDIR="${2:-/usr/local/var/run/dovecot}" +SYSCONFDIR="${3:-/usr/local/etc}" + +sed -e "/^@INCLUDE:global-options@$/{ + r ${SRCDIR}/global-options.inc + d + }" \ + -e "/^@INCLUDE:global-options-formatter@$/{ + r ${SRCDIR}/global-options-formatter.inc + d + }" \ + -e "/^@INCLUDE:option-A@$/{ + r ${SRCDIR}/option-A.inc + d + }" \ + -e "/^@INCLUDE:option-u-user@$/{ + r ${SRCDIR}/option-u-user.inc + d + }" \ + -e "/^@INCLUDE:reporting-bugs@$/{ + r ${SRCDIR}/reporting-bugs.inc + d + }" | sed -e "s|@sysconfdir@|${SYSCONFDIR}|" -e "s|@rundir@|${RUNDIR}|" +