Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IMAP::Shell(3)	      User Contributed Perl Documentation	IMAP::Shell(3)

       Cyrus::IMAP::Shell - Perl version of cyradm

	 $ cyradm [--user authid] [--authz authzid] [--[no]rc] [--systemrc file] [--userrc file] \
	 > [--port n] [--auth mechanism] [--server] server

       but possibly

	 $ perl	-MCyrus::IMAP::Shell -e	'run("myscript")'

       or even (not recommended)

	 use Cyrus::IMAP::Admin::Shell;


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

       The ``cyradm`` utility is a simple command line for performing common
       administrative tasks on a Cyrus IMAP server, written in Perl.

       The cyradm utility can either be	executed from a	client where it	has
       been installed and connect to the server	via IMAP or it can be executed
       locally via a shell on the server.

       cyradm understands /bin/sh-style	redirection: any command can have its
       standard	or error output	redirected, with all sh-style redirections
       (except \<\>) supported.	It does	not currently understand pipes or

       If the Term::Readline::Perl or Term::Readline::GNU modules are
       available, cyradm will use it.

       "--u", "--user" user
	   Authenticate	with the specified username.

       "--authz" user
	   Authorize the connection as being the specified username.

       "--norc", "--rc"
	   (Do not) load the configuration files.

       "--systemrc" file
	   Use the system configuration	file specified.

       "--userrc" file
	   Use the user	configuration file specified.

       "--port"	port
	   Connect to the *server* specified on	the port specified.

       "--auth"	mechanism
	   Use the mechanism specified to authenticate.	One of PLAIN, LOGIN,
	   DIGEST-MD5, etc.

	   Show	a help message about these command-line	options.

	   Display the version of Cyrus	IMAP the current ``cyradm`` command is
	   a part of.

       "--server" server
	   The server address to connect to.

       authenticate ["--minssf"	N] ["--maxssf" N] ["--mechanisms" list]
       ["--service" name] ["--tlskey" keyfile] ["--notls"] ["--cafile"
       cacertfile] ["--capath" cacertdir] user

       Authenticate to server.	You must already be connected to a server and
       Cyrus imapd will	refuse to allow	you to re-authenticate once you	have
       authenticated once.

       aliases:	"auth",	"login"

       chdir directory

       Change directory.  A "pwd" builtin is not provided, but the default
       command action will run "pwd" from a shell if invoked.

       aliases:	"cd"

       createmailbox ["--partition" partition] ["--specialuse" specialuse]

       createmailbox ["--specialuse" specialuse] mailbox partition

       Create a	mailbox	on the default or a specified partition.  Both old-
       style and getopt-style usages are accepted (combining them will produce
       an error).  Optionally assign a special use to the mailbox.

       New mailboxes inherit the ACL permissions of their parent mailbox,
       except for top-level mailboxes such as the user's INBOX.	Mailboxes that
       are the user's INBOX are	assigned all to	the corresponding user.

       Example Usage
	       localhost> :command:`cm user.john`
	       localhost> :command:`lm`
	       user.john (\HasNoChildren)
	       localhost> :command:`lam	user.john`
	       john lrswipkxtecda

	   Note	that in	the above example, the "unixhierarchysep" setting in
	   imapd.conf is set to	0. When	using the UNIX hierarchy separator,
	   the "/" (forward slash) character would be used as the hierarchy
	   separator, and the example would look as follows:

       Example Usage with "unixhierarchysep: 1"
	       localhost> :command:`cm user/john`
	       localhost> :command:`lm`
	       user/john (\HasNoChildren)
	       localhost> :command:`lam	user/john`
	       john lrswipkxtecda

	   The above examples use the unqualified, shorthand user identifier
	   john	as the mailbox name.

	   With	the use	of virtual domains, controlled through the
	   "virtdomains" setting in imapd.conf(5).

       aliases:	"cm", "create"

       deleteaclmailbox	mailbox	id [...]

       Remove ACLs from	the specified mailbox.

       aliases:	"delteacl", "dam"

       deletemailbox mailbox

       Delete the specified mailbox.

       Administrators do not have implicit delete rights on mailboxes.	Use
       the "setaclmailbox" command to grant the	"x" permission to your
       principal if you	need to	delete a mailbox you do	not own.

       Note that the online help admits	to an optional host argument.  This
       argument	is not currently used, and will	be rejected with an error if
       specified; it is	reserved for IMSP.

       aliases:	"delete", "dm"


       Disconnect from the current server.  The	prompt will revert to
       "cyradm>".  This	does not quit cyradm.

       aliases:	"disc"

       exit [number]

       Exit "cyradm", optionally with a	specific exit status; the exit status
       of the last command will	be used	if one is not specified.

       aliases:	"quit"

       help [command]

       Show help for "command" or all commands.

       aliases:	"?"

       getmetadata [mailbox]

       Display mailbox/server metadata

       aliases:	"getmd"

       info [mailbox]

       Display the mailbox/server annotations.

       listaclmailbox mailbox

       List ACLs on the	specified mailbox.

       aliases:	"lam", "listacl"

       listmailbox ["--subscribed"] ["--specialuse"] [pattern [reference]]

       List all, or all	subscribed or special-use, mailboxes matching the
       specified pattern.  The pattern may have	embedded wildcards '*' or '%',
       which match anything or anything	except the separator character,

       Mailboxes returned will be relative to the specified reference if one
       is specified.  This allows a mailbox list to be limited to a particular

       In some cases when the '%' wildcard is used to end a pattern, it	may
       match an	entry which is not a mailbox but which contains	other
       mailboxes.  In this case, the entry will	be parenthesized to indicate
       that it is a root for other mailboxes, as opposed to a mailbox itself.

       aliases:	"list",	"lm"

       listquota root

       List quotas on specified	root.  If the specified	mailbox	path does not
       have a quota assigned, an error will be raised; see "listquotaroot" for
       a way to	find the quota root for	a mailbox.

       aliases:	"lq"

       listquotaroot mailbox

       Show quota roots	and quotas for mailbox

       aliases:	"lqm", "lqr"

       mboxconfig ["--private"]	mailbox	attribute value

       Set mailbox metadata, optionally	set the	private	instead	of the shared
       version of the metadata.	A value	of "none" will remove the attribute.

       The currently supported attributes are:

       "comment" description
	   Sets	a comment or description associated with the mailbox.

       "expire"	days
	   Sets	the number of days after which messages	will be	expired	from
	   the mailbox.

       "news2mail" address
	   Sets	an email address to which messages injected into the server
	   via NNTP will be sent.

       "pop3showafter" time
	   Sets	a time (in RFC3501 format, for example "6-Jan-2011 11:45:32
	   +1100") which specifies a cutoff date such that POP3	fetching of
	   the folder does not see messages whose internaldate is before or
	   equal to the	date.

       "sharedseen" true|false
	   Enables the use of a	shared \Seen flag on messages rather than a
	   per-user \Seen flag.	 The 's' right in the mailbox ACL still
	   controls whether a user can set the shared \Seen flag.

       "sieve" scriptname
	   Indicates the name of the global sieve script that should be	run
	   when	a message is delivered to the shared mailbox (not used for
	   personal mailboxes).

       "squat" true|false
	   Indicates that the mailbox should have a squat index	created	for

       aliases:	"mboxcfg"

       reconstruct ["-r"] mailbox

       Reconstruct the specified mailbox, optionally recursing and
       reconstructing child mailboxes if the "-r" flag is given.

       For more	information see	reconstruct(8).

       renamemailbox ["--partition" partition] oldname newname

       renamemailbox oldname newname [partition]

       Rename the specified mailbox, optionally	moving it to a different
       partition.  Both	old-style and getopt-style usages are accepted;
       combining them will produce an error.

       aliases:	"rename", "renm"


       server [--noauthenticate] [server]

       With no arguments, show the current server.  With an argument, connect
       to that server.	It will	prompt for automatic login unless the
       "--noauthenticate" option is specified.	(This may change; in
       particular, either automatic authentication will	be removed or all
       "authenticate" options will be added.)

       When connected to a server, cyradm's prompt changes from	"cyradm>" to
       "servername>", where servername is the fully qualified domain name of
       the connected server.

       aliases:	"connect", "servername"

       setaclmailbox mailbox id	rights [id rights ...]

       Set ACLs	on a mailbox.  The ACL may be one of the special strings
       "none", "read" ("lrs"), "post" ("lrsp"),	"append" ("lrsip"), "write"
       ("lrswipkxte"), "delete"	("lrxte"), or "all" ("lrswipkxte"), or any
       combinations of the ACL codes:

       l   Lookup (mailbox is visible to LIST/LSUB, SUBSCRIBE mailbox)

       r   Read	(SELECT/EXAMINE	the mailbox, perform STATUS)

       s   Seen	(set/clear \SEEN flag via STORE, also set \SEEN	flag during

       w   Write flags other than \SEEN	and \DELETED

       i   Insert (APPEND, COPY	destination)

       p   Post	(send mail to mailbox)

       k   Create mailbox (CREATE new sub-mailboxes, parent for	new mailbox in

       x   Delete mailbox (DELETE mailbox, old mailbox name in RENAME)

       t   Delete messages (set/clear \DELETED flag via	STORE, also set
	   \DELETED flag during	APPEND/COPY)

       e   Perform EXPUNGE and expunge as part of CLOSE


       aliases:	"setacl", "sam"

       setinfo attribute value

       Set server metadata.  A value of	"none" will remove the attribute.  The
       currently supported attributes are:

       "motd" message
	   Sets	a "message of the day".	 The message gets displayed as an
	   ALERT upon connection.

       "comment" note
	   Sets	a comment or description associated with the server.

       "admin" address
	   Sets	the administrator email	address	for the	server.

       "shutdown" message
	   Sets	a shutdown message.  The message gets displayed	as an ALERT
	   and all users are disconnected from the server (subsequent logins
	   are disallowed).

       "expire"	days
	   Sets	the number of days after which messages	will be	expired	from
	   the server (unless overridden by a mailbox annotation).

       "squat" true|false
	   Indicates that all mailboxes	should have a squat indexes created
	   for them (unless overridden by a mailbox annotation).

       setmetadata [--private] mailbox [annotation] value

       Set metadata on mailbox,	where annotation is one	of
       squat|/<explicit	annotation>].

       Note that value with a leading backslash	must be	escaped	with an
       additional backslash.  For example:

	 setmetadata --private Spam specialuse "\\Junk"

       Note, too, that "private" annotations are private to the	user currently
       authenticated as, not necessarily the owner of the mailbox.  To set
       annotations for another user you	must authorize as that user.

       In addition to the use of optional flag --private, one may use a	more
       explicit	syntax,	prefixing the annotation with '/shared/' or
       '/private/' as in this example:

	 setmetadata Spam /private/specialuse "\\Junk"

       aliases:	"setmd"

       setquota	root resource value [resource value ...]

       Set a quota on the specified root, which	may or may not be an actual
       mailbox.	The resources understood by Cyrus are "STORAGE", "MESSAGE",
       "X-NUM-FOLDERS" and "X-ANNOTATION-STORAGE".  The	storage	units are, as
       defined in RFC 2087, groups of 1024 octets (i.e.	 Kilobytes). The value
       may be the special string "none"	which will remove the quota.

       aliases:	"sq"

       subscribe mailbox

       Subscribe to the	given mailbox.

       unsubscribe mailbox

       Unsubscribe to the given	mailbox.


       Display the version info	of the current server.

       aliases:	"ver"

       xfermailbox ["--partition" partition] mailbox server

       xfermailbox mailbox server [partition]

       Transfer	(relocate) the specified mailbox to a different	server.	 Both
       old-style and getopt-style usages are accepted; combining them will
       produce an error.

       aliases:	"xfer"

       GNU-style long options must be given in their entirety; Tcl-style
       options may be abbreviated.

       Tcl-style options are provided as a compatibility feature.  They	will
       probably	go away	in the future.

       Multiple	commands can be	given on a line, separated by ';' characters.

       All commands set	an exit	status,	which at present is not	useful.

       Unknown commands	are passed to a	subshell for execution.

       The Tcl version of cyradm is used for scripting as well as
       interactively.  While this is possible to a limited extent by use of
       the "run" method, scripting would normally be done with
       "Cyrus::IMAP::Admin", which is far more flexible	than either
       interactive "cyradm" or the Tcl scripting mechanism for Cyrus.

       cyradm understands /bin/sh-style	redirection:  any command can have its
       standard	or error output	redirected, with all sh-style redirections
       (except "<>") supported.	 It does not currently understand pipes	or

       If the "Term::Readline::Perl" or	"Term::Readline::GNU" modules are
       available, cyradm will use it.

       An alias	facility is implemented	internally, but	no access is currently
       provided	to it.	This will change, if only to allow some	of the
       predefined aliases to be	removed	if they	conflict with useful shell

       Brandon S. Allbery,

       Cyrus::IMAP::Admin, Term::ReadLine, sh(1), perl(1), imapd(8),
       imapd.conf(5), reconstruct(8)

perl v5.32.1			  2021-09-01			IMAP::Shell(3)


Want to link to this manual page? Use this URL:

home | help