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
-
run it from the CLI:
zextras$ carbonio backup doSmartScan start
-
enter the Carbonio Shell
zextras$ carbonio
The prompt will change into
carbonio>
. In the Carbonio CLI, you can run the previous command ascarbonio> 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.