Mercurial > dovecot > core-2.2

comparison doc/man/doveadm-director.1.in @ 11644:be2b7d2901a0 HEAD

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: added manual pages
author Pascal Volk <user@localhost.localdomain.org>
date Mon, 28 Jun 2010 13:56:39 +0000
parents
children e546af72d6bb
comparison
equal deleted inserted replaced
11643:9be162cc2c52 11644:be2b7d2901a0
1 .\" Copyright (c) 2010 Dovecot authors, see the included COPYING file
2 .TH DOVEADM\-DIRECTOR 1 "2010-06-22" "Dovecot v2.0" "Dovecot"
3 .SH NAME
4 doveadm\-director \- Manage Dovecot directors
5 .\"------------------------------------------------------------------------
6 .SH SYNOPSIS
7 .BR doveadm " [" \-Dv "] " "director add"
8 [\fB\-a\fP \fIdirector_socket_path\fP]
9 .IR host " [" vhost_count ]
10 .\"-------------------------------------
11 .br
12 .BR doveadm " [" \-Dv "] " "director flush"
13 [\fB\-a\fP \fIdirector_socket_path\fP]
14 \fIhost\fP|\fBall\fP
15 .\"-------------------------------------
16 .br
17 .BR doveadm " [" \-Dv "] " "director remove"
18 [\fB\-a\fP \fIdirector_socket_path\fP]
19 .I host
20 .\"-------------------------------------
21 .br
22 .BR doveadm " [" \-Dv "] " "director status"
23 [\fB\-a\fP \fIdirector_socket_path\fP]
24 .RI [ user ]
25 .\"------------------------------------------------------------------------
26 .SH DESCRIPTION
27 .B doveadm director
28 can be used to manage and query the status of the list of backend mail
29 servers where Dovecot proxy can redirect connections to.
30 .\"------------------------------------------------------------------------
31 @INCLUDE:global-options@
32 .\" --- command specific options --- "/.
33 .PP
34 Command specific
35 .IR options :
36 .\"-------------------------------------
37 .TP
38 .BI \-a\ director_socket_path
39 This option is used to specify an absolute path to an alternative UNIX
40 domain socket.
41 .sp
42 By default
43 .BR doveadm (1)
44 will use the socket
45 .IR @rundir@/director\-admin .
46 The socket may be located in another directory, when the default
47 .I base_dir
48 setting was overridden in
49 .IR @sysconfdir@/dovecot/dovecot.conf .
50 .\"------------------------------------------------------------------------
51 .SH ARGUMENTS
52 .TP
53 .I host
54 A mail server\(aqs hostname or IP address.
55 .\"-------------------------------------
56 .TP
57 .I user
58 Is a
59 .IR user \(aqs
60 login name.
61 Depending on the configuration, a login name may be for example
62 .BR jane " or " john@example.com .
63 .\"-------------------------------------
64 .TP
65 .I vhost_count
66 The number of \(dqvirtual hosts\(dq to assign to this server. The higher
67 the number is relative to other servers, the more connections it gets. The
68 default is 100.
69 .\"------------------------------------------------------------------------
70 .SH COMMANDS
71 .SS director add
72 .B doveadm director add
73 [\fB\-a\fP \fIdirector_socket_path\fP]
74 .I host
75 .RI [ vhost_count ]
76 .PP
77 The command\(aqs tasks are:
78 .TP 4
79 *
80 assign a new mail server to the director.
81 .TP
82 *
83 increase/decrease the
84 .I vhost_count
85 of an already assigned server.
86 .PP
87 .\"-------------------------------------
88 .SS director flush
89 .B doveadm director flush
90 [\fB\-a\fP \fIdirector_socket_path\fP]
91 \fIhost\fP|\fBall\fP
92 .PP
93 .B doveadm director flush
94 drops all user associations either from the given
95 .I host
96 or
97 .B all
98 hosts.
99 This command is intended mainly for testing purposes.
100 .\"-------------------------------------
101 .SS director remove
102 .B doveadm director remove
103 [\fB\-a\fP \fIdirector_socket_path\fP]
104 .I host
105 .PP
106 Use this command in oder to remove the given
107 .I host
108 from the director.
109 .\"-------------------------------------
110 .SS director status
111 .B doveadm director status
112 [\fB\-a\fP \fIdirector_socket_path\fP]
113 .RI [ user ]
114 .PP
115 This command is used to show the current usage of all assigned mail
116 servers.
117 .br
118 When a user name is given, this command shows which server the
119 .I user
120 is currently assigned to, where the user will be assigned after the current
121 saved assignment gets removed and where the user would be assigned to if
122 the whole proxy cluster was restarted fresh.
123 .\"------------------------------------------------------------------------
124 .SH FILES
125 .TP
126 .I @sysconfdir@/dovecot/dovecot.conf
127 Dovecot\(aqs main configuration file.
128 .TP
129 .I @sysconfdir@/dovecot/conf.d/10\-director.conf
130 Director specific settings.
131 .\"------------------------------------------------------------------------
132 .SH EXAMPLE
133 Add a director with vhost count 150 (or change existing one\(aqs
134 vhost count to 150):
135 .PP
136 .nf
137 .B doveadm \-v director add x1357.imap.ha.example.net 150
138 2001:db8:543:6861:143::1357: OK
139 .fi
140 .\"-------------------------------------
141 .PP
142 Remove a director:
143 .PP
144 .nf
145 .B doveadm director remove x1357.imap.ha.example.net
146 .fi
147 .\"-------------------------------------
148 .PP
149 Query the status of mail hosts in a director:
150 .PP
151 .nf
152 .B doveadm director status
153 mail server ip vhosts users
154 192.168.10.1 100 125
155 192.168.10.2 100 144
156 192.168.10.3 100 115
157 .fi
158 .\"-------------------------------------
159 .PP
160 Query the status of a user\(aqs assignment:
161 .PP
162 .nf
163 .B doveadm director status user@example.com
164 Current: 192.168.10.1 (expires 2010\-06\-18 20:17:04)
165 Hashed: 192.168.10.2
166 Initial config: 192.168.10.3
167 .fi
168 .PP
169 This means that the user is currently assigned to mail server on IP
170 192.168.10.1. After all of user\(aqs connections have logged out, the
171 assignment will be removed (currently it looks like at 20:17:04, but
172 that may be increased). After the assignment has expired, the user will
173 next time be redirected to 192.168.10.2 (assuming no changes to director
174 settings). If the entire Dovecot proxy cluster was restarted, so that all
175 of the director configuration would revert back to its initial values, the
176 user would be redirected to 192.168.10.3.
177 .\"------------------------------------------------------------------------
178 @INCLUDE:reporting-bugs@
179 .\"------------------------------------------------------------------------
180 .SH SEE ALSO
181 .BR doveadm (1)