Carbonio CLI Overview

Carbonio CLI Overview#

The Carbonio CLI, also known as Carbonio Shell, is an interactive shell that allows to execute Carbonio’s commands. All carbonio commands must be run as the zextras user: to do so, run as the root user

# su - zextras

Upon launching this command, the prompt will change to zextras$.

At this point, to launch a carbonio command you can either

  1. run it from the CLI:

    zextras$ carbonio backup doSmartScan start

  2. enter the Carbonio Shell

    zextras$ carbonio

    The prompt will change into carbonio> . In the Carbonio CLI, you can run the previous command as

    carbonio> backup doSmartScan start

    The Carbonio Shell is useful in multiple ways:

    • If you need to execute multiple commands, for example to carry out some advanced task

    • To keep the history: commands will be available for future reference and to check the operations done so far

    • You will be able to use tab for auto-completion of commands

Syntax of a Command#

A typical Carbonio command is composed by several parts, some of which is required for the command to work properly, for example

zextras$ carbonio --progress backup doSmartScan start

Besides carbonio, which is used to invoke the commands, the following parts compose a typical carbonio command: the module name, the command, and the parameters.

Command Line Options#

Adding options to any commands is also possible; for example, you can run

carbonio> --progress backup doSmartScan start

The available command line options are:

--host

Specify a target host (both IP or hostname are accepted) on which the command will be executed. Use all_servers to broadcast the command to all servers. To run a command only on the server on which you are logged in, simply do not use the option.

--json

The output of the command will be presented in JSON format and is useful for scripting.

--progress

Prints the operation’s feedback directly to STDOUT. Press Ctrl+C to interrupt the output: the operation itself will not be interrupted.

--sync

Runs the command in synchronous mode, waiting for the operation’s execution to end and returning an exit code:

  • 0 - Successful

  • 1 - Failed

  • 2 - Stopped

  • 3 - Removed

  • 4 - Interrupted

Module#

The Carbonio CLI supports all Carbonio modules: auth, admin, and more, including provisioning (i.e., carbonio prov).

Command#

Most of the commands are module-dependent

Parameters#

The actual parameters available for each carbonio command depend on the command itself. Parameter are either mandatory or optional and are denoted with (M) and (O) in the online help.

All parameters are given as a <name> <value> pair, but the <name> must be provided only for optional parameters and must be omitted in the mandatory. For example, consider this help page.

zextras$ carbonio admin setDomainSettings *domain* [param \
VALUE[,VALUE]]

Parameter List

NAME

TYPE

EXPECTED VALUES

DEFAULT

domain (M)

String

account_limit (O)

Integer

no action

domain_account_quota (O)

String

no action

reset_cos_limits (O)

String

cosname1:limit1, cosname2:limit2

no action

add_cos_limits (O)

String

cosname1:limit1, cosname2:limit2

no action

(M) == mandatory parameter, (O) – optional parameter

In order to limit to 1,000 the accounts of domain acme.example, we need to write the command as

zextras$ carbonio admin setDomainSettings \
acme.example \
account_limit 1000

There are two parameters in this command: <domain> <acme.example> and <account_limit> <1000>, but since domain is mandatory, we omit its name.

Seeking Help#

carbonio comes with a contextual help that can be used at different levels and with no differences on CLI and Carbonio Shell. The most general use is

zextras$ carbonio help

This lists all options (see previous section) and all modules available to carbonio. The help keyword can be used also to list all command in a module (for example, carbonio help config), or the help page of each command (for example, carbonio help config distributionList).

Hint

The help page of the command is shown also if there is some syntax error in the command issued.

Scripting Commands#

To launch multiple carbonio commands, you can save them in a file (called carbonio-commands.txt here) and pipe them to the carbonio shell. For example, consider file carbonio-commands.txt containing the commands:

prov ca user@example.com ''
prov sp user@example.com password
mobile doAddAccountLogger user@example.com debug /tmp/user@example.com
prov ma user@example.com zimbraFeatureMobileSyncEnabled TRUE
prov sm user@example.com cf /test
prov sm user@example.com addMessage /test /tmp/email.eml
prov ma user@example.com zimbraFeatureMobileSyncEnabled FALSE
prov da user@example.com ''
prov fc all

All these command can be executed as

# cat carbonio-commands.txt | carbonio

This proves useful, for example, when finding a procedure that requires to execute a set of carbonio commands: copy tand paste them into a file and run all of them sequentially without the need to copy and paste each single command.

Shared Commands#

There are a few commands that can be used within every module and allow to manage the status of the services provided by each module. These commands are: getServices, doStartService, doStopService, and doRestartService.

Their usage is quite simple and follows the general syntax (see Syntax of a Command): carbonio <module> <command> {service_name}, for example:

zextras$ carbonio mobile getServices

The output will be similar to the following one:

services
  module
      could_start                                                 false
      could_stop                                                  true
      running                                                     true
  activesync-services
      could_start                                                 false
      could_stop                                                  true
      running                                                     true
  autodiscover
      could_start                                                 false
      could_stop                                                  true
      running                                                     true
  abq-services
      could_start                                                 false
      could_stop                                                  true
      running                                                     true
  ldap-address-book
      could_start                                                 false
      could_stop                                                  true
      running                                                     true
  anti-dos
      could_not_start_because                                     anti-dos disabled
      could_start                                                 false
      could_stop                                                  false
      running                                                     false

Along each available service appears its current status and whether it can started or stopped. In some cases, additional information is also shown, for example the anti-dos service can not be started because it is not enabled.

You can manually start, restart, or stop a service using the other commands; unlike getServices, these require a parameter, which is the service name, for example:

zextras$ carbonio mobile doStopService activesync-services

This command outputs a status message, which is “service stopped” if it was successful. Similar messages are generated after using the doStartService and doRestartService commands.

Contents