1IMAP::Shell(3) User Contributed Perl Documentation IMAP::Shell(3)
2
3
4
6 Cyrus::IMAP::Shell - Perl version of cyradm
7
9 $ cyradm [--user authid] [--authz authzid] [--[no]rc] [--systemrc file] [--userrc file] \
10 > [--port n] [--auth mechanism] [--server] server
11
12 but possibly
13
14 $ perl -MCyrus::IMAP::Shell -e 'run("myscript")'
15
16 or even (not recommended)
17
18 use Cyrus::IMAP::Admin::Shell;
19
20 run('myscriptname');
21
23 This module implements cyradm in Perl. It is a shell around
24 Cyrus::IMAP::Admin. Commands are provided in both Tcl-compatible forms
25 and GNU-style long option forms.
26
27 The ``cyradm`` utility is a simple command line for performing common
28 administrative tasks on a Cyrus IMAP server, written in Perl.
29
30 The cyradm utility can either be executed from a client where it has
31 been installed and connect to the server via IMAP or it can be executed
32 locally via a shell on the server.
33
34 cyradm understands /bin/sh-style redirection: any command can have its
35 standard or error output redirected, with all sh-style redirections
36 (except \<\>) supported. It does not currently understand pipes or
37 backgrounding.
38
39 If the Term::Readline::Perl or Term::Readline::GNU modules are
40 available, cyradm will use it.
41
43 "--u", "--user" user
44 Authenticate with the specified username.
45
46 "--authz" user
47 Authorize the connection as being the specified username.
48
49 "--norc", "--rc"
50 (Do not) load the configuration files.
51
52 "--systemrc" file
53 Use the system configuration file specified.
54
55 "--userrc" file
56 Use the user configuration file specified.
57
58 "--port" port
59 Connect to the *server* specified on the port specified.
60
61 "--auth" mechanism
62 Use the mechanism specified to authenticate. One of PLAIN, LOGIN,
63 DIGEST-MD5, etc.
64
65 "--help"
66 Show a help message about these command-line options.
67
68 "--version"
69 Display the version of Cyrus IMAP the current ``cyradm`` command is
70 a part of.
71
72 "--server" server
73 The server address to connect to.
74
76 authenticate
77 authenticate ["--minssf" N] ["--maxssf" N] ["--mechanisms" list]
78 ["--service" name] ["--tlskey" keyfile] ["--notls"] ["--cafile"
79 cacertfile] ["--capath" cacertdir] user
80
81 Authenticate to server. You must already be connected to a server and
82 Cyrus imapd will refuse to allow you to re-authenticate once you have
83 authenticated once.
84
85 aliases: "auth", "login"
86
87 chdir
88 chdir directory
89
90 Change directory. A "pwd" builtin is not provided, but the default
91 command action will run "pwd" from a shell if invoked.
92
93 aliases: "cd"
94
95 createmailbox
96 createmailbox ["--partition" partition] ["--specialuse" specialuse]
97 mailbox
98
99 createmailbox ["--specialuse" specialuse] mailbox partition
100
101 Create a mailbox on the default or a specified partition. Both old-
102 style and getopt-style usages are accepted (combining them will produce
103 an error). Optionally assign a special use to the mailbox.
104
105 New mailboxes inherit the ACL permissions of their parent mailbox,
106 except for top-level mailboxes such as the user's INBOX. Mailboxes that
107 are the user's INBOX are assigned all to the corresponding user.
108
109 Example Usage
110 localhost> :command:`cm user.john`
111 localhost> :command:`lm`
112 user.john (\HasNoChildren)
113 localhost> :command:`lam user.john`
114 john lrswipkxtecda
115
116 Note that in the above example, the "unixhierarchysep" setting in
117 imapd.conf is set to 0. When using the UNIX hierarchy separator,
118 the "/" (forward slash) character would be used as the hierarchy
119 separator, and the example would look as follows:
120
121 Example Usage with "unixhierarchysep: 1"
122 localhost> :command:`cm user/john`
123 localhost> :command:`lm`
124 user/john (\HasNoChildren)
125 localhost> :command:`lam user/john`
126 john lrswipkxtecda
127
128 Note
129 The above examples use the unqualified, shorthand user identifier
130 john as the mailbox name.
131
132 With the use of virtual domains, controlled through the
133 "virtdomains" setting in imapd.conf(5).
134
135 aliases: "cm", "create"
136
137 deleteaclmailbox
138 deleteaclmailbox mailbox id [...]
139
140 Remove ACLs from the specified mailbox.
141
142 aliases: "delteacl", "dam"
143
144 deletemailbox
145 deletemailbox mailbox
146
147 Delete the specified mailbox.
148
149 Administrators do not have implicit delete rights on mailboxes. Use
150 the "setaclmailbox" command to grant the "x" permission to your
151 principal if you need to delete a mailbox you do not own.
152
153 Note that the online help admits to an optional host argument. This
154 argument is not currently used, and will be rejected with an error if
155 specified; it is reserved for IMSP.
156
157 aliases: "delete", "dm"
158
159 disconnect
160 disconnect
161
162 Disconnect from the current server. The prompt will revert to
163 "cyradm>". This does not quit cyradm.
164
165 aliases: "disc"
166
167 exit
168 exit [number]
169
170 Exit "cyradm", optionally with a specific exit status; the exit status
171 of the last command will be used if one is not specified.
172
173 aliases: "quit"
174
175 help
176 help [command]
177
178 Show help for "command" or all commands.
179
180 aliases: "?"
181
182 getmetadata
183 getmetadata [mailbox]
184
185 Display mailbox/server metadata
186
187 aliases: "getmd"
188
189 info
190 info [mailbox]
191
192 Display the mailbox/server annotations.
193
194 listaclmailbox
195 listaclmailbox mailbox
196
197 List ACLs on the specified mailbox.
198
199 aliases: "lam", "listacl"
200
201 listmailbox
202 listmailbox ["--subscribed"] ["--specialuse"] [pattern [reference]]
203
204 List all, or all subscribed or special-use, mailboxes matching the
205 specified pattern. The pattern may have embedded wildcards '*' or '%',
206 which match anything or anything except the separator character,
207 respectively.
208
209 Mailboxes returned will be relative to the specified reference if one
210 is specified. This allows a mailbox list to be limited to a particular
211 hierarchy.
212
213 In some cases when the '%' wildcard is used to end a pattern, it may
214 match an entry which is not a mailbox but which contains other
215 mailboxes. In this case, the entry will be parenthesized to indicate
216 that it is a root for other mailboxes, as opposed to a mailbox itself.
217
218 aliases: "list", "lm"
219
220 listquota
221 listquota root
222
223 List quotas on specified root. If the specified mailbox path does not
224 have a quota assigned, an error will be raised; see "listquotaroot" for
225 a way to find the quota root for a mailbox.
226
227 aliases: "lq"
228
229 listquotaroot
230 listquotaroot mailbox
231
232 Show quota roots and quotas for mailbox
233
234 aliases: "lqm", "lqr"
235
236 mboxconfig
237 mboxconfig ["--private"] mailbox attribute value
238
239 Set mailbox metadata, optionally set the private instead of the shared
240 version of the metadata. A value of "none" will remove the attribute.
241
242 The currently supported attributes are:
243
244 "comment" description
245 Sets a comment or description associated with the mailbox.
246
247 "expire" days
248 Sets the number of days after which messages will be expired from
249 the mailbox.
250
251 "news2mail" address
252 Sets an email address to which messages injected into the server
253 via NNTP will be sent.
254
255 "pop3showafter" time
256 Sets a time (in RFC3501 format, for example "6-Jan-2011 11:45:32
257 +1100") which specifies a cutoff date such that POP3 fetching of
258 the folder does not see messages whose internaldate is before or
259 equal to the date.
260
261 "sharedseen" true|false
262 Enables the use of a shared \Seen flag on messages rather than a
263 per-user \Seen flag. The 's' right in the mailbox ACL still
264 controls whether a user can set the shared \Seen flag.
265
266 "sieve" scriptname
267 Indicates the name of the global sieve script that should be run
268 when a message is delivered to the shared mailbox (not used for
269 personal mailboxes).
270
271 "squat" true|false
272 Indicates that the mailbox should have a squat index created for
273 it.
274
275 aliases: "mboxcfg"
276
277 reconstruct
278 reconstruct ["-r"] mailbox
279
280 Reconstruct the specified mailbox, optionally recursing and
281 reconstructing child mailboxes if the "-r" flag is given.
282
283 For more information see reconstruct(8).
284
285 renamemailbox
286 renamemailbox ["--partition" partition] oldname newname
287
288 renamemailbox oldname newname [partition]
289
290 Rename the specified mailbox, optionally moving it to a different
291 partition. Both old-style and getopt-style usages are accepted;
292 combining them will produce an error.
293
294 aliases: "rename", "renm"
295
296 server
297 server
298
299 server [--noauthenticate] [server]
300
301 With no arguments, show the current server. With an argument, connect
302 to that server. It will prompt for automatic login unless the
303 "--noauthenticate" option is specified. (This may change; in
304 particular, either automatic authentication will be removed or all
305 "authenticate" options will be added.)
306
307 When connected to a server, cyradm's prompt changes from "cyradm>" to
308 "servername>", where servername is the fully qualified domain name of
309 the connected server.
310
311 aliases: "connect", "servername"
312
313 setaclmailbox
314 setaclmailbox mailbox id rights [id rights ...]
315
316 Set ACLs on a mailbox. The ACL may be one of the special strings
317 "none", "read" ("lrs"), "post" ("lrsp"), "append" ("lrsip"), "write"
318 ("lrswipkxte"), "delete" ("lrxte"), or "all" ("lrswipkxte"), or any
319 combinations of the ACL codes:
320
321 l Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
322
323 r Read (SELECT/EXAMINE the mailbox, perform STATUS)
324
325 s Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during
326 APPEND/COPY/FETCH BODY[...])
327
328 w Write flags other than \SEEN and \DELETED
329
330 i Insert (APPEND, COPY destination)
331
332 p Post (send mail to mailbox)
333
334 k Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in
335 RENAME)
336
337 x Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
338
339 t Delete messages (set/clear \DELETED flag via STORE, also set
340 \DELETED flag during APPEND/COPY)
341
342 e Perform EXPUNGE and expunge as part of CLOSE
343
344 a Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
345
346 aliases: "setacl", "sam"
347
348 setinfo
349 setinfo attribute value
350
351 Set server metadata. A value of "none" will remove the attribute. The
352 currently supported attributes are:
353
354 "motd" message
355 Sets a "message of the day". The message gets displayed as an
356 ALERT upon connection.
357
358 "comment" note
359 Sets a comment or description associated with the server.
360
361 "admin" address
362 Sets the administrator email address for the server.
363
364 "shutdown" message
365 Sets a shutdown message. The message gets displayed as an ALERT
366 and all users are disconnected from the server (subsequent logins
367 are disallowed).
368
369 "expire" days
370 Sets the number of days after which messages will be expired from
371 the server (unless overridden by a mailbox annotation).
372
373 "squat" true|false
374 Indicates that all mailboxes should have a squat indexes created
375 for them (unless overridden by a mailbox annotation).
376
377 setmetadata
378 setmetadata [--private] mailbox [annotation] value
379
380 Set metadata on mailbox, where annotation is one of
381 [comment|expire|news2mail|pop3showafter|sharedseen|sieve|specialuse|
382 squat|/<explicit annotation>].
383
384 Note that value with a leading backslash must be escaped with an
385 additional backslash. For example:
386
387 setmetadata --private Spam specialuse "\\Junk"
388
389 Note, too, that "private" annotations are private to the user currently
390 authenticated as, not necessarily the owner of the mailbox. To set
391 annotations for another user you must authorize as that user.
392
393 In addition to the use of optional flag --private, one may use a more
394 explicit syntax, prefixing the annotation with '/shared/' or
395 '/private/' as in this example:
396
397 setmetadata Spam /private/specialuse "\\Junk"
398
399 aliases: "setmd"
400
401 setquota
402 setquota root resource value [resource value ...]
403
404 Set a quota on the specified root, which may or may not be an actual
405 mailbox. The resources understood by Cyrus are "STORAGE", "MESSAGE",
406 "X-NUM-FOLDERS" and "X-ANNOTATION-STORAGE". The storage units are, as
407 defined in RFC 2087, groups of 1024 octets (i.e. Kilobytes). The value
408 may be the special string "none" which will remove the quota.
409
410 aliases: "sq"
411
412 subscribe
413 subscribe mailbox
414
415 Subscribe to the given mailbox.
416
417 unsubscribe
418 unsubscribe mailbox
419
420 Unsubscribe to the given mailbox.
421
422 version
423 version
424
425 Display the version info of the current server.
426
427 aliases: "ver"
428
429 xfermailbox
430 xfermailbox ["--partition" partition] mailbox server
431
432 xfermailbox mailbox server [partition]
433
434 Transfer (relocate) the specified mailbox to a different server. Both
435 old-style and getopt-style usages are accepted; combining them will
436 produce an error.
437
438 aliases: "xfer"
439
441 GNU-style long options must be given in their entirety; Tcl-style
442 options may be abbreviated.
443
444 Tcl-style options are provided as a compatibility feature. They will
445 probably go away in the future.
446
447 Multiple commands can be given on a line, separated by ';' characters.
448
449 All commands set an exit status, which at present is not useful.
450
451 Unknown commands are passed to a subshell for execution.
452
453 The Tcl version of cyradm is used for scripting as well as
454 interactively. While this is possible to a limited extent by use of
455 the "run" method, scripting would normally be done with
456 "Cyrus::IMAP::Admin", which is far more flexible than either
457 interactive "cyradm" or the Tcl scripting mechanism for Cyrus.
458
459 cyradm understands /bin/sh-style redirection: any command can have its
460 standard or error output redirected, with all sh-style redirections
461 (except "<>") supported. It does not currently understand pipes or
462 backgrounding.
463
464 If the "Term::Readline::Perl" or "Term::Readline::GNU" modules are
465 available, cyradm will use it.
466
467 An alias facility is implemented internally, but no access is currently
468 provided to it. This will change, if only to allow some of the
469 predefined aliases to be removed if they conflict with useful shell
470 commands.
471
473 Brandon S. Allbery, allbery@ece.cmu.edu
474
476 Cyrus::IMAP::Admin, Term::ReadLine, sh(1), perl(1), imapd(8),
477 imapd.conf(5), reconstruct(8)
478
479
480
481perl v5.34.0 2022-02-10 IMAP::Shell(3)