Using the Kolab Command-Line

The kolab command-line is a powerful administration utility allowing you to quickly execute standard administrative tasks.

acl-cleanup

Iterate over all mailboxes and cleans up the ACL. Useful in deployments where any ACI may be used with setting the ACE, because identifier verification is disabled or otherwise unavailable.

It is important to appreciate that an ACE for doe@example.org is not removed when the user doe@example.org is removed – when a new user is created with a result attribute value of doe@example.org, this user implicitly has the access specified by the ACE.

add-domain

This command adds a new domain name space to Kolab Groupware.

Synopsis

kolab add-domain [options] <domain>

Command-Line Options

domain

The domain to add.

--alias domain

Add the domain as an alias for the domain specified as --alias.

add-user-subscription

Subscribes a user to a folder.

Synopsis

kolab add-user-subscription <user> <pattern>

Command-Line Options

user

Subscribe the specified user.

Note

The user will be subscribed only if the user also has rights to the folder.

pattern

Subscribe the user specified to mailboxes matching the specified pattern.

cm

Short-hand for create-mailbox.

create-mailbox

Create a mailbox or mail folder.

Synopsis

kolab create-mailbox [options] <mailbox>

Command-Line Options

mailbox

The mailbox to create.

--metadata KEY=VALUE

Set the metadata KEY for the mailbox or mail folder to VALUE. Specify once for each pair of KEY=VALUE.

See /etc/imapd.annotations.conf for valid KEYs, the permissions required to set them, namespaces and the format of the VALUE.

--partition=PARTITION

New in version pykolab-0.6.11.

Specify the Cyrus IMAP partition on which to create the mailbox. If not specified, uses the defaultpartition configured in imapd.conf(5).

Example Usage

Create a new mail folder for user John Doe:

# kolab create-mailbox "user/john.doe/New@example.org"

Create a new calendar for user John Doe:

# kolab create-mailbox \
    --metadata=/shared/vendor/kolab/folder-type=event \
    "user/john.doe/New Calendar@example.org"

Create a new default calendar folder for user John Doe.

Note

Only one default calendar folder may exist.

# kolab create-mailbox \
    --user john.doe@example.org \
    --metadata=/private/vendor/kolab/folder-type=event.default \
    "New Calendar"

dam

Short-hand for delete-mailbox-acl

delete-mailbox (dm)

Delete a mailbox.

Synopsis

kolab delete-mailbox <pattern>

Command-Line Options

pattern

Delete all mailboxes matching pattern.

Example Usage

Delete a mail folder for user John Doe:

# kolab delete-mailbox "user/john.doe/Trash/Oops@example.org"

Delete all non-INBOX folders for user John Doe:

# kolab delete-mailbox "user/jane.doe/%@example.org"

delete-mailbox-acl

Delete an ACE for a mailbox.

Command-Line Options

pattern

Delete the ACE from mailboxes matching the specified pattern.

subject

Delete the ACE for this subject.

lam

Short-hand for list-mailbox-acls

list-deleted-mailboxes

Synopsis

kolab list-deleted-mailboxes [pattern]

Command-Line Options

pattern

List deleted mailboxes matching the specified pattern.

--server server

Connect to the IMAP server at address <SERVER> instead of the configured IMAP server.

list-mailbox-acls

Command-Line Options

pattern

List the ACL for mailboxes matching the specified pattern.

list-mailbox-metadata

Command-Line Options

--user user

List the mailbox metadata logged in as the user, enabling the examination of the /private metadata namespace in addition to the /shared namespace.

list-mailboxes (lm)

Command-Line Options

--server server

Connect to the IMAP server at address <SERVER> instead of the configured IMAP server.

list-user-subscriptions

Command-Line Options

user

The user identifier to list the (un)subscribed folders for.

--unsubscribed

List folders the user is not subscribed to, instead of subscribed folders.

rename-mailbox

Renames a mailbox or sub-folder.

Synopsis

kolab rename-mailbox <source> <target> [<partition>]

Command-Line Options

source

Source mailbox name.

target

Target mailbox name.

partition

Optional partition name.

rm

Short-hand for rename-mailbox

sam

Short-hand for set-mailbox-acl

