.\" -*- nroff -*-
.\"
.\" Copyright (c) 2000 Carnegie Mellon University. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" 3. The name "Carnegie Mellon University" must not be used to
.\" endorse or promote products derived from this software without
.\" prior written permission. For permission or any other legal
.\" details, please contact
.\" Office of Technology Transfer
.\" Carnegie Mellon University
.\" 5000 Forbes Avenue
.\" Pittsburgh, PA 15213-3890
.\" (412) 268-4387, fax: (412) 268-7395
.\" tech-transfer@andrew.cmu.edu
.\"
.\" 4. Redistributions of any form whatsoever must retain the following
.\" acknowledgment:
.\" "This product includes software developed by Computing Services
.\" at Carnegie Mellon University (http://www.cmu.edu/computing/)."
.\"
.\" CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
.\" THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
.\" FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
.\" AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
.\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" $Id: cyradm.1,v 1.1.1.1 2003/11/06 21:14:17 dasenbro Exp $
.\"
.\" The definitions below are for supplemental macros used in Tcl/Tk
.\" manual entries.
.\"
.\" .HS name section [date [version]]
.\" Replacement for .TH in other man pages. See below for valid
.\" section names.
.\"
.\" .AP type name in/out [indent]
.\" Start paragraph describing an argument to a library procedure.
.\" type is type of argument (int, etc.), in/out is either "in", "out",
.\" or "in/out" to describe whether procedure reads or modifies arg,
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
.\" needed; use .AS below instead)
.\"
.\" .AS [type [name]]
.\" Give maximum sizes of arguments for setting tab stops. Type and
.\" name are examples of largest possible arguments that will be passed
.\" to .AP later. If args are omitted, default tab stops are used.
.\"
.\" .BS
.\" Start box enclosure. From here until next .BE, everything will be
.\" enclosed in one large box.
.\"
.\" .BE
.\" End of box enclosure.
.\"
.\" .VS
.\" Begin vertical sidebar, for use in marking newly-changed parts
.\" of man pages.
.\"
.\" .VE
.\" End of vertical sidebar.
.\"
.\" .DS
.\" Begin an indented unfilled display.
.\"
.\" .DE
.\" End of indented unfilled display.
.\"
'\" # Heading for Tcl/Tk man pages
.de HS
.ds ^3 \\0
.if !"\\$3"" .ds ^3 \\$3
.if '\\$2'cmds' .TH \\$1 1 \\*(^3 \\$4
.if '\\$2'lib' .TH \\$1 3 \\*(^3 \\$4
.if '\\$2'tcl' .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
.if '\\$2'tk' .TH \\$1 n \\*(^3 Tk "Tk Commands"
.if '\\$2'tclc' .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
.if '\\$2'tkc' .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
.if '\\$2'tclcmds' .TH \\$1 1 \\*(^3 Tcl "Tcl Applications"
.if '\\$2'tkcmds' .TH \\$1 1 \\*(^3 Tk "Tk Applications"
.if t .wh -1.3i ^B
.nr ^l \\n(.l
.ad b
..
'\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
'\" # BS - start boxed text
'\" # ^y = starting y location
'\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\" # VS - start vertical sidebar
'\" # ^Y = starting y location
'\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\" # Special macro to handle page bottom: finish off current
'\" # box/sidebar if in box/sidebar mode, then invoked standard
'\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\" # DS - begin display
.de DS
.RS
.nf
.sp
..
'\" # DE - end display
.de DE
.fi
.RE
.sp .5
..
.HS cyradm tclcmds
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
cyradm \- Cyrus administrative client
.SH SYNOPSIS
\fBcyradm -file\fI script\fR
.br
\fBcyradm\fR [\fB-user \fIuser\fR] [\fB-protection \fIprot\fR]
\fIhost\fR [\fIport\fR]
.BE
.SH OPTIONS
.IP "\fB\-file \fIscript\fR" 15
Execute commands from \fIscript\fR.
.IP "\fB\-user \fIuser\fR" 15
Log in to the server as \fIuser\fR.
.IP "\fB\-u \fIuser\fR" 15
Short form of \fB-user\fI user\fR.
.IP "\fB\-layers \fInumber\fR" 15
Specify the maximum allowable protection layer for the connection. 0
corresponds to no protection, 1 to integrity protection, and more for
n bits of privacy protection. Default is 10000, allowing virtually
any protection mechanism.
.IP "\fB\-l \fInumber\fR" 15
Short form of \fB-layers\fI prot\fR.
.IP "\fB\-mech \fImechanism\fR" 15
Specify the SASL mechanism to use for authentication.
.IP "\fB\-m \fImechanism\fR" 15
Short form of \fB-mech\fI mechanism\fR.
.SH DESCRIPTION
.PP
\fBCyradm\fR is a simple Tcl-based administrative client for the Cyrus IMAP
server. If invoked with a script, \fBcyradm\fR reads Tcl commands
from the file \fIscript\fR and evaluates them.
.PP
If invoked with \fIhost\fR, \fBcyradm\fR runs in interactive
mode, connecting to \fIhost\fR on port \fIport\fR, authenticating, and
then reading commands from the standard input and evaluating
them. \fIPort\fR defaults to the standard IMAP port. \fBCyradm\fR
runs until the \fBexit\fR command is invoked or until it reaches
end-of-file on its standard input. If the file \fB.cyradmrc\fR
is in the home directory of the user, \fBcyradm\fR
evaluates the file as a Tcl script just before reading the first
command from standard input, after connecting and authenticating to
\fIserver\fR.
.SH "INTERACTIVE COMMANDS"
.PP
The following commands are available only in interactive mode.
In all commands, a \fImailbox\fR or \fIroot\fR of ``.'' specifies the
same mailbox used previously in that connection.
.IP "\fBcreatemailbox \fImailbox\fR [\fIpartition\fR]" 5
The \fBcreatemailbox\fR (or \fBcm\fR) command creates a new mailbox
named \fImailbox\fR. The optional \fIpartition\fR argument
specifies the partition name on which to create the mailbox.
.IP "\fBdeletemailbox \fImailbox\fR" 5
The \fBdeletemailbox\fR (or \fBdm\fR) command deletes the named mailbox.
.IP
Since administrators don't have implicit delete rights on all
mailboxes, they may need to use \fBsetaclmailbox\fR
to give themselves delete rights before trying to delete a mailbox.
.IP "\fBrenamemailbox \fImailbox newmailbox\fR [\fIpartition\fR]" 5
The \fBrenamemailbox\fR (or \fBrenm\fR) command renames the named
mailbox to \fInewmailbox\fR. The optional
\fIpartition\fR argument specifies the partition name on which to move
the mailbox.
.IP "\fBlistmailbox [\fI-subscribed\fR] [\fIpattern\fR] [\fIreference\fR]" 5
The \fBlistmailbox\fR (or \fBlm\fR) command returns a list of mailbox names matching
the string \fIpattern\fR. If \fIpattern\fR is omitted, it defaults to
``*''. The optional \fIreference\fR argument specifies the
reference name relative to which \fIpattern\fR is then interpreted.
.IP
Two wildcard characters are defined in \fIpattern\fR. The ``*''
wildcard matches zero or more characters. The ``%'' wildcard is like
the ``*'' wildcard except that it will not match the hierarchy
separator, ``.''. For example, if ``listmailbox user.foo.%'' is
specified, and the mailboxes ``user.foo.bar'' and
``user.foo.bar.old'' both exist, then ``user.foo.bar'' is listed, but
``user.foo.bar.old'' is not.
.IP
In some cases, where ``%'' is used as the last character of a pattern,
non-mailbox names are listed in parentheses. This indicates that the
name is not actually a mailbox, yet there are sub-mailboxes underneath
that name. For example, if ``listmailbox user.foo.%'' is specified,
and the mailbox ``user.foo.bar.old'' exists, but ``user.foo.bar'' does
\fBnot\fR exist, then ``(user.foo.bar)'' is listed.
.IP "\fBsetaclmailbox \fImailbox identifier rights\fR [\fIidentifier rights\fR]..." 5
The \fBsetaclmailbox\fR (or \fBsam\fR) command modifies the access
control list of the mailbox \fImailbox\fR. One or more
\fIidentifier\fR-\fIrights\fR pairs may be given after
\fImailbox\fR, each sets the ACL for \fIidentifier\fR to \fIrights\fR.
.IP
\fIRights\fR may be a set of access right letters:
.RS 4
.IP \fBl\fR
lookup (mailbox is visible to LIST/LSUB/UNSEEN commands)
.IP \fBr\fR
read (SELECT the mailbox, perform CHECK, FETCH, PARTIAL,
SEARCH, COPY from mailbox)
.IP \fBs\fR
keep seen/unseen information across sessions (STORE \\SEEN flag)
.IP \fBw\fR
write (STORE flags other than \\SEEN and \\DELETED)
.IP \fBi\fR
insert (perform APPEND, COPY into mailbox)
.IP \fBp\fR
post (send mail to submission address for mailbox)
.IP \fBc\fR
create (CREATE new sub-mailboxes in any implementation-defined
hierarchy)
.IP \fBd\fR
delete (STORE \\DELETED flag, perform EXPUNGE)
.IP \fBa\fR
administer (perform SETACL)
.PP
or one of the following words:
.IP \fBnone\fR 10
""
.IP \fBread\fR
lrs
.IP \fBpost\fR
lrsp
.IP \fBappend\fR
lrsip
.IP \fBwrite\fR
lrswipcd
.IP \fBall\fR
lrswipcda
.RE
.IP "\fBdeleteaclmailbox \fImailbox identifier\fR [\fIidentifier\fR]..." 5
The \fBdeleteaclmailbox\fR (or \fBdam\fR) command modifies the access
control list of \fImailbox\fR. One or more \fIidentifier\fRs may be
specified, each \fIidentifier\fR has its access control entry removed.
.IP "\fBlistaclmailbox \fImailbox\fR" 5
The \fBlistaclmailbox\fR (or \fBlam\fR) command returns a string
containing the access control list of the mailbox \fImailbox\fR.
.IP "\fBsetquota \fIroot quota\fR..." 5
The \fBsetquota\fR (or \fBsq\fR) command sets the limit on the quota
root \fIroot\fR to \fIquota\fR. The \fIquota\fR is one of the
following:
.RS 5
.IP - 3
A single numeric value, limiting the use of storage to that value
.IP - 3
A list of one or more \fIresource\fR-\fIvalue\fR pairs, limiting the
use of each given \fIresource\fR to the given numeric \fIvalue\fR.
The Cyrus server does not support resources other than storage.
.IP - 3
\fBnone\fR, specifying no limits whatsoever
.RE
.IP "\fBlistquota \fIroot\fR" 5
The \fBlistquota\fR (or \fBlq\fR) command returns a string
listing the quotas on the quota root \fIroot\fR.
.IP "\fBlistquotaroot \fImailbox\fR" 5
The \fBlistquotaroot\fR (or \fBlqr\fR or \fBlqm\fR) command returns a string
listing the quota roots and quotas on the mailbox \fImailbox\fR.
.IP "\fBquit\fR" 5
Same as the Tcl command \fBexit\fR. Close the connection and exit
\fBcyradm\fR.
.SH "COMMANDS FOR TCL SCRIPTS"
\fBCyradm\fR adds one command to the standard Tcl command set.
.IP "\fBcyradm connect\fI connection\fR [\fIhost\fR] [\fIport\fR]" 5
The \fBcyradm connect\fR command opens a connection to \fIhost\fR and
creates a new Tcl command \fIconnection\fR that may be used to invoke
various operations on the connection. \fIHost\fR defaults to
\fIconnection\fR and \fIport\fR defaults to the standard IMAP port.
.IP
The \fBcyradm connect\fR command returns its \fIconnection\fR
argument.
.IP "\fIconnection\fB servername\fR" 5
Returns the name of the host that \fIconnection\fR is connected to.
.IP "\fIconnection\fB authenticate\fR [\fIswitches\fB]" 5
Authenticates the connection. Switches are:
.RS 5
.IP "\fB-user\fI user\fR"
Log in to the server as \fIuser\fR.
.IP "\fB-pwcommand\fI script\fR"
Attempt a plaintext password login.
The argument is a Tcl script which is executed to obtain the login
information--the script must return a list with two elements,
the username and the password. Before executing the script, the
authenticate command will replace %-sequences as follows:
.RS 7
.IP %%
replaced with a single %
.IP %h
replaced with the hostname of the server
.IP %u
replaced with the value of the \fB-user\fR switch, or the
empty string if the \fB-user\fR switch was not given
.RE
.IP "\fB-layers\fI number\fR"
Specify allowable protection mechanisms for the connection; see above.
.IP "\fB-mech\fI mechanism\fR"
Specify the SASL mechanism to use, if not plaintext login.
.RE
.IP "\fIconnection\fB createmailbox \fImailbox\fR [\fIpartition\fR]" 5
Creates a mailbox on \fIconnection\fR. Arguments are the same as for
the interactive version of the command.
.IP "\fIconnection\fB deletemailbox \fImailbox\fR" 5
Delete a mailbox on \fIconnection\fR. Arguments are the same as for
the interactive version of the command.
.IP "\fIconnection\fB renamemailbox \fImailbox newmailbox\fR [\fIpartition\fR]" 5
Renames a mailbox on \fIconnection\fR. Arguments are the same as for
the interactive version of the command.
.IP "\fIconnection\fB listmailbox [\fI-subscribed\fR] \fIpattern\fR [\fIreference\fR]" 5
Returns a list describing mailboxes on
\fIconnection\fR matching \fIpattern\fR. The optional \fIreference\fR
argument specifies the reference name relative to which \fIpattern\fR
is then interpreted.
.IP
The \fB-subscribed\fR switch limits the returned
mailboxes to those to which the user has subscribed.
.IP
The returned value contains a list with one entry for each matching
mailbox. Each entry is a list containing three elements, the name,
a list of mailbox attributes, and the hierarchy delimiter. If
there is no hierarchy delimiter, the third element is the empty
string.
.IP "\fIconnection\fB setaclmailbox \fImailbox identifier rights\fR [...]" 5
Modifies an access control list on \fIconnection\fR. Arguments are
the same as for the interactive version of the command.
.IP "\fIconnection\fB deleteaclmailbox \fImailbox identifier\fR [...]" 5
Modifies an access control list on \fIconnection\fR. Arguments are
the same as for the interactive version of the command.
.IP "\fIconnection\fB listaclmailbox \fImailbox\fR" 5
Returns a list containing the access control list of the mailbox
\fImailbox\fR on \fIconnection\fR. The returned list contains
alternating \fIidentifier right\fR pairs.
.IP "\fIconnection\fB setquota \fIroot\fR [\fIresource limit\fR]..." 5
Sets the limit on the quota root \fIroot\fR
on \fIconnection\fR. Zero or more \fIresource limit\fR pairs may be
specified, specifying the limit for each resource.
.IP "\fIconnection\fB listquota \fIroot\fR" 5
Returns a list containing the quotas of the quota root \fIroot\fR on
\fIconnection\fR. The returned list contains zero or more \fIresource
usage limit\fR triplets.
.IP "\fIconnection\fB listquotaroot\fI mailbox\fR" 5
Returns a list containing the quota roots and quotas on the mailbox
\fImailbox\fR on \fIconnection\fR. The returned list contains zero or
more sublists; each sublist contains the name of a quota root followed
by zero or more \fIresource usage limit\fR triplets.