ZCS Administrator's Guide, Network Edition 4.0
Table of Contents Previous Next Index


Appendix A   Command-Line Utilities

Appendix A   Command-Line Utilities
Command Line Interface (CLI) can be used to create, modify and delete certain features and functions of the Zimbra Collaboration Suite. The administration console is the main tool for maintaining the Zimbra Collaboration Suite, but some functions can only be changed from the CLI utility.
The CLI utility can be used for the following:
*In general, provisioning and managing accounts should be performed from the administration console, but bulk provisioning can be done from the CLIGeneral Tool Information
The Zimbra command-line utilities follow standard UNIX command-line conventions.
Follow these guidelines when using the commands
Press ENTER after you type a command.
Typing the CLI command and then - h displays the usage options for the command. Example: zmprov - h lists all the options available for the zmprov utility.
Each operation is invoked through command-line options. Many have a long name and a short name. For example, these two commands are equivalent:
zmprov createAccount joe@domain.com test123
zmprov ca joe@domain.com test123
Syntax Conventions
When demonstrating the syntax of each tool, the following conventions indicate required, optional, and alternate values:
{attribute} in curly brackets is required information.
[attribute] in square brackets are optional arguments or information.
{a|b|c} or [a|b|c] options separated by the pipe character | means "a” OR "b” OR "c”
Location of Command-Line Utilities
The command-line tools available for administrators are all located in the
/opt/zimbra/bin directory on the Zimbra server
Zimbra CLI Commands
The table below lists the CLI commands in /opt/zimbra/bin.
Start, stop, or find the status of the MySql session. Enters interactive command-line MySQL session with the logger mysql
Start, stop, status of the Zimbra servers. Also can use to find the ZCS version installed.
Start, stop, the conversion server or find the status of the converted attachments conversion/indexing
Creates a signing certificate. Used with zmcreatecert and zmcertinstall
Start, stop, reload, or find the status of the mailbox components (Tomcat, MySQL, convert)
Performs all provisioning tasks in Zimbra LDAP, including creating accounts, domains, distribution lists and aliases
Start, stop, or find the status of the Swatch process, which is used in monitoring
Set the Web server mode to the communication protocol options: HTTP, HTTPS or mixed
zmprov (Provisioning)
The zmprov tool performs all provisioning tasks in Zimbra LDAP, including creating accounts, aliases, domains, distribution lists, and calendar resources. Each operation is invoked through command-line options, each of which has a long name and a short name.
The syntax for modify can include the prefix "+” or "-” so that you can make changes to the attributes affected and do not need to reenter attributes that are not changing. Use + to add a new instance of the specified attribute name without changing any existing attributes. Use - to remove a particular instance of an attribute. The syntax is zmprov [cmd] [argument].
The following objects use this syntax:
The following example would add the attribute zimbraZimletUserProperties with the value "testing” to user 1 and would not change the value of any other instances of that attribute.
zmprov ma user1 +zimbraZimletUserProperties testing
 
