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 seperator,
118 the "/" (forward slash) character would be used as the hierarchy
119 seperator, 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 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 aliases: "delete", "dm"
158 disconnect
160 disconnect
161 Disconnect from the current server. The prompt will revert to
163 "cyradm>". This does not quit cyradm.
164 aliases: "disc"
166 exit
168 exit [number]
169 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 aliases: "quit"
174 help
176 help [command]
177 Show help for "command" or all commands.
179 aliases: "?"
181 info
183 info [mailbox]
184 Display the mailbox/server metadata.
186 listaclmailbox
188 listaclmailbox mailbox
189 List ACLs on the specified mailbox.
191 aliases: "lam", "listacl"
193 listmailbox
195 listmailbox ["--subscribed"] ["--specialuse"] [pattern [reference]]
196 List all, or all subscribed or special-use, mailboxes matching the
198 specified pattern. The pattern may have embedded wildcards '*' or '%',
199 which match anything or anything except the separator character,
200 respectively.
201 Mailboxes returned will be relative to the specified reference if one
203 is specified. This allows a mailbox list to be limited to a particular
204 hierarchy.
205 In some cases when the '%' wildcard is used to end a pattern, it may
207 match an entry which is not a mailbox but which contains other
208 mailboxes. In this case, the entry will be parenthesized to indicate
209 that it is a root for other mailboxes, as opposed to a mailbox itself.
210 aliases: "list", "lm"
212 listquota
214 listquota root
215 List quotas on specified root. If the specified mailbox path does not
217 have a quota assigned, an error will be raised; see "listquotaroot" for
218 a way to find the quota root for a mailbox.
219 aliases: "lq"
221 listquotaroot
223 listquotaroot mailbox
224 Show quota roots and quotas for mailbox
226 aliases: "lqm", "lqr"
228 mboxconfig
230 mboxconfig ["--private"] mailbox attribute value
231 Set mailbox metadata, optionally set the private instead of the shared
233 version of the metadata. A value of "none" will remove the attribute.
234 The currently supported attributes are:
236 "comment" description
238 Sets a comment or description associated with the mailbox.
239 "expire" days
241 Sets the number of days after which messages will be expired from
242 the mailbox.
243 "news2mail" address
245 Sets an email address to which messages injected into the server
246 via NNTP will be sent.
247 "pop3showafter" time
249 Sets a time (in RFC3501 format, for example "6-Jan-2011 11:45:32
250 +1100") which specifies a cutoff date such that POP3 fetching of
251 the folder does not see messages whose internaldate is before or
252 equal to the date.
253 "sharedseen" true|false
255 Enables the use of a shared \Seen flag on messages rather than a
256 per-user \Seen flag. The 's' right in the mailbox ACL still
257 controls whether a user can set the shared \Seen flag.
258 "sieve" scriptname
260 Indicates the name of the global sieve script that should be run
261 when a message is delivered to the shared mailbox (not used for
262 personal mailboxes).
263 "squat" true|false
265 Indicates that the mailbox should have a squat index created for
266 it.
267 aliases: "mboxcfg"
269 reconstruct
271 reconstruct ["-r"] mailbox
272 Reconstruct the specified mailbox, optionally recursing and
274 reconstructing child mailboxes if the "-r" flag is given.
275 For more information see reconstruct(8).
277 renamemailbox
279 renamemailbox ["--partition" partition] oldname newname
280 renamemailbox oldname newname [partition]
282 Rename the specified mailbox, optionally moving it to a different
284 partition. Both old-style and getopt-style usages are accepted;
285 combining them will produce an error.
286 aliases: "rename", "renm"
288 server
290 server
291 server [--noauthenticate] [server]
293 With no arguments, show the current server. With an argument, connect
295 to that server. It will prompt for automatic login unless the
296 "--noauthenticate" option is specified. (This may change; in
297 particular, either automatic authentication will be removed or all
298 "authenticate" options will be added.)
299 When connected to a server, cyradm's prompt changes from "cyradm>" to
301 "servername>", where servername is the fully qualified domain name of
302 the connected server.
303 aliases: "connect", "servername"
305 setaclmailbox
307 setaclmailbox mailbox id rights [id rights ...]
308 Set ACLs on a mailbox. The ACL may be one of the special strings
310 "none", "read" ("lrs"), "post" ("lrsp"), "append" ("lrsip"), "write"
311 ("lrswipkxte"), "delete" ("lrxte"), or "all" ("lrswipkxte"), or any
312 combinations of the ACL codes:
313 l Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
315 r Read (SELECT/EXAMINE the mailbox, perform STATUS)
317 s Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during
319 APPEND/COPY/FETCH BODY[...])
320 w Write flags other than \SEEN and \DELETED
322 i Insert (APPEND, COPY destination)
324 p Post (send mail to mailbox)
326 k Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in
328 RENAME)
329 x Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
331 t Delete messages (set/clear \DELETED flag via STORE, also set
333 \DELETED flag during APPEND/COPY)
334 e Perform EXPUNGE and expunge as part of CLOSE
336 a Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
338 aliases: "setacl", "sam"
340 setinfo
342 setinfo attribute value
343 Set server metadata. A value of "none" will remove the attribute. The
345 currently supported attributes are:
346 "motd" message
348 Sets a "message of the day". The message gets displayed as an
349 ALERT upon connection.
350 "comment" note
352 Sets a comment or description associated with the server.
353 "admin" address
355 Sets the administrator email address for the server.
356 "shutdown" message
358 Sets a shutdown message. The message gets displayed as an ALERT
359 and all users are disconnected from the server (subsequent logins
360 are disallowed).
361 "expire" days
363 Sets the number of days after which messages will be expired from
364 the server (unless overridden by a mailbox annotation).
365 "squat" true|false
367 Indicates that all mailboxes should have a squat indexes created
368 for them (unless overridden by a mailbox annotation).
369 setquota
371 setquota root resource value [resource value ...]
372 Set a quota on the specified root, which may or may not be an actual
374 mailbox. The resources understood by Cyrus are "STORAGE", "MESSAGE",
375 "X-NUM-FOLDERS" and "X-ANNOTATION-STORAGE". The storage units are, as
376 defined in RFC 2087, groups of 1024 octets (i.e. Kilobytes). The value
377 may be the special string "none" which will remove the quota.
378 aliases: "sq"
380 subscribe
382 subscribe mailbox
383 Subscribe to the given mailbox.
385 unsubscribe
387 unsubscribe mailbox
388 Unsubscribe to the given mailbox.
390 version
392 version
393 Display the version info of the current server.
395 aliases: "ver"
397 xfermailbox
399 xfermailbox ["--partition" partition] mailbox server
400 xfermailbox mailbox server [partition]
402 Transfer (relocate) the specified mailbox to a different server. Both
404 old-style and getopt-style usages are accepted; combining them will
405 produce an error.
406 aliases: "xfer"
408
410 GNU-style long options must be given in their entirety; Tcl-style
411 options may be abbreviated.
412 Tcl-style options are provided as a compatibility feature. They will
414 probably go away in the future.
415 Multiple commands can be given on a line, separated by ';' characters.
417 All commands set an exit status, which at present is not useful.
419 Unknown commands are passed to a subshell for execution.
421 The Tcl version of cyradm is used for scripting as well as
423 interactively. While this is possible to a limited extent by use of
424 the "run" method, scripting would normally be done with
425 "Cyrus::IMAP::Admin", which is far more flexible than either
426 interactive "cyradm" or the Tcl scripting mechanism for Cyrus.
427 cyradm understands /bin/sh-style redirection: any command can have its
429 standard or error output redirected, with all sh-style redirections
430 (except "<>") supported. It does not currently understand pipes or
431 backgrounding.
432 If the "Term::Readline::Perl" or "Term::Readline::GNU" modules are
434 available, cyradm will use it.
435 An alias facility is implemented internally, but no access is currently
437 provided to it. This will change, if only to allow some of the
438 predefined aliases to be removed if they conflict with useful shell
439 commands.
440
442 Brandon S. Allbery, allbery@ece.cmu.edu
443
445 Cyrus::IMAP::Admin, Term::ReadLine, sh(1), perl(1), imapd(8),
446 imapd.conf(5), reconstruct(8)
447perl v5.26.3 2018-05-18 IMAP::Shell(3)