1IMAP::Shell(3)        User Contributed Perl Documentation       IMAP::Shell(3)
2
3
4

NAME

6       Cyrus::IMAP::Shell - Perl version of cyradm
7

SYNOPSIS

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

DESCRIPTION

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

COMMAND-LINE ARGUMENTS

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

COMMANDS

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       aliases: "delete", "dm"
154
155   disconnect
156       disconnect
157
158       Disconnect from the current server.  The prompt will revert to
159       "cyradm>".  This does not quit cyradm.
160
161       aliases: "disc"
162
163   exit
164       exit [number]
165
166       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
169       aliases: "quit"
170
171   help
172       help [command]
173
174       Show help for "command" or all commands.
175
176       aliases: "?"
177
178   getmetadata
179       getmetadata [mailbox]
180
181       Display mailbox/server metadata
182
183       aliases: "getmd"
184
185   info
186       info [mailbox]
187
188       Display the mailbox/server annotations.
189
190   listaclmailbox
191       listaclmailbox mailbox
192
193       List ACLs on the specified mailbox.
194
195       aliases: "lam", "listacl"
196
197   listmailbox
198       listmailbox ["--subscribed"] ["--specialuse"] [pattern [reference]]
199
200       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
205       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
209       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
214       aliases: "list", "lm"
215
216   listquota
217       listquota root
218
219       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
223       aliases: "lq"
224
225   listquotaroot
226       listquotaroot mailbox
227
228       Show quota roots and quotas for mailbox
229
230       aliases: "lqm", "lqr"
231
232   mboxconfig
233       mboxconfig ["--private"] mailbox attribute value
234
235       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
238       The currently supported attributes are:
239
240       "comment" description
241           Sets a comment or description associated with the mailbox.
242
243       "expire" days
244           Sets the number of days after which messages will be expired from
245           the mailbox.
246
247       "news2mail" address
248           Sets an email address to which messages injected into the server
249           via NNTP will be sent.
250
251       "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
257       "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
262       "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
267       "squat" true|false
268           Indicates that the mailbox should have a squat index created for
269           it.
270
271       aliases: "mboxcfg"
272
273   reconstruct
274       reconstruct ["-r"] mailbox
275
276       Reconstruct the specified mailbox, optionally recursing and
277       reconstructing child mailboxes if the "-r" flag is given.
278
279       For more information see reconstruct(8).
280
281   renamemailbox
282       renamemailbox ["--partition" partition] oldname newname
283
284       renamemailbox oldname newname [partition]
285
286       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
290       aliases: "rename", "renm"
291
292   server
293       server
294
295       server [--noauthenticate] [server]
296
297       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
303       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
307       aliases: "connect", "servername"
308
309   setaclmailbox
310       setaclmailbox mailbox id rights [id rights ...]
311
312       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
317       l   Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
318
319       r   Read (SELECT/EXAMINE the mailbox, perform STATUS)
320
321       s   Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during
322           APPEND/COPY/FETCH BODY[...])
323
324       w   Write flags other than \SEEN and \DELETED
325
326       i   Insert (APPEND, COPY destination)
327
328       p   Post (send mail to mailbox)
329
330       k   Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in
331           RENAME)
332
333       x   Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
334
335       t   Delete messages (set/clear \DELETED flag via STORE, also set
336           \DELETED flag during APPEND/COPY)
337
338       e   Perform EXPUNGE and expunge as part of CLOSE
339
340       a   Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
341
342       aliases: "setacl", "sam"
343
344   setinfo
345       setinfo attribute value
346
347       Set server metadata.  A value of "none" will remove the attribute.  The
348       currently supported attributes are:
349
350       "motd" message
351           Sets a "message of the day".  The message gets displayed as an
352           ALERT upon connection.
353
354       "comment" note
355           Sets a comment or description associated with the server.
356
357       "admin" address
358           Sets the administrator email address for the server.
359
360       "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
365       "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
369       "squat" true|false
370           Indicates that all mailboxes should have a squat indexes created
371           for them (unless overridden by a mailbox annotation).
372
373   setmetadata
374       setmetadata [--private] mailbox [annotation] value
375
376       Set metadata on mailbox, where annotation is one of
377       [comment|expire|news2mail|pop3showafter|sharedseen|sieve|specialuse|
378       squat|/<explicit annotation>].
379
380       Note that value with a leading backslash must be escaped with an
381       additional backslash.  For example:
382
383         setmetadata --private Spam specialuse "\\Junk"
384
385       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
389       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
393         setmetadata Spam /private/specialuse "\\Junk"
394
395       aliases: "setmd"
396
397   setquota
398       setquota root resource value [resource value ...]
399
400       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
406       aliases: "sq"
407
408   subscribe
409       subscribe mailbox
410
411       Subscribe to the given mailbox.
412
413   unsubscribe
414       unsubscribe mailbox
415
416       Unsubscribe to the given mailbox.
417
418   version
419       version
420
421       Display the version info of the current server.
422
423       aliases: "ver"
424
425   xfermailbox
426       xfermailbox ["--partition" partition] mailbox server
427
428       xfermailbox mailbox server [partition]
429
430       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
434       aliases: "xfer"
435

NOTES

437       GNU-style long options must be given in their entirety; Tcl-style
438       options may be abbreviated.
439
440       Tcl-style options are provided as a compatibility feature.  They will
441       probably go away in the future.
442
443       Multiple commands can be given on a line, separated by ';' characters.
444
445       All commands set an exit status, which at present is not useful.
446
447       Unknown commands are passed to a subshell for execution.
448
449       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
455       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
460       If the "Term::Readline::Perl" or "Term::Readline::GNU" modules are
461       available, cyradm will use it.
462
463       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

AUTHOR

469       Brandon S. Allbery, allbery@ece.cmu.edu
470

SEE ALSO

472       Cyrus::IMAP::Admin, Term::ReadLine, sh(1), perl(1), imapd(8),
473       imapd.conf(5), reconstruct(8)
474
475
476
477perl v5.36.0                      2023-01-22                    IMAP::Shell(3)
Impressum