Long Name
--password {pass}
use zimbra admin name/password from localconfig for admin/password
The commands in the following table are divided into the following tasks types - Account, Calendar Resources, Config, COS, Distribution List, Documents, Domain, Server, and Miscellaneous.
Short Name
Syntax:{name@domain} {password} [attribute1 value1 etc]
zmprov ma joe@domain.com zimbraAccountStatus maintenance
zmprov aaa joe@domain.com joe.smith@engr.domain.com
zmprov raa joe@domain.com joe.smith@engr.domain.com
Note: After you rename an account, you should run a full backup for that account. zmbackup -f - <servername.com> -a <newaccountname@servername.com>
zmprov cc Executive zimbraAttachmentsBlocked FALSE zimbraAuthTokenLifetime 60m zimbraMailQuota 100M zimbraMailMessageLifetime 0
zmprov mc Executive zimbraAttachmentsBlocked TRUE
zmprov ms domain.com zimbraVirusDefinitionsUpdateFrequency 2h
Get DistributionListmembership
{username} {password} {from dir}{to folder} Before importing files, any file that will become a Documents page (wiki-style page), must be renamed to include the extension ".wiki”. If not it is imported as a file, accessed either as an attachment or an image.
{username}{password} {domain} {directory} {folder} Creates the domain Documents account
idn domainwiki@company.com test123 zimbra.com /opt/zimbra/wiki/template template
Generates a pre-authentication key to enable a trusted third party to authenticate to allow for single-sign on. Used in conjunction with GenerateDomainPreAuth.
{domain|id} {name} {name|id|foreignPrincipal} {timestamp|0} {expires|0}
Examples
zmprov ca name@domain.com password
Create one account with a password that is assigned to a specified COS. You must know the COS ID number. To find a COS ID, type gc <COSname>.
zmprov ca name@domain.com password zimbraCOS cosIDnumberstring
zmprov ca name@domain.com ‘’
The empty single quote is required and indicates that there is no local password.
Using a batch process to create accounts, see Managing the Zimbra Collaboration Suite chapter for the procedure.
zmprov aaa accountname@domain.com aliasname@domain.com
zmprov cdl listname@domain.com
Add a member to a distribution list. Tip: You can add multiple members to a list from the administration console.
zmprov adlm listname@domain.com member@domain.com
Change the administrator’s password. Use this command to change any password. Enter the address of the password to be changed.
zmprov sp admin@domain.com password
zmprov cd marketing.domain.com zimbraAuthMech zimbra
zmprov mcf zimbraDefaultDomain domain1.com
zmprov gac -v
zmprov gaa domain.com
zmprov gaa -v domain.com
zmprov +zimbraServiceEnabled logger
Then type zmloggerctl start, to start the logger.
Modify zimbraNewMailNotification to customize the notification email template. A default email is sent from Postmaster notifying users that they have received mail in another mailbox. To change the template, you modify the receiving mailbox account. The variables are
You can specify which of the above variables appear in the Subject, From, or Body of the email. The following example is changing the appearance of the message in the body of the notification email that is received at name@domain.com. You can also change the template in a class of service, use zmprov mc. The command is written on one line.
zmprov ma name@domain.com zimbraNewMailNotificationBody ‘Important message from ${SENDER_ADDRESS}.${NEWLINE}Subject:${SUBJECT}’
zmbackup
This tool performs full backups and incremental backups for a designated mail host. You can either specify specific accounts, or, if no accounts are specified, all accounts are included.
This utility has short option names and full names. The short option is preceded by a single dash, the full option is proceeded by a double dash. For example, -fb is the same as --fullBackup.
Syntax
One of -f, -i, or -del must be specified.
zmbackup {-f | -i | del} -acct (account) [options]
Description
 
Short Name
--incrementalBackup
Specifies the account email addresses. Separate accounts with a blank space. Enter all to backup all accounts. Required.
<label|date> Deletes the backup session on or prior to the specified label/date.
--incrementalBackup
<arg> Mail server host name. For format, use either the plain host name or the server.domain.com name. The default is the localhost name.
<arg> Specifies the target backup location. The default is <zimbra_home>/backup.
Examples
In these examples, the server (-s) is server1.domain.com. The (-t) is not required if the target is the default directory, (zimbra_home/backup).
zmbackup -f -a all -s server1.domain.com
zmbackup -i -a all -s server1.domain.com
Perform full backup of only user1’s mailbox on server1. Note that hostname does not need full domain if account is used.
zmbackup -f -s server1 -a user1@domain.com
 
Perform incremental backup of user1’s mailbox on server1.
zmbackup -i -s server1 -a user1@domain.com
zmschedulebackup
This command is used to schedule backups and add the command to your cron table.
The default schedule is as follows:
Each crontab entry is a single line composed of five fields separated by a blank space. Specify the fields as follows:
minute 0 through 59
hour 0 through 23
day of month 1 through 31
month 1 through 12
day of week 0 through 7 (0 or 7 is Sunday)
Type an asterisk (*) in the fields you are not using.
This command automatically writes the schedule to the crontab.
Syntax
zmschedulebackup [-q]|-s|-A|-R|-F|-D] [schedule] [schedule...]
Description
 
Save the schedule. Allows you to save the schedule command to a text file so that you can quickly regenerate the backup schedule when the system is restored.
Removes the current schedule and cancels all scheduled backups.
-h
Examples
zmschedulebackup [-D]
zmschedulebackup -R f [schedule] [schedule]
zmschedulebackup -A f [schedule]
zmschedulebackup -A i [schedule]
zmschedulebackup -q
To display the schedules on one line as a command, so that they can be copied to a text file and saved to be used if the application needs to be restored.
zmschedulebackup -s
zmbackupabort (Aborting a Full Backup)
The zmbackupabort command can be used to stop a backup process. Before you can abort an account you must know backup label. This label is displayed after you start the backup procedure. If you do not know the label, use the zmbackupquery to find the label name.
To stop the restore process. The zmbackupabort -r interrupts an on going restore. The restore process is stopped after the current account is restored. The command displays message showing which accounts were not restored.
Syntax
zmbackupabort -lb (label) -acct (email addresses) -s (hostname) -t (zimbra-home/backup)
Description
 
