1IMAP::Shell(3) User Contributed Perl Documentation IMAP::Shell(3)
2
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 but possibly
13 $ perl -MCyrus::IMAP::Shell -e 'run("myscript")'
15 or even (not recommended)
17 use Cyrus::IMAP::Admin::Shell;
19 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 The ``cyradm`` utility is a simple command line for performing common
28 administrative tasks on a Cyrus IMAP server, written in Perl.
29 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 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 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 "--authz" user
47 Authorize the connection as being the specified username.
48 "--norc", "--rc"
50 (Do not) load the configuration files.
51 "--systemrc" file
53 Use the system configuration file specified.
54 "--userrc" file
56 Use the user configuration file specified.
57 "--port" port
59 Connect to the *server* specified on the port specified.
60 "--auth" mechanism
62 Use the mechanism specified to authenticate. One of PLAIN, LOGIN,
63 DIGEST-MD5, etc.
64 "--help"
66 Show a help message about these command-line options.
67 "--version"
69 Display the version of Cyrus IMAP the current ``cyradm`` command is
70 a part of.
71 "--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 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 aliases: "auth", "login"
86 chdir
88 chdir directory
89 Change directory. A "pwd" builtin is not provided, but the default
91 command action will run "pwd" from a shell if invoked.
92 aliases: "cd"
94 createmailbox
96 createmailbox ["--partition" partition] ["--specialuse" specialuse]
97 mailbox
98 createmailbox ["--specialuse" specialuse] mailbox partition
100 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 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 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 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 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 Note
129 The above examples use the unqualified, shorthand user identifier
130 john as the mailbox name.
131 With the use of virtual domains, controlled through the
133 "virtdomains" setting in imapd.conf(5).
134 aliases: "cm", "create"
136 deleteaclmailbox
138 deleteaclmailbox mailbox id [...]
139 Remove ACLs from the specified mailbox.
141 aliases: "delteacl", "dam"
143 deletemailbox
145 deletemailbox mailbox
146 Delete the specified mailbox.
148 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 aliases: "delete", "dm"
154 disconnect
156 disconnect
157 Disconnect from the current server. The prompt will revert to
159 "cyradm>". This does not quit cyradm.
160 aliases: "disc"
162 exit
164 exit [number]
165 Exit "cyradm", optionally with a specific exit status; the exit status
167 of the last command will be used if one is not specified.
168 aliases: "quit"
170 help
172 help [command]
173 Show help for "command" or all commands.
175 aliases: "?"
177 getmetadata
179 getmetadata [mailbox]
180 Display mailbox/server metadata
182 aliases: "getmd"
184 info
186 info [mailbox]
187 Display the mailbox/server annotations.
189 listaclmailbox
191 listaclmailbox mailbox
192 List ACLs on the specified mailbox.
194 aliases: "lam", "listacl"
196 listmailbox
198 listmailbox ["--subscribed"] ["--specialuse"] [pattern [reference]]
199 List all, or all subscribed or special-use, mailboxes matching the
201 specified pattern. The pattern may have embedded wildcards '*' or '%',
202 which match anything or anything except the separator character,
203 respectively.
204 Mailboxes returned will be relative to the specified reference if one
206 is specified. This allows a mailbox list to be limited to a particular
207 hierarchy.
208 In some cases when the '%' wildcard is used to end a pattern, it may
210 match an entry which is not a mailbox but which contains other
211 mailboxes. In this case, the entry will be parenthesized to indicate
212 that it is a root for other mailboxes, as opposed to a mailbox itself.
213 aliases: "list", "lm"
215 listquota
217 listquota root
218 List quotas on specified root. If the specified mailbox path does not
220 have a quota assigned, an error will be raised; see "listquotaroot" for
221 a way to find the quota root for a mailbox.
222 aliases: "lq"
224 listquotaroot
226 listquotaroot mailbox
227 Show quota roots and quotas for mailbox
229 aliases: "lqm", "lqr"
231 mboxconfig
233 mboxconfig ["--private"] mailbox attribute value
234 Set mailbox metadata, optionally set the private instead of the shared
236 version of the metadata. A value of "none" will remove the attribute.
237 The currently supported attributes are:
239 "comment" description
241 Sets a comment or description associated with the mailbox.
242 "expire" days
244 Sets the number of days after which messages will be expired from
245 the mailbox.
246 "news2mail" address
248 Sets an email address to which messages injected into the server
249 via NNTP will be sent.
250 "pop3showafter" time
252 Sets a time (in RFC3501 format, for example "6-Jan-2011 11:45:32
253 +1100") which specifies a cutoff date such that POP3 fetching of
254 the folder does not see messages whose internaldate is before or
255 equal to the date.
256 "sharedseen" true|false
258 Enables the use of a shared \Seen flag on messages rather than a
259 per-user \Seen flag. The 's' right in the mailbox ACL still
260 controls whether a user can set the shared \Seen flag.
261 "sieve" scriptname
263 Indicates the name of the global sieve script that should be run
264 when a message is delivered to the shared mailbox (not used for
265 personal mailboxes).
266 "squat" true|false
268 Indicates that the mailbox should have a squat index created for
269 it.
270 aliases: "mboxcfg"
272 reconstruct
274 reconstruct ["-r"] mailbox
275 Reconstruct the specified mailbox, optionally recursing and
277 reconstructing child mailboxes if the "-r" flag is given.
278 For more information see reconstruct(8).
280 renamemailbox
282 renamemailbox ["--partition" partition] oldname newname
283 renamemailbox oldname newname [partition]
285 Rename the specified mailbox, optionally moving it to a different
287 partition. Both old-style and getopt-style usages are accepted;
288 combining them will produce an error.
289 aliases: "rename", "renm"
291 server
293 server
294 server [--noauthenticate] [server]
296 With no arguments, show the current server. With an argument, connect
298 to that server. It will prompt for automatic login unless the
299 "--noauthenticate" option is specified. (This may change; in
300 particular, either automatic authentication will be removed or all
301 "authenticate" options will be added.)
302 When connected to a server, cyradm's prompt changes from "cyradm>" to
304 "servername>", where servername is the fully qualified domain name of
305 the connected server.
306 aliases: "connect", "servername"
308 setaclmailbox
310 setaclmailbox mailbox id rights [id rights ...]
311 Set ACLs on a mailbox. The ACL may be one of the special strings
313 "none", "read" ("lrs"), "post" ("lrsp"), "append" ("lrsip"), "write"
314 ("lrswipkxte"), "delete" ("lrxte"), or "all" ("lrswipkxte"), or any
315 combinations of the ACL codes:
316 l Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
318 r Read (SELECT/EXAMINE the mailbox, perform STATUS)
320 s Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during
322 APPEND/COPY/FETCH BODY[...])
323 w Write flags other than \SEEN and \DELETED
325 i Insert (APPEND, COPY destination)
327 p Post (send mail to mailbox)
329 k Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in
331 RENAME)
332 x Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
334 t Delete messages (set/clear \DELETED flag via STORE, also set
336 \DELETED flag during APPEND/COPY)
337 e Perform EXPUNGE and expunge as part of CLOSE
339 a Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
341 aliases: "setacl", "sam"
343 setinfo
345 setinfo attribute value
346 Set server metadata. A value of "none" will remove the attribute. The
348 currently supported attributes are:
349 "motd" message
351 Sets a "message of the day". The message gets displayed as an
352 ALERT upon connection.
353 "comment" note
355 Sets a comment or description associated with the server.
356 "admin" address
358 Sets the administrator email address for the server.
359 "shutdown" message
361 Sets a shutdown message. The message gets displayed as an ALERT
362 and all users are disconnected from the server (subsequent logins
363 are disallowed).
364 "expire" days
366 Sets the number of days after which messages will be expired from
367 the server (unless overridden by a mailbox annotation).
368 "squat" true|false
370 Indicates that all mailboxes should have a squat indexes created
371 for them (unless overridden by a mailbox annotation).
372 setmetadata
374 setmetadata [--private] mailbox [annotation] value
375 Set metadata on mailbox, where annotation is one of
377 [comment|expire|news2mail|pop3showafter|sharedseen|sieve|specialuse|
378 squat|/<explicit annotation>].
379 Note that value with a leading backslash must be escaped with an
381 additional backslash. For example:
382 setmetadata --private Spam specialuse "\\Junk"
384 Note, too, that "private" annotations are private to the user currently
386 authenticated as, not necessarily the owner of the mailbox. To set
387 annotations for another user you must authorize as that user.
388 In addition to the use of optional flag --private, one may use a more
390 explicit syntax, prefixing the annotation with '/shared/' or
391 '/private/' as in this example:
392 setmetadata Spam /private/specialuse "\\Junk"
394 aliases: "setmd"
396 setquota
398 setquota root resource value [resource value ...]
399 Set a quota on the specified root, which may or may not be an actual
401 mailbox. The resources understood by Cyrus are "STORAGE", "MESSAGE",
402 "X-NUM-FOLDERS" and "X-ANNOTATION-STORAGE". The storage units are, as
403 defined in RFC 2087, groups of 1024 octets (i.e. Kilobytes). The value
404 may be the special string "none" which will remove the quota.
405 aliases: "sq"
407 subscribe
409 subscribe mailbox
410 Subscribe to the given mailbox.
412 unsubscribe
414 unsubscribe mailbox
415 Unsubscribe to the given mailbox.
417 version
419 version
420 Display the version info of the current server.
422 aliases: "ver"
424 xfermailbox
426 xfermailbox ["--partition" partition] mailbox server
427 xfermailbox mailbox server [partition]
429 Transfer (relocate) the specified mailbox to a different server. Both
431 old-style and getopt-style usages are accepted; combining them will
432 produce an error.
433 aliases: "xfer"
435
437 GNU-style long options must be given in their entirety; Tcl-style
438 options may be abbreviated.
439 Tcl-style options are provided as a compatibility feature. They will
441 probably go away in the future.
442 Multiple commands can be given on a line, separated by ';' characters.
444 All commands set an exit status, which at present is not useful.
446 Unknown commands are passed to a subshell for execution.
448 The Tcl version of cyradm is used for scripting as well as
450 interactively. While this is possible to a limited extent by use of
451 the "run" method, scripting would normally be done with
452 "Cyrus::IMAP::Admin", which is far more flexible than either
453 interactive "cyradm" or the Tcl scripting mechanism for Cyrus.
454 cyradm understands /bin/sh-style redirection: any command can have its
456 standard or error output redirected, with all sh-style redirections
457 (except "<>") supported. It does not currently understand pipes or
458 backgrounding.
459 If the "Term::Readline::Perl" or "Term::Readline::GNU" modules are
461 available, cyradm will use it.
462 An alias facility is implemented internally, but no access is currently
464 provided to it. This will change, if only to allow some of the
465 predefined aliases to be removed if they conflict with useful shell
466 commands.
467
469 Brandon S. Allbery, allbery@ece.cmu.edu
470
472 Cyrus::IMAP::Admin, Term::ReadLine, sh(1), perl(1), imapd(8),
473 imapd.conf(5), reconstruct(8)
474perl v5.38.0 2023-09-13 IMAP::Shell(3)