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       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

NOTES

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

AUTHOR

473       Brandon S. Allbery, allbery@ece.cmu.edu
474

SEE ALSO

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)
Impressum