Short Name
Label of the full backup to be aborted. Use the zmbackupquery, to find the file name.
Specifies the account email addresses. Separate accounts with a blank space. If accounts are omitted, all accounts are backed up.
Mail server host name. For format, use either the plain host name or the server.domain.com name. The default is the localhost name.
Specifies the target backup location. The default is <zimbra_home>/backup.
zmbackupquery
The zmbackupquery command is used to find full backup sets. The command can be used to find a specific full backup set, full backup sets since a specific date, or all backup sets in the backup directory.
Syntax
zmbackupquery <options>
Description
 
Short Name
-a
Account email addresses separated by white space or all for all accounts.
The label of the full backup session to query. An example of a label is backup200507121559510.
If a date is used, the query returns a list of full backup sets since the specified date. Enter date as YYYY/MM/DD hh:mm:ss. The hours, minutes, and seconds are not required.
Mail server host name. For format, use either the plain host name or the server.domain.com name. The default is the localhost name.
Specifies the backup target location. The default is <zimbra_home>/backup.
zmrestore
This tool performs full restores and incremental restores for a designated mail host. You can either specify specific accounts, or, if no accounts are specified, all accounts are in the backup are restored. In addition, you can restore to a specific point in time.
This utility has short option names and full names. The short option is preceded by a single dash, the full option is proceeded by a double dash. For example, -rb is the same as --restorefullBackupOnly.
Syntax
zmrestore {-f | -i} -a (account) <options>
Description
 
Short Name
The label of the full backup to restore. Restores to the latest full backup if this is omitted.
Restores to the full backup only, not any incremental backups since that backup.
<prefix> The prefix to pre-pend to the original account names.
Restores accounts to new target accounts whose names are pre-pended with <prefix>.
Replays the redo logs in backup only, which excludes archived and current redo logs of the system.
Specifies the account email addresses. Separate accounts with a blank space or Type all to restore all accounts.
Mail server host name. For format, use either the plain host name or the server.domain.com name. The default is the localhost name.
--skipDeletedAccounts
Do not restore if named accounts were deleted or did not exist at backup time. (This option is always enabled with "-a all”)
Specifies the backup target location. The default is <zimbra_home>/backup.
Examples
Perform complete restore of all accounts on server1, including last full backup and any incremental backups since last full backup.
zmrestore -acct all -s server1.domain.com
zmbackup -rf -acct all -s server1.domain.com
zmrestoreoffline (Offline Restore)
This tool is run when the Zimbra server (i.e., the Tomcat process) is down. The MySQL database for the server and the OpenLDAP directory server must be running before you start the zmrestoreoffline command.
Syntax
zmrestoreoffline <options> [<accounts>]
Description
 
Short Name
The label of the full backup to restore. Type this label to specify a backup file other then the latest.
--restorefullBackupOnly
Restores to the full backup only, not any incremental backups since that backup.
<prefix> The prefix to pre-pend to the original account names.
Restores accounts to new target accounts whose names are pre-pended with <prefix>.
<arg> Specifies the account email addresses. Separate accounts with a blank space or state all for restoring all accounts. Required.
Replays the redo logs in backup only, which excludes archived and current redo logs of the system.
Mail server host name. For format, use either the plain host name or the server.domain.com name. The default is the localhost name. If -s is specified, this must be localhost.
Specifies the backup target location. The default is <zimbra_home>/backup.
Examples
Before you begin zmrestoreoffline, the LDAP directory server must be running
Perform a complete restore of all accounts on server1, including last full backup and any incremental backups since last full backup.
zmrestoreoffline -s server1.domain.com
zmrestoreldap
This tool is run to restore accounts from the ldap backup.
Syntax
zmrestoreldap -lb session -t target <options>
Description
 
Short Name
Session label to restore from. For example, full200612291821113.
Specifies the backup target location. The default is /opt/zimbra/backup.
Restores named account(s). List account names separated by white space.
zmcontrol (Start/Stop Service)
This command is run to start or to stop services. You can also find which version of the Zimbra Collaboration Suite is installed.
Syntax
zmcontrol [ -v -h ] command [args]
Description
 
Short Name
Shutdown all services and manager on this host. When the manager is shutdown, you cannot query that status.
 
zmmailboxmove (Move Mailbox)
This command is used to move a mailbox from one Zimbra server to another. Mailboxes can be moved between Zimbra servers that share the same LDAP server. All the files are copied to the new server and LDAP is updated. After the mailbox is moved to a new server, a copy still remains on the older server, but the status of old mailbox is closed. Users cannot log on and mail is not delivered. You should check to see that all the mailbox contents were moved successfully before purging the old mailbox.
Syntax
To move a mailbox to a new server, type
zmmailboxmove -a <email@address> -ow -s <servername> -t <movetoservername>
To purge the mailbox from the old server, type
zmmailboxmove -a <email@address) -po.
The mailbox and its contents and references are deleted from the server.
Description
 
