1CYRADM(1)             User Contributed Perl Documentation            CYRADM(1)
2
3
4

NAME

6       cyradm - Cyrus administration shell, alter ego of Cyrus::IMAP::Shell
7

SYNOPSIS

9         $ cyradm [--user user] [--[no]rc] [--systemrc file] [--userrc file] \
10         > [--port n] [--auth mechanism] [--tlskey keyfile] [--notls] \
11         > [--cafile cacertfile] [--cadir cacertdir] \
12         > [--server] server
13
14       but possibly
15
16         $ perl -MCyrus::IMAP::Shell -e 'run("myscript")'
17
18       or even (not recommended)
19
20         use Cyrus::IMAP::Admin::Shell;
21
22         run('myscriptname');
23

DESCRIPTION

25       This module implements cyradm in Perl.  It is a shell around
26       Cyrus::IMAP::Admin.  Commands are provided in both Tcl-compatible forms
27       and GNU-style long option forms.
28

COMMANDS

30       "authenticate" ["--minssf" N] ["--maxssf" N] ["--mechanisms" list]
31       ["--service" name] ["--tlskey" keyfile] ["--notls"] ["--cafile"
32       cacertfile] ["--capath" cacertdir] [user]
33       "auth" ["--minssf" N] ["--maxssf" N] ["--mechanisms" list] ["--service"
34       name] ["--tlskey" keyfile] ["--notls"] ["--cafile" cacertfile]
35       ["--capath" cacertdir] [user]
36       "login" ["--minssf" N] ["--maxssf" N] ["--mechanisms" list]
37       ["--service" name] ["--tlskey" keyfile] ["--notls"] ["--cafile"
38       cacertfile] ["--capath" cacertdir] [user]
39           Authenticate to server.  You must already be connected to a server
40           and Cyrus imapd will refuse to allow you to re-authenticate once
41           you have authenticated once.
42
43       "chdir" directory
44       "cd" directory
45           Change directory.  A "pwd" builtin is not provided, but the default
46           command action will run "pwd" from a shell if invoked.
47
48       "createmailbox" ["--partition" partition] ["--specialuse" specialuse]
49       mailbox
50       "create" ["--partition" partition] ["--specialuse" specialuse] mailbox
51       "create" ["--specialuse" specialuse] mailbox partition
52       "cm" ["--partition" partition] ["--specialuse" specialuse] mailbox
53       "cm" ["--specialuse" specialuse] mailbox partition
54           Create a mailbox on the default or a specified partition.  Both
55           old-style and getopt-style usages are accepted (combining them will
56           produce an error).  Optionally assign a special use to the mailbox.
57
58       "deleteaclmailbox" mailbox id [...]
59       "deleteacl" mailbox id [...]
60       "dam" mailbox id [...]
61           Remove ACLs from the specified mailbox.
62
63       "deletemailbox" mailbox
64       "delete" mailbox
65       "dm" mailbox
66           Delete the specified mailbox.
67
68           Administrators do not have implicit delete rights on mailboxes.
69           Use the setaclmailbox command to grant the "x" permission to your
70           principal if you need to delete a mailbox you do not own.
71
72           Note that the online help admits to an optional host argument.
73           This argument is not currently used, and will be rejected with an
74           error if specified; it is reserved for IMSP.
75
76       "disconnect"
77       "disc"
78           Disconnect from the current server.  The prompt will revert to
79           "cyradm>".
80
81       "exit" [number]
82       "quit" [number]
83           Exit cyradm, optionally with a specific exit status; the exit
84           status of the last command will be used if one is not specified.
85
86       help [command]
87       ? [command]
88           Show help for "command" or all commands.
89
90       "getmetadata" [mailbox]
91       "getmd" [mailbox]
92           Display mailbox/server metadata
93
94       "info" [mailbox]
95           Display the mailbox/server annotations.
96
97       "listaclmailbox" mailbox
98       "listacl" mailbox
99       "lam" mailbox
100           List ACLs on the specified mailbox.
101
102       "listmailbox" ["--subscribed"] ["--specialuse"] [pattern [reference]]
103       "list" ["--subscribed"] ["--specialuse"] [pattern [reference]]
104       "lm" ["--subscribed"] ["--specialuse"] [pattern [reference]]
105           List all, or all subscribed or special-use, mailboxes matching the
106           specified pattern.  The pattern may have embedded wildcards '*' or
107           '%', which match anything or anything except the separator
108           character, respectively.
109
110           Mailboxes returned will be relative to the specified reference if
111           one is specified.  This allows a mailbox list to be limited to a
112           particular hierarchy.
113
114           In some cases when the '%' wildcard is used to end a pattern, it
115           may match an entry which is not a mailbox but which contains other
116           mailboxes.  In this case, the entry will be parenthesized to
117           indicate that it is a root for other mailboxes, as opposed to a
118           mailbox itself.
119
120       "listquota" root
121       "lq" root
122           List quotas on specified root.  If the specified mailbox path does
123           not have a quota assigned, an error will be raised; see
124           listquotaroot for a way to find the quota root for a mailbox.
125
126       "listquotaroot" mailbox
127       "lqm" mailbox
128       "lqr" mailbox?
129           show quota roots and quotas for mailbox
130
131       "mboxconfig" ["--private"] mailbox attribute value
132       "mboxcfg" ["--private"] mailbox attribute value
133           Set mailbox metadata, optionally set the private instead of the
134           shared version of the metadata. A value of "none" will remove the
135           attribute.
136
137           The currently supported attributes are:
138
139           "comment"
140               Sets a comment or description associated with the mailbox.
141
142           "expire"
143               Sets the number of days after which messages will be expired
144               from the mailbox.
145
146           "news2mail"
147               Sets an email address to which messages injected into the
148               server via NNTP will be sent.
149
150           "pop3showafter"
151               Sets a time (in RFC3501 format, for example "6-Jan-2011
152               11:45:32 +1100") which specifies a cutoff date such that POP3
153               fetching of the folder does not see messages whose internaldate
154               is before or equal to the date.
155
156           "sharedseen"
157               Enables the use of a shared \Seen flag on messages rather than
158               a per-user \Seen flag.  The 's' right in the mailbox ACL still
159               controls whether a user can set the shared \Seen flag.
160
161           "sieve"
162               Indicates the name of the global sieve script that should be
163               run when a message is delivered to the shared mailbox (not used
164               for personal mailboxes).
165
166           "squat"
167               Indicates that the mailbox should have a squat index created
168               for it.
169
170           "/explicit/annotation"
171               Sets the annotation /explicit/annotation on mailbox to value.
172
173       "renamemailbox" ["--partition" partition] oldname newname
174       "rename" ["--partition" partition] oldname newname
175       "renm" ["--partition" partition] oldname newname
176       "renamemailbox" oldname newname [partition]
177       "rename" oldname newname [partition]
178       "renm" oldname newname [partition]
179           Rename the specified mailbox, optionally moving it to a different
180           partition.  Both old-style and getopt-style usages are accepted;
181           combining them will produce an error.
182
183       server [--noauthenticate] [server]
184       connect [--noauthenticate] [server]
185       servername [--noauthenticate] [server]
186           With no arguments, show the current server.  With an argument,
187           connect to that server.  It will prompt for automatic login unless
188           the "--noauthenticate" option is specified.  (This may change; in
189           particular, either automatic authentication will be removed or all
190           "authenticate" options will be added.)
191
192           When connected to a server, the cyradm prompt changes from
193           "cyradm>" to "servername>", where servername is the fully qualified
194           domain name of the connected server.
195
196       "setaclmailbox" mailbox id rights [id rights ...]
197       "setacl" mailbox id rights [id rights ...]
198       "sam" mailbox id rights [id rights ...]
199           Set ACLs on a mailbox.  The ACL may be one of the special strings
200           "none", "read" ("lrs"), "post" ("lrsp"), "append" ("lrsip"),
201           "write" ("lrswipkxten"), "delete" ("lrxten"), or "all"
202           ("lrswipkxten"), or any combinations of the ACL codes:
203
204           l   Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
205
206           r   Read (SELECT/EXAMINE the mailbox, perform STATUS)
207
208           s   Seen (set/clear \SEEN flag via STORE, also set \SEEN flag
209               during
210                   APPEND/COPY/FETCH BODY[...])
211
212           w   Write flags other than \SEEN and \DELETED
213
214           i   Insert (APPEND, COPY destination)
215
216           p   Post (send mail to mailbox)
217
218           k   Create mailbox (CREATE new sub-mailboxes, parent for new
219               mailbox in RENAME)
220
221           x   Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
222
223           t   Delete messages (set/clear \DELETED flag via STORE, also set
224               \DELETED
225                   flag during APPEND/COPY)
226
227           e   Perform EXPUNGE and expunge as part of CLOSE
228
229           a   Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
230
231           n   Add, delete or modify annotations
232
233       "setinfo" attribute value
234           Set server metadata.  A value of "none" will remove the attribute.
235           The currently supported attributes are:
236
237           "motd"
238               Sets a "message of the day".  The message gets displayed as an
239               ALERT after authentication.
240
241           "comment"
242               Sets a comment or description associated with the server.
243
244           "admin"
245               Sets the administrator email address for the server.
246
247           "shutdown"
248               Sets a shutdown message.  The message gets displayed as an
249               ALERT and all users are disconnected from the server
250               (subsequent logins are disallowed).
251
252           "expire"
253               Sets the number of days after which messages will be expired
254               from the server (unless overridden by a mailbox annotation).
255
256           "squat"
257               Indicates that all mailboxes should have a squat indexes
258               created for them (unless overridden by a mailbox annotation).
259
260       "setmetadata" [--private] mailbox [annotation] value
261       "setmd" [--private] mailbox [annotation] value
262           Set metadata on mailbox, where <annotation> is one of
263           [comment|expire|news2mail|pop3showafter|sharedseen|sieve|specialuse|
264           squat|/<explicit annotation>].
265
266           Note that flags with a leading backslash must be escaped with an
267           additional backslash.  For example:
268
269             setmetadata --private Spam specialuse "\\Junk"
270
271           Note, too, that "private" annotations are private to the user
272           currently authenticated as, not necessarily the owner of the
273           mailbox.  To set annotations for another user you must authorize as
274           that user.
275
276           In addition to the use of optional flag --private, one may use a
277           more explicit syntax, prefixing the annotation with '/shared/' or
278           '/private/' as in this example:
279
280             setmetadata Spam /private/specialuse "\\Junk"
281
282       "setquota" root resource value [resource value ...]
283       "sq" root resource value [resource value ...]
284           Set a quota on the specified root, which may or may not be an
285           actual mailbox.  The only resource understood by Cyrus is
286           "STORAGE".  The value may be the special string "none" which will
287           remove the quota.
288
289       "version"
290       "ver"
291           Display the version info of the current server.
292
293       "xfermailbox" ["--partition" partition] mailbox server
294       "xfer" ["--partition" partition] mailbox server
295       "xfermailbox" mailbox server [partition]
296       "xfer" mailbox server [partition]
297           Transfer (relocate) the specified mailbox to a different server.
298           Both old-style and getopt-style usages are accepted; combining them
299           will produce an error.
300

NOTES

302       GNU-style long options must be given in their entirety; Tcl-style
303       options may be abbreviated.
304
305       Tcl-style options are provided as a compatibility feature.  They will
306       probably go away in the future.
307
308       Multiple commands can be given on a line, separated by ';' characters.
309
310       All commands set an exit status, which at present is not useful.
311
312       Unknown commands are passed to a subshell for execution.
313
314       The Tcl version of cyradm is used for scripting as well as
315       interactively.  While this is possible to a limited extent by use of
316       the "run" method, scripting would normally be done with
317       "Cyrus::IMAP::Admin", which is far more flexible than either
318       interactive "cyradm" or the Tcl scripting mechanism for Cyrus.
319
320       cyradm understands /bin/sh-style redirection:  any command can have its
321       standard or error output redirected, with all sh-style redirections
322       (except "<>") supported.  It does not currently understand pipes or
323       backgrounding.
324
325       If the "Term::Readline::Perl" or "Term::Readline::GNU" modules are
326       available, cyradm will use it.
327
328       An alias facility is implemented internally, but no access is currently
329       provided to it.  This will change, if only to allow some of the
330       predefined aliases to be removed if they conflict with useful shell
331       commands.
332

AUTHOR

334       Brandon S. Allbery, allbery@ece.cmu.edu
335

SEE ALSO

337       Cyrus::IMAP::Admin Term::ReadLine sh(1), perl(1), imapd(8).
338
339
340
341perl v5.36.0                      2022-08-01                         CYRADM(1)
Impressum