COMMANDS FOR TCL SCRIPTS


OPTIONS
-file script


Execute commands from script.

-user user

-u user

Log in to the server as user.

Short form of -user user.

-layers number
Specify the maximum allowable protection layer for the connection. 0 corresponds to no protec-
tion, 1 to integrity protection, and more for n bits of privacy protection. Default is 10000, allowing
virtually any protection mechanism.

-l number Short form of -layers prot.

-mech mechanism
Specify the SASL mechanism to use for authentication.

-m mechanism
Short form of -mech mechanism.

DESCRIPTION
Cyradm is a simple Tcl-based administrative client for the Cyrus IMAP server. If invoked with a script, cyradm reads Tcl commands from the file script and evaluates them.

If invoked with host, cyradm runs in interactive mode, connecting to host on port port, authenticating, and then reading commands from the standard input and evaluating them. Port defaults to the standard IMAP port. Cyradm runs until the exit command is invoked or until it reaches end-of-file on its standard input. If the file .cyradmrc is in the home directory of the user, cyradm evaluates the file as a Tcl script just before reading the first command from standard input, after connecting and authenticating to server.

INTERACTIVE COMMANDS
The following commands are available only in interactive mode. In all commands, a mailbox or root of ``.'' speci- fies the same mailbox used previously in that connection.

createmailbox mailbox [partition]
The createmailbox (or cm) command creates a new mailbox named mailbox. The optional partition argu-
ment specifies the partition name on which to create the mailbox.

deletemailbox mailbox
The deletemailbox (or dm) command deletes the named mailbox.

Since administrators don't have implicit delete rights on all mailboxes, they may need to use setaclmailbox to
give themselves delete rights before trying to delete a mailbox.

renamemailbox mailbox newmailbox [partition]
The renamemailbox (or renm) command renames the named mailbox to newmailbox. The optional parti-
tion
argument specifies the partition name on which to move the mailbox.

listmailbox [-subscribed] [pattern] [reference]
The listmailbox (or lm) command returns a list of mailbox names matching the string pattern. If pattern is
omitted, it defaults to ``*''. The optional reference argument specifies the reference name relative to which
pattern is then interpreted.

Two wildcard characters are defined in pattern. The ``*'' wildcard matches zero or more characters. The
``%'' wildcard is like the ``*'' wildcard except that it will not match the hierarchy separator, ``.''. For exam-
ple, 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.

In some cases, where ``%'' is used as the last character of a pattern, non-mailbox names are listed in paren-
theses. 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 not exist, then ``(user.foo.bar)'' is listed.

setaclmailbox mailbox identifier rights [identifier rights]...
The setaclmailbox (or sam) command modifies the access control list of the mailbox mailbox. One or more
identifier-rights pairs may be given after mailbox, each sets the ACL for identifier to rights.

Rights may be a set of access right letters:

l

r

lookup (mailbox is visible to LIST/LSUB/UNSEEN commands)

read (SELECT the mailbox, perform CHECK, FETCH, PARTIAL, SEARCH, COPY
from mailbox)

s

w

i

p

c

d

a

keep seen/unseen information across sessions (STORE \SEEN flag)

write (STORE flags other than \SEEN and \DELETED)

insert (perform APPEND, COPY into mailbox)

post (send mail to submission address for mailbox)

create (CREATE new sub-mailboxes in any implementation-defined hierarchy)

delete (STORE \DELETED flag, perform EXPUNGE)

administer (perform SETACL)

or one of the following words:

none

read

post

append

write

all

""

lrs

lrsp

lrsip

lrswipcd

lrswipcda

deleteaclmailbox mailbox identifier [identifier]...
The deleteaclmailbox (or dam) command modifies the access control list of mailbox. One or more identi-
fier
s may be specified, each identifier has its access control entry removed.

listaclmailbox mailbox
The listaclmailbox (or lam) command returns a string containing the access control list of the mailbox mail-
box
.

setquota root quota...
The setquota (or sq) command sets the limit on the quota root root to quota. The quota is one of the follow-
ing:

-

-

A single numeric value, limiting the use of storage to that value

A list of one or more resource-value pairs, limiting the use of each given resource to the given numeric
value. The Cyrus server does not support resources other than storage.

-

none, specifying no limits whatsoever

listquota root
The listquota (or lq) command returns a string listing the quotas on the quota root root.

listquotaroot mailbox
The listquotaroot (or lqr or lqm) command returns a string listing the quota roots and quotas on the mailbox
mailbox.

quit Same as the Tcl command exit. Close the connection and exit cyradm.

COMMANDS FOR TCL SCRIPTS

Cyradm adds one command to the standard Tcl command set.

cyradm connect connection [host] [port]
The cyradm connect command opens a connection to host and creates a new Tcl command connection that
may be used to invoke various operations on the connection. Host defaults to connection and port defaults to
the standard IMAP port.

The cyradm connect command returns its connection argument.

connection servername
Returns the name of the host that connection is connected to.

connection authenticate [switches]
Authenticates the connection. Switches are:

-user user

-pwcommand script

Log in to the server as user.

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 user- name and the password. Before executing the script, the authenticate command will replace %-sequences as follows:

%%

%h

%u

replaced with a single %

replaced with the hostname of the server

replaced with the value of the -user switch, or the empty string if the -user
switch was not given

-layers number

-mech mechanism

Specify allowable protection mechanisms for the connection; see above.

Specify the SASL mechanism to use, if not plaintext login.

connection createmailbox mailbox [partition]
Creates a mailbox on connection. Arguments are the same as for the interactive version of the command.

connection deletemailbox mailbox
Delete a mailbox on connection. Arguments are the same as for the interactive version of the command.

connection renamemailbox mailbox newmailbox [partition]
Renames a mailbox on connection. Arguments are the same as for the interactive version of the command.

connection listmailbox [-subscribed] pattern [reference]
Returns a list describing mailboxes on connection matching pattern. The optional reference argument speci-
fies the reference name relative to which pattern is then interpreted.

The -subscribed switch limits the returned mailboxes to those to which the user has subscribed.

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.

connection setaclmailbox mailbox identifier rights [...]
Modifies an access control list on connection. Arguments are the same as for the interactive version of the
command.

connection deleteaclmailbox mailbox identifier [...]
Modifies an access control list on connection. Arguments are the same as for the interactive version of the
command.

connection listaclmailbox mailbox
Returns a list containing the access control list of the mailbox mailbox on connection. The returned list con-
tains alternating identifier right pairs.

connection setquota root [resource limit]...
Sets the limit on the quota root root on connection. Zero or more resource limit pairs may be specified, spec-
ifying the limit for each resource.

connection listquota root
Returns a list containing the quotas of the quota root root on connection. The returned list contains zero or
more resource usage limit triplets.

connection listquotaroot mailbox
Returns a list containing the quota roots and quotas on the mailbox mailbox on connection. The returned list
contains zero or more sublists; each sublist contains the name of a quota root followed by zero or more
resource usage limit triplets.