Short Name
Purge old mailbox on previous server. After a mailbox has been successfully moved to a new server, perform purgeOld to remove the mailbox and its contents from the previous server.
Mail server hostname. The default is the localhost. Server where the --account mailbox is located.
-t and -po options are mutually exclusive. Use -t option to move a mailbox from the current server to the new server specified by the option. If -ow is specified, if a mailbox already exists for the target server, it is overwritten. After successfully moving the mailbox, use
-po option to purge the old mailbox on the original server.
zmmboxsearch (Cross mailbox search)
zmmboxsearch is the CLI command used to search across mailboxes. You can search across mailboxes to find messages and attachments that match specific criteria and save copies of these messages to a directory.
Syntax
zmmboxsearch -q <querystring}> -m <mailboxids> -s <server> [-d directory]
Description
 
Short Name
<arg> Directory to write the messages to. If none is specified, then only the headers are fetched. Files names are generated in the form RESULTNUM_ACCOUNT-ID_ MAILITEMID.
Sets the limit for the number of results returned. The default is 25.
<arg> Comma-separated list of mailboxes to search. UIDs or email-address or /SERVER/MAILBOXID or *.
<arg> Specify where the hit list should start. The default is 0.
<arg> The query string for the search.
<arg> Mail server hostname. default is the localhost.
Request that the status message print while the search is being executed.
Example
The following example is to do a cross-mailbox search in the inbox folder of two different mailboxes on the specified server and put a copy of the message in to the specified directory.
zmmboxsearch -q "in:inbox” -m user1@yourdomain.com,user2@yourdomain.com -d /var/tmp
zmcreatecert and zmcertinstall (For a Certificate)
The CLI command zmcreateca creates the signing certificate and zmcreatecert creates a new self-signed certificate. After a certificate is created, zmcertinstall is the CLI command to install it.
Tomcat must be stopped and then restarted after the certificate is installed.
Example of steps to use to stop tomcat, delete a certificate that is not working and then create a new certificate and install it.
1.
As root, type:
rm -rf /opt/zimbra/ssl
mkdir /opt/zimbra/ssl
chown zimbra:zimbra /opt/zimbra/ssl
2.
Type su - zimbra, then type the following all on one line
keytool -delete -alias my_ca -keystore /opt/zimbra/java/jre/lib/security/cacerts -storepass changeit
3.
keytool -delete -alias tomcat -keystore /opt/zimbra/tomcat/conf/keystore -storepass zimbra
4.
Type zmcreateca, press Enter
5.
Type zmcreatecert, press Enter
6.
Type zmcertinstall mailbox, press Enter
7.
Type tomcat stop, press Enter
8.
Type tomcat start, press Enter
zmlocalconfig (Local Configuration)
This command is used to set or get the local configuration for a Zimbra server.
Syntax
zmlocalconfig [options] [args]
To see the local config type
zmlocalconfig
Description
 
Short Name
Edit the configuration file, change keys and values specified. The [args] is in the key=value form.
Edit the keys whose change is known to be potentially dangerous.
Shows the values in one of these formats: plain (default), xml, shell, nokey.
Shows the values for only those keys listed in the [args] that have been changed from their defaults.
This option is used with the edit option. Specified key is set to a random password string.
Removes the local setting for a variable, which causes it to fallback to the default.
zmtlsctl
This command is used to set the Web server mode to the communication protocol options: HTTP, HTTPS, or mixed. Mixed mode uses HTTPS for logging in and HTTP for normal session traffic. All modes use SSL encryption for back-end administrative traffic.
Tomcat has to be stopped and restarted for the change to take effect.
Note: If you switch to https, you use the self-signed certificate generated during Zimbra installation, in /opt/zimbra/ssl/ssl/server/server.crt.
Syntax
zmtlsctl [mode]
mode = http, https, or mixed
Steps to run
 
1.
Type zmtlsctl [mode], press Enter.
2.
Type tomcat stop, press Enter.
3.
When Tomcat is stopped, type tomcat start, press Enter.
zmhsm
This command is to start, stop (abort), and see the status of a HSM session. The threshold for when messages are moved to a storage volume is configured from the administration console, Servers>Volume tab.
Syntax
zmhsm {abort|start|status} {server} <name>
Description
Short Name
Aborts the current HSM session.If all the messages in a mailbox being processed were not moved before you clicked Abort, no messages from that mailbox are moved from the primary volume. Messages for mailboxes that have completed the move to the secondary volume are not moved back to the primary volume.
The mail server host name. The default is the localhost [args].
zmmailbox
The zmmailbox tool is used for mailbox management. The command can help administrators provision new mailboxes along with accounts, debug issues with a mailbox, and help with migrations.
Syntax
zmmailbox [args] [cmd] [cmd-args...]
Description
 
Long Name
http[s]://{host}[:{port}] server hostname and optional port. Must use admin port with -z/-a
use zimbra admin name/password from localconfig for admin/password
--password {pass}
Specific CLI tools are available for the different components of a mailbox. Usage is described in the CLI help for the following
 
Examples
When you create an account, you may want to pre-create some tags and folders. You can invoke zmmailbox inside of zmprov by using "selectMailbox(sm)”
 
zmlicense
This command is used to view and install your Zimbra license. The license can be viewed and installed from the administration console, Global Settings, License tab.
 
Short Name
Installs the specified license file.[arg] This is the Zimbra license file that you received.
zmmsgtrace
This command is used to trace an email message that was sent or received with the last 30 days.
Syntax
zmmsgtrace -i|-s|-r|-F <message_id>
Description
 
Short Name
From Times in YYYYMMDD (hhmmss) format.
start, end times in YYYYMMDD[hhmmss] format
zmmylogpasswd
This command is used to change the zimbra_logger_myql_password. If the --root option is specified, the MySql_logger_root_passwd is changed. In both cases, MySQL is updated with the new passwords. Refer to the MySQL documentation to see how you can start the MySQL server temporarily to skip grant tables, to override the root password.
Syntax
zmmylogpasswd <new_password>
zmmypasswd
This command is used to change zimbra_myql_password. If the --root option is specified, the mysql_root_passwd is changed. In both cases, MySQL is updated with the new passwords. Refer to the MySQL documentation to see how you can start the MySQL server temporarily to skip grant tables, to override the root password.
Syntax
zmmypasswd <new_password>.
zmtrainsa
This command is used to train the anti-spam filter. This command is run automatically every night to train the SpamAssasin filter from messages users mark as "junk” "not junk” from their mailbox. See "Anti-Spam Training Filters” .
You can use this command to manually send one account’s mail through the spam filter. You will need to know the account password.
Syntax
zmtrainsa <server> <user> <pass> <spam|ham> [folder]
Description
zmtrainsa fetches the mail from <user> with password <pass> from <server> and trains the filter as either spam or ham <spam|ham>. The folder is optional. If a folder is not defined, the contents of the Inbox is fetched.
zmvolume
This command can be used to manage storage volumes from the CLI. Volumes can be easily managed from the administration console, Server, Volume tab.
Syntax
zmvolume --add --name <message volume> --type <primaryMessage> --path /<data/msgvol>
Description
 
Long Name Second Attribute
Short Name
Type of volume, primaryMessage, secondaryMessage, or index. SecondaryMessage is used only when the Network Edition, HSM feature is enabled.
Compress blobs, "true” or "false”. The default is "false.”
True means that message blobs whose size are above the compression threshold are compressed.
--compressionThreshold <arg>
Compression threshold size is specified in bytes. The default is 4KB
Edits a volume. Any of the options listed under --add can also be specified to have its volume modified.
ID is optional. If it is specified, just that volume is listed. If not, all volumes are displayed.
Sets the volume specified by --id to be the current volume of its volume type.
--turnOffSecondary
Turns off the current secondary message volume. After this command completes, no current secondary volume is enabled.
zmzimletctl
This command is used to deploy Zimlets to users. See Working with Zimlets.
Syntax
zmzimletctl {command} <zimletname> <arg>
Description
Short Name
deploy <zimletname>
Creates the Zimlet entry in the LDAP server, installs the zimlet files on the Server, grants, access to the members of the default COS, and turns on the Zimlet
Extracts the configuration template from the Zimlet.zip file

Appendix A   Command-Line Utilities

Table of Contents Previous Next Index
ZCS Administrator's Guide, Network Edition 4.0
Copyright © 2006 Zimbra Inc.