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