set-mailbox-acl

Sets an access control entry (ACE) for a given subject.

Synopsis

kolab set-mailbox-acl <pattern> <subject> <rights>

Command-Line Options

pattern

Apply the ACE to mailboxes matching the specified pattern.

subject

Set the ACE for the subject specified.

rights

The ACE subject is getting these rights.

In addition to the regular IMAP access right identifiers, the kolab command- line takes the following rights:

all

Full rights, including administration. The IMAP equivalent is lrswipkxtecda.

read-only

Read-only rights, with the IMAP equivalent being lrs.

read-write

Permissions most suitable for access to a (shared) groupware folder.

The rights allow a subject to modify groupware contents, such as marking tasks as completed.

The IMAP equivalent is lrswited.

semi-full

Allow the subject to insert new message (copies), such as groupware content, and flag current messages as deleted.

Also allow the subject to maintain flags other than the system flags \Seen and \Deleted (such as \Flagged).

Note that the rights do not include the right to EXPUNGE the folder, meaning that messages therein remain available.

The IMAP equivalent is lrswit.

full

Everything but administrator rights, so that the subject cannot modify the access control on the folder.

Example Usage

Set the access rights for john.doe@example.org to administer a folder shared/contacts@example.org:

# kolab sam shared/contacts@example.org john.doe@example.org all

Give access to jane.doe@example.org to read and write contacts in a folder shared/contacts@example.org:

# kolab sam shared/contacts@example.org jane.doe@example.org read-write

set-mailbox-metadata

Command-Line Options

--user user

Set the mailbox metadata logged in as the user, enabling the modification of the /private metadata namespace annotation values.

summarize-quota-allocation (sqa)

Summarize all quota allocation for all mailboxes.

Command-Line Options

--server server

Connect to the IMAP server at address <SERVER> instead of the configured IMAP server.

sync

Synchronize IMAP.

Command-Line Options

--resync

Resync.

--threads THREADS

Number of threads.

transfer-mailbox

Transfer a mailbox from the server it is currently on, to the server you specify.

Warning

Transferring mailboxes may take quite a bit of time, depending on the connection speed between the two IMAP servers, and the size of a mailbox (tree).

Make sure that despite your workstation’s session possibly being interrupted, the command can continue, by using screen(1) for example.

Synopsis

kolab transfer-mailbox <mailbox> <server>

Command-Line Options

mailbox

Transfer the mailbox specified, such as user/john.doe@example.org.

server

Transfer the mailboxes to the server specified.

Example Usage

Transfer mailbox user/john.doe@example.org currently on IMAP server imap1.example.org over to IMAP server imap2.example.org:

# kolab transfer-mailbox user/john.doe@example.org imap2.example.org

undelete-mailbox

Recovers mailboxes previously deleted.

Synopsis

kolab undelete-mailbox [options] <mailbox> [<target>]

Command-Line Options

mailbox

Mailbox may be a string representing either of the following two options - the fully qualified path of the deleted folder in its current location (e.g. “DELETED/user/userid/hex[@domain]”) or the original folder name, such as “user/userid[@domain]”.

target

Target may be the target folder to “undelete” the deleted folder to. If not specified, the original folder name is used.

--dry-run

Do not actually execute, but state what would have been executed.

user-info

This command retrieves information about a user from the Web Administration Panel API (places a user.info API call), and prints all attributes for the corresponding user type.

Synopsis

kolab user-info <address>

Command-Line Options

address

The primary or secondary recipient email address for the user, that is globally unique, such as john.doe@example.org.

Sieve Operations

sieve-list

Retrieves list of sieve scripts of a user.

Synopsis

kolab sieve-list <email>

sieve-put

Put a sieve script to a user mailbox.

Synopsis

kolab sieve-put <email> <file> <script_name>

sieve-refresh

Refresh a user’s managed and contributed sieve scripts. It will re-generate sieve scripts content according to LDAP attributes of the user record and KE#14 in a way defined in sievemgmt plugin of kolab daemon.

Synopsis

kolab sieve-refresh <email>

sieve-test

Syntactically checks sieve scripts of a user.

Synopsis

kolab sieve-test <email>