Debian Codegraph @

doc/html/_sources/imap/reference/manpages/systemcommands/cyradm.rst.txt

raw
1
2 ##########
3 **cyradm**
4 ##########
5
6
7 .. DO NOT EDIT cyradm.rst: Autogenerated by tools/perl2rst from cyrus-imapd\perl\imap\IMAP\Shell.pm
8
9 .. cyrusman:: cyradm(8)
10
11 .. _imap-reference-manpages-systemcommands-cyradm:
12
13 ****
14 NAME
15 ****
16
17
18 Cyrus::IMAP::Shell - Perl version of cyradm
19
20
21 ********
22 SYNOPSIS
23 ********
24
25
26
27 .. code-block:: perl
28
29 $ cyradm [--user authid] [--authz authzid] [--[no]rc] [--systemrc file] [--userrc file] \
30 > [--port n] [--auth mechanism] [--server] server
31
32
33 but possibly
34
35
36 .. code-block:: perl
37
38 $ perl -MCyrus::IMAP::Shell -e 'run("myscript")'
39
40
41 or even (not recommended)
42
43
44 .. code-block:: perl
45
46 use Cyrus::IMAP::Admin::Shell;
47
48 run('myscriptname');
49
50
51
52 ***********
53 DESCRIPTION
54 ***********
55
56
57 This module implements \ **cyradm**\ in Perl. It is a shell around
58 `Cyrus::IMAP::Admin <http://search.cpan.org/search?query=Cyrus%3a%3aIMAP%3a%3aAdmin&mode=module>`_. Commands are provided in both Tcl-compatible
59 forms and GNU-style long option forms.
60
61 The \`\`cyradm\`\` utility is a simple command line for performing common
62 administrative tasks on a Cyrus IMAP server, written in Perl.
63
64 The cyradm utility can either be executed from a client where it has been
65 installed and connect to the server via IMAP or it can be executed
66 locally via a shell on the server.
67
68 cyradm understands /bin/sh-style redirection: any command can have its
69 standard or error output redirected, with all sh-style redirections
70 (except \<\>) supported. It does not currently understand pipes or
71 backgrounding.
72
73 If the `Term::Readline::Perl <http://search.cpan.org/search?query=Term%3a%3aReadline%3a%3aPerl&mode=module>`_ or `Term::Readline::GNU <http://search.cpan.org/search?query=Term%3a%3aReadline%3a%3aGNU&mode=module>`_ modules are
74 available, cyradm will use it.
75
76
77 **********************
78 COMMAND-LINE ARGUMENTS
79 **********************
80
81
82
83 - \ ``--u``\ , \ ``--user``\ \ *user*\
84
85 Authenticate with the specified username.
86
87
88
89 - \ ``--authz``\ \ *user*\
90
91 Authorize the connection as being the specified username.
92
93
94
95 - \ ``--norc``\ , \ ``--rc``\
96
97 (Do not) load the configuration files.
98
99
100
101 - \ ``--systemrc``\ \ *file*\
102
103 Use the system configuration file specified.
104
105
106
107 - \ ``--userrc``\ \ *file*\
108
109 Use the user configuration file specified.
110
111
112
113 - \ ``--port``\ \ *port*\
114
115 Connect to the \*server\* specified on the port specified.
116
117
118
119 - \ ``--auth``\ \ *mechanism*\
120
121 Use the mechanism specified to authenticate. One of PLAIN, LOGIN, etc.
122
123
124
125 - \ ``--help``\
126
127 Show a help message about these command-line options.
128
129
130
131 - \ ``--version``\
132
133 Display the version of Cyrus IMAP the current \`\`cyradm\`\` command is a part of.
134
135
136
137 - \ ``--server``\ \ *server*\
138
139 The server address to connect to.
140
141
142
143
144 ********
145 COMMANDS
146 ********
147
148
149 .. _imap-reference-manpages-systemcommands-cyradm-authenticate:
150
151 authenticate
152 ============
153
154
155 \ **authenticate**\ [\ ``--minssf``\ \ *N*\ ] [\ ``--maxssf``\ \ *N*\ ] [\ ``--mechanisms``\ \ *list*\ ] [\ ``--service``\ \ *name*\ ] [\ ``--tlskey``\ \ *keyfile*\ ] [\ ``--notls``\ ] [\ ``--cafile``\ \ *cacertfile*\ ] [\ ``--capath``\ \ *cacertdir*\ ] \ *user*\
156
157 Authenticate to server. You must already be connected to a server and
158 Cyrus imapd will refuse to allow you to re-authenticate once you have
159 authenticated once.
160
161 aliases: \ ``auth``\ , \ ``login``\
162
163 .. _imap-reference-manpages-systemcommands-cyradm-chdir:
164
165
166 chdir
167 =====
168
169
170 \ **chdir**\ \ *directory*\
171
172 Change directory. A \ ``pwd``\ builtin is not provided, but the default command
173 action will run \ ``pwd``\ from a shell if invoked.
174
175 aliases: \ ``cd``\
176
177 .. _imap-reference-manpages-systemcommands-cyradm-createmailbox:
178
179
180 createmailbox
181 =============
182
183
184 \ **createmailbox**\ [\ ``--partition``\ \ *partition*\ ] [\ ``--specialuse``\ \ *specialuse*\ ] \ *mailbox*\
185
186 \ **createmailbox**\ [\ ``--specialuse``\ \ *specialuse*\ ] \ *mailbox*\ \ *partition*\
187
188 Create a mailbox on the default or a specified partition. Both old-style
189 and getopt-style usages are accepted (combining them will produce an error).
190 Optionally assign a special use to the mailbox.
191
192 New mailboxes inherit the ACL permissions of
193 their parent mailbox, except for top-level mailboxes such as the user's
194 INBOX. Mailboxes that are the user's INBOX are assigned all to the
195 corresponding user.
196
197
198 - Example Usage
199
200
201 .. code-block:: perl
202
203 localhost> :command:`cm user.john`
204 localhost> :command:`lm`
205 user.john (\HasNoChildren)
206 localhost> :command:`lam user.john`
207 john lrswipkxtecda
208
209
210 Note that in the above example, the \ ``unixhierarchysep``\ setting in
211 imapd.conf is set to \ ``0``\ . When using the UNIX
212 hierarchy separator, the \ ``/``\ (forward slash) character would be
213 used as the hierarchy separator, and the example would look as
214 follows:
215
216
217
218 - Example Usage with \ ``unixhierarchysep: 1``\
219
220
221 .. code-block:: perl
222
223 localhost> :command:`cm user/john`
224 localhost> :command:`lm`
225 user/john (\HasNoChildren)
226 localhost> :command:`lam user/john`
227 john lrswipkxtecda
228
229
230
231
232 - Note
233
234 The above examples use the unqualified, shorthand user
235 identifier john as the mailbox name.
236
237 With the use of virtual domains, controlled through the
238 \ ``virtdomains``\ setting in imapd.conf(5).
239
240
241
242 aliases: \ ``cm``\ , \ ``create``\
243
244 .. _imap-reference-manpages-systemcommands-cyradm-deleteaclmailbox:
245
246
247 deleteaclmailbox
248 ================
249
250
251 \ **deleteaclmailbox**\ \ *mailbox*\ \ *id*\ [...]
252
253 Remove ACLs from the specified mailbox.
254
255 aliases: \ ``delteacl``\ , \ ``dam``\
256
257 .. _imap-reference-manpages-systemcommands-cyradm-deletemailbox:
258
259
260 deletemailbox
261 =============
262
263
264 \ **deletemailbox**\ \ *mailbox*\
265
266 Delete the specified mailbox.
267
268 Administrators do not have implicit delete rights on mailboxes. Use the
269 `setaclmailbox`_ command to grant the \ ``x``\ permission to your
270 principal if you need to delete a mailbox you do not own.
271
272 aliases: \ ``delete``\ , \ ``dm``\
273
274 .. _imap-reference-manpages-systemcommands-cyradm-disconnect:
275
276
277 disconnect
278 ==========
279
280
281 \ **disconnect**\
282
283 Disconnect from the current server. The prompt will revert to \ ``cyradm>``\ .
284 This does not quit cyradm.
285
286 aliases: \ ``disc``\
287
288 .. _imap-reference-manpages-systemcommands-cyradm-exit:
289
290
291 exit
292 ====
293
294
295 \ **exit**\ [\ *number*\ ]
296
297 Exit \ ``cyradm``\ , optionally with a specific exit status; the exit status of the
298 last command will be used if one is not specified.
299
300 aliases: \ ``quit``\
301
302 .. _imap-reference-manpages-systemcommands-cyradm-help:
303
304
305 help
306 ====
307
308
309 \ **help**\ [command]
310
311 Show help for \ ``command``\ or all commands.
312
313 aliases: \ ``?``\
314
315 .. _imap-reference-manpages-systemcommands-cyradm-getmetadata:
316
317
318 getmetadata
319 ===========
320
321
322 \ **getmetadata**\ [\ *mailbox*\ ]
323
324 Display mailbox/server metadata
325
326 aliases: \ ``getmd``\
327
328 .. _imap-reference-manpages-systemcommands-cyradm-info:
329
330
331 info
332 ====
333
334
335 \ **info**\ [\ *mailbox*\ ]
336
337 Display the mailbox/server annotations.
338
339 .. _imap-reference-manpages-systemcommands-cyradm-listaclmailbox:
340
341
342 listaclmailbox
343 ==============
344
345
346 \ **listaclmailbox**\ \ *mailbox*\
347
348 List ACLs on the specified mailbox.
349
350 aliases: \ ``lam``\ , \ ``listacl``\
351
352 .. _imap-reference-manpages-systemcommands-cyradm-listmailbox:
353
354
355 listmailbox
356 ===========
357
358
359 \ **listmailbox**\ [\ ``--subscribed``\ ] [\ ``--specialuse``\ ] [\ *pattern*\ [\ *reference*\ ]]
360
361 List all, or all subscribed or special-use, mailboxes matching the specified
362 pattern. The pattern may have embedded wildcards \ ``'\*'``\ or \ ``'%'``\ , which
363 match anything or anything except the separator character, respectively.
364
365 Mailboxes returned will be relative to the specified reference if one
366 is specified. This allows a mailbox list to be limited to a particular
367 hierarchy.
368
369 In some cases when the \ ``'%'``\ wildcard is used to end a pattern, it may
370 match an entry which is not a mailbox but which contains other mailboxes.
371 In this case, the entry will be parenthesized to indicate that it is a
372 root for other mailboxes, as opposed to a mailbox itself.
373
374 aliases: \ ``list``\ , \ ``lm``\
375
376 .. _imap-reference-manpages-systemcommands-cyradm-listquota:
377
378
379 listquota
380 =========
381
382
383 \ **listquota**\ \ *root*\
384
385 List quotas on specified root. If the specified mailbox path does not have
386 a quota assigned, an error will be raised; see `listquotaroot`_ for a way to
387 find the quota root for a mailbox.
388
389 aliases: \ ``lq``\
390
391 .. _imap-reference-manpages-systemcommands-cyradm-listquotaroot:
392
393
394 listquotaroot
395 =============
396
397
398 \ **listquotaroot**\ \ *mailbox*\
399
400 Show quota roots and quotas for mailbox
401
402 aliases: \ ``lqm``\ , \ ``lqr``\
403
404 .. _imap-reference-manpages-systemcommands-cyradm-mboxconfig:
405
406
407 mboxconfig
408 ==========
409
410
411 \ **mboxconfig**\ [\ ``--private``\ ] \ *mailbox*\ \ *attribute*\ \ *value*\
412
413 Set mailbox metadata, optionally set the private instead of the shared
414 version of the metadata. A value of "none" will remove the attribute.
415
416 The currently supported attributes are:
417
418
419 - \ ``comment``\ \ *description*\
420
421 Sets a comment or description associated with the mailbox.
422
423
424
425 - \ ``expire``\ \ *days*\
426
427 Sets the number of days after which messages will be expired from the mailbox.
428
429
430
431 - \ ``news2mail``\ \ *address*\
432
433 Sets an email address to which messages injected into the server via NNTP
434 will be sent.
435
436
437
438 - \ ``pop3showafter``\ \ *time*\
439
440 Sets a time (in RFC3501 format, for example "6-Jan-2011 11:45:32 +1100")
441 which specifies a cutoff date such that POP3 fetching of the folder does
442 not see messages whose internaldate is before or equal to the date.
443
444
445
446 - \ ``sharedseen``\ \ *true|false*\
447
448 Enables the use of a shared \Seen flag on messages rather than a
449 per-user \Seen flag. The 's' right in the mailbox ACL still controls
450 whether a user can set the shared \Seen flag.
451
452
453
454 - \ ``sieve``\ \ *scriptname*\
455
456 Indicates the name of the global sieve script that should be run when
457 a message is delivered to the shared mailbox (not used for personal
458 mailboxes).
459
460
461
462 - \ ``squat``\ \ *true|false*\
463
464 Indicates that the mailbox should have a squat index created for it.
465
466
467
468 aliases: \ ``mboxcfg``\
469
470 .. _imap-reference-manpages-systemcommands-cyradm-reconstruct:
471
472
473 reconstruct
474 ===========
475
476
477 \ **reconstruct**\ [\ ``-r``\ ] \ *mailbox*\
478
479 Reconstruct the specified mailbox, optionally recursing and reconstructing child mailboxes if the \ ``-r``\ flag is given.
480
481 For more information see reconstruct(8).
482
483 .. _imap-reference-manpages-systemcommands-cyradm-renamemailbox:
484
485
486 renamemailbox
487 =============
488
489
490 \ **renamemailbox**\ [\ ``--partition``\ \ *partition*\ ] \ *oldname*\ \ *newname*\
491
492 \ **renamemailbox**\ \ *oldname*\ \ *newname*\ [\ *partition*\ ]
493
494 Rename the specified mailbox, optionally moving it to a different partition.
495 Both old-style and getopt-style usages are accepted; combining them will
496 produce an error.
497
498 aliases: \ ``rename``\ , \ ``renm``\
499
500 .. _imap-reference-manpages-systemcommands-cyradm-server:
501
502
503 server
504 ======
505
506
507 \ **server**\
508
509 \ **server**\ \ *[--noauthenticate]*\ \ *[server]*\
510
511 With no arguments, show the current server. With an argument, connect to that
512 server. It will prompt for automatic login unless the \ ``--noauthenticate``\
513 option is specified. (This may change; in particular, either automatic
514 authentication will be removed or all `authenticate`_ options will be added.)
515
516 When connected to a server, \ **cyradm**\ 's prompt changes from \ ``cyradm>``\ to
517 \ ``servername>``\ , where \ *servername*\ is the fully qualified domain name
518 of the connected server.
519
520 aliases: \ ``connect``\ , \ ``servername``\
521
522 .. _imap-reference-manpages-systemcommands-cyradm-setaclmailbox:
523
524
525 setaclmailbox
526 =============
527
528
529 \ **setaclmailbox**\ \ *mailbox*\ \ *id*\ \ *rights*\ [\ *id*\ \ *rights*\ ...]
530
531 Set ACLs on a mailbox. The ACL may be one of the special strings \ ``none``\ ,
532 \ ``read``\ (\ ``lrs``\ ), \ ``post``\ (\ ``lrsp``\ ), \ ``append``\ (\ ``lrsip``\ ), \ ``write``\
533 (\ ``lrswipkxte``\ ), \ ``delete``\ (\ ``lrxte``\ ), or \ ``all``\ (\ ``lrswipkxte``\ ), or
534 any combinations of the ACL codes:
535
536
537 - \ **l**\
538
539 Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)
540
541
542
543 - \ **r**\
544
545 Read (SELECT/EXAMINE the mailbox, perform STATUS)
546
547
548
549 - \ **s**\
550
551 Seen (set/clear \SEEN flag via STORE, also set \SEEN flag during APPEND/COPY/FETCH BODY[...])
552
553
554
555 - \ **w**\
556
557 Write flags other than \SEEN and \DELETED
558
559
560
561 - \ **i**\
562
563 Insert (APPEND, COPY destination)
564
565
566
567 - \ **p**\
568
569 Post (send mail to mailbox)
570
571
572
573 - \ **k**\
574
575 Create mailbox (CREATE new sub-mailboxes, parent for new mailbox in RENAME)
576
577
578
579 - \ **x**\
580
581 Delete mailbox (DELETE mailbox, old mailbox name in RENAME)
582
583
584
585 - \ **t**\
586
587 Delete messages (set/clear \DELETED flag via STORE, also set \DELETED flag during APPEND/COPY)
588
589
590
591 - \ **e**\
592
593 Perform EXPUNGE and expunge as part of CLOSE
594
595
596
597 - \ **a**\
598
599 Administer (SETACL/DELETEACL/GETACL/LISTRIGHTS)
600
601
602
603 aliases: \ ``setacl``\ , \ ``sam``\
604
605 .. _imap-reference-manpages-systemcommands-cyradm-setinfo:
606
607
608 setinfo
609 =======
610
611
612 \ **setinfo**\ \ *attribute*\ \ *value*\
613
614 Set server metadata. A value of "none" will remove the attribute.
615 The currently supported attributes are:
616
617
618 - \ ``motd``\ \ *message*\
619
620 Sets a "message of the day". The message gets displayed as an ALERT upon
621 connection.
622
623
624
625 - \ ``comment``\ \ *note*\
626
627 Sets a comment or description associated with the server.
628
629
630
631 - \ ``admin``\ \ *address*\
632
633 Sets the administrator email address for the server.
634
635
636
637 - \ ``shutdown``\ \ *message*\
638
639 Sets a shutdown message. The message gets displayed as an ALERT and
640 all users are disconnected from the server (subsequent logins are disallowed).
641
642
643
644 - \ ``expire``\ \ *days*\
645
646 Sets the number of days after which messages will be expired from the
647 server (unless overridden by a mailbox annotation).
648
649
650
651 - \ ``squat``\ \ *true|false*\
652
653 Indicates that all mailboxes should have a squat indexes created for
654 them (unless overridden by a mailbox annotation).
655
656
657
658 .. _imap-reference-manpages-systemcommands-cyradm-setmetadata:
659
660
661 setmetadata
662 ===========
663
664
665 \ **setmetadata**\ [--private] mailbox [\ *annotation*\ ] \ *value*\
666
667 Set metadata on mailbox, where \ *annotation*\ is one of
668 [comment|expire|news2mail|pop3showafter|sharedseen|sieve|specialuse|
669 squat|/<explicit annotation>].
670
671 Note that \ *value*\ with a leading backslash must be escaped with an
672 additional backslash. For example:
673
674
675
676 .. code-block:: perl
677
678 setmetadata --private Spam specialuse "\\Junk"
679
680
681 Note, too, that "private" annotations are private to the user currently
682 authenticated as, not necessarily the owner of the mailbox. To set
683 annotations for another user you must authorize as that user.
684
685 In addition to the use of optional flag \ **--private**\ , one may use a more
686 explicit syntax, prefixing the annotation with '/shared/' or '/private/'
687 as in this example:
688
689
690
691 .. code-block:: perl
692
693 setmetadata Spam /private/specialuse "\\Junk"
694
695
696 aliases: \ ``setmd``\
697
698 .. _imap-reference-manpages-systemcommands-cyradm-setquota:
699
700
701 setquota
702 ========
703
704
705 \ **setquota**\ \ *root*\ \ *resource*\ \ *value*\ [\ *resource*\ \ *value*\ ...]
706
707 Set a quota on the specified root, which may or may not be an actual
708 mailbox. The \ *resources*\ understood by \ **Cyrus**\ are \ ``STORAGE``\ ,
709 \ ``MESSAGE``\ , \ ``X-NUM-FOLDERS``\ and \ ``X-ANNOTATION-STORAGE``\ . The storage
710 units are, as defined in RFC 2087, groups of 1024 octets (i.e.
711 Kilobytes). The \ *value*\ may be the special string \ ``none``\ which will
712 remove the quota.
713
714 aliases: \ ``sq``\
715
716 .. _imap-reference-manpages-systemcommands-cyradm-subscribe:
717
718
719 subscribe
720 =========
721
722
723 \ **subscribe**\ \ *mailbox*\
724
725 Subscribe to the given mailbox.
726
727 .. _imap-reference-manpages-systemcommands-cyradm-unsubscribe:
728
729
730 unsubscribe
731 ===========
732
733
734 \ **unsubscribe**\ \ *mailbox*\
735
736 Unsubscribe to the given mailbox.
737
738 .. _imap-reference-manpages-systemcommands-cyradm-version:
739
740
741 version
742 =======
743
744
745 \ **version**\
746
747 Display the version info of the current server.
748
749 aliases: \ ``ver``\
750
751 .. _imap-reference-manpages-systemcommands-cyradm-xfermailbox:
752
753
754 xfermailbox
755 ===========
756
757
758 \ **xfermailbox**\ [\ ``--partition``\ \ *partition*\ ] \ *mailbox*\ \ *server*\
759
760 \ **xfermailbox**\ \ *mailbox*\ \ *server*\ [\ *partition*\ ]
761
762 Transfer (relocate) the specified mailbox to a different server.
763 Both old-style and getopt-style usages are accepted; combining them will
764 produce an error.
765
766 aliases: \ ``xfer``\
767
768
769
770 *****
771 NOTES
772 *****
773
774
775 GNU-style long options must be given in their entirety; Tcl-style options
776 may be abbreviated.
777
778 Tcl-style options are provided as a compatibility feature. They will
779 probably go away in the future.
780
781 Multiple commands can be given on a line, separated by \ ``';'``\ characters.
782
783 All commands set an exit status, which at present is not useful.
784
785 Unknown commands are passed to a subshell for execution.
786
787 The Tcl version of \ **cyradm**\ is used for scripting as well as interactively.
788 While this is possible to a limited extent by use of the \ ``run``\ method,
789 scripting would normally be done with \ ``Cyrus::IMAP::Admin``\ , which is far
790 more flexible than either interactive \ ``cyradm``\ or the Tcl scripting
791 mechanism for Cyrus.
792
793 \ **cyradm**\ understands \ **/bin/sh**\ -style redirection: any command can have
794 its standard or error output redirected, with all \ **sh**\ -style redirections
795 (except \ ``<>``\ ) supported. It does not currently understand pipes
796 or backgrounding.
797
798 If the \ ``Term::Readline::Perl``\ or \ ``Term::Readline::GNU``\ modules are
799 available, \ **cyradm**\ will use it.
800
801 An alias facility is implemented internally, but no access is currently
802 provided to it. This will change, if only to allow some of the predefined
803 aliases to be removed if they conflict with useful shell commands.
804
805
806 ******
807 AUTHOR
808 ******
809
810
811 Brandon S. Allbery, [email protected]
812
813
814 ********
815 SEE ALSO
816 ********
817
818
819 Cyrus::IMAP::Admin,
820 Term::ReadLine,
821 sh(1), perl(1), imapd(8), imapd.conf(5), reconstruct(8)
822
823 :cyrusman:`imapd(8)`, :cyrusman:`imapd.conf(5)`, :cyrusman:`reconstruct(8)`.
824