Advanced Administration Tasks

Advanced Administration Tasks#

In this section we describe and outline a few advanced tasks, providing quick directions to carry them out.

Component-based Access Control#

Carbonio uses a delegation mechanism to allow the principal administrator to assign roles and permission to other users with the purpose of sharing with them the administration tasks and duties, electing them as either Global or Delegated Administrator, who have different privileges to configure and manage these features.

In the context of the management of Anti-Virus and Anti-Spam functionalities, each Administrator, either Global or Delegated, can access with the personal account and be able to control and manage them, according to permissions granted.

Server-side Management of E-mails#

Carbonio's MTA (Postfix) receives e-mail by means of the SMTP protocol and forwards it to the correct e-mail queue according to the user’s username (this coincides with the user’s e-mail address). In case of an e-mail whose recipient is a distribution list (i.e., a mailing list), the e-mail is forwarded to each of the members of the list.

Additional rules can be created directly on Postfix from the CLI. Examples of restriction rules can be found directly in Postfix documentation, for example in Postfix Standard Configuration Examples. More examples, depending on the use case, can be found in the official Postfix documentation.

Server-side Attachment Management#

Global e-mail attachment settings allow you to specify global rules for handling attachments of an e-mail message.

Modify list of blocked file extensions

You can set rules at COS-level and also for individual accounts. When attachment settings are configured in Global Settings, the global rule takes precedence over COS and Account settings.

A list of formats (extensions) can be created via CLI to restrict the attachments allowed.

Warning

All files whose extension is in the list will never reach the recipient.

For example, to block .exe filex, use command

# carbonio prov mcf +zimbraMtaBlockedExtension "exe"

Hint

Only one format/extension at a time can be specified.

Manage attachments’ size

It is possible to limit both the size of a message and its attachment and their individual sizes.

The total size of the message can be set for each MTA server directly on the Carbonio Admin Panel, in the Tuning section under Admin Panel ‣ MTA ‣ Advanced (see documentation).

The maximum size of each attachment can be set by the CLI for each user, CoS, or domain issuing as the zextras user

zextras$ carbonio prov ma alice@example.com zimbraFileUploadMaxSizePerFile 1048574

This command prevents Alice to sent an attachment larger that 10Mb.

Management of a COS#

Each account on Carbonio is assigned a COS, a global object that is not restricted to a particular domain or set of domains.

The COS assigned to an account determines the default attributes for that account and the features to be enabled or not for it. The COS controls mailbox quotas, message lifetime, password restrictions, attachment blocking, and server pool usage.

You can create and edit the classes of services via CLI and soon also via the new Carbonio Admin Panel, in which the tasks of COS management will feature an helpful wizard that guides the Administrator through the creation process.

# carbonio prov createCos {name} [attribute value ...]

All the attributes that need to be customised can be either added at the end of the base command above as [ attribute value ] pairs, or at a later point with the following command:

# carbonio prov modifyCos {name} [attribute value ...]

S/MIME support#

S/MIME support for all users can be enabled using command

zextras$ carbonio config set global enableSmimeEncryption TRUE

Users will then be able to upload certificates to be used for S/MIME signing; setting it to false will prevent users from using the feature.

Additionally, the command below enables the ability of the user to verify the S/MIME signature.

zextras$ carbonio prov mcf carbonioSMIMESignatureVerificationEnabled TRUE

The access the S/MIME Certificate Store from within their Settings page, users need to supply a password, which is different from the S/MIME certificate’s password. You can set various parameters of this password from the CLI, by using the following command as the zextras user user.

zextras$ carbonio config set global \
encryptionPasswordPolicyAttribute <attribute> <value>

The list of all available attributes that can be customised can be retrieved using command

zextras$ carbonio config get global \
encryptionPasswordPolicyAttribute

The output of the above command is:

global
      values

              attribute                                                   encryptionPasswordPolicyAttribute
              inheritedValue
                  minLength                                                       8
                  maxLength                                                       100
                  minUpperCase                                                    1
                  minLowerCase                                                    1
                  minDigits                                                       1
                  minPunctuation                                                  0
                  minAlphaChars                                                   0
                  minPunctuationOrDigitChars                                      0
                  requireAlphanumeric                                             true
                  allowedChars
                  allowedPunctuation
                  denyList
              inheritedFrom                                               default
              isInherited                                                 true
              modules
                      ZxCore

The attribute is available only at global level, meaning this password policy is the same for all configured domains, CoS, and user on the system.

Pending-setups#

This section describes the functionalities provided by pending-setups in Carbonio and explains when it is necessary to run or re-run it for its proper functioning.

Overview#

In a nutshell, pending-setups in Carbonio manages post-installation and configuration tasks that are required to finalise Carbonio's setup and to ensure that the services run correctly.

pending-setups is a wrapper around a collection of scripts, provided by other packages and placed in the /etc/zextras/pending-setups.d/ directory.

When invoked, pending-setups carries out these task:

  • Set up of authentication and security policies using service-discover

  • Securely store and manage credentials

  • Configure services to ensures all Carbonio components (e.g., Mail, Authentication, Video Server) are properly configured

  • Reload services to apply changes

When a script is successfully executed, it is moved to the /etc/zextras/pending-setups.d/done directory.

Running pending-setups#

Hint

All commands shown in this section must be executed as the root user.

Before executing the command, make sure that you retrieve the cluster credential password, which is stored in file /var/lib/service-discover/password.

pending-setups can be invoked with the -a option: in this case, it simply reads all the scripts in the /etc/zextras/pending-setups.d/ directory and executes them, with the output showing the tasks it carries out.

Invoked with no options, it enters an interactive mode, showing a menu similar to:

You have 6 pending setups to run
0) carbonio-catalog.sh
1) carbonio-tasks.sh
2) carbonio-user-management.sh
3) carbonio-tasks-db-setup.sh
4) carbonio-files.sh
5) carbonio-files-db-setup.sh

a) execute all
q) quit

Please input your selection:
>

The initial list shows all the scripts that must be executed: enter the number corresponding to the script to launch it or chose either a to execute them all, or q to exit. In the latter case, however, it will not be possible to use Carbonio successfully, as it would miss a number of configurations.

If all scripts have been executed, the command will output:

There are no pending-setups to run. Exiting!

Why Running pending-setups Again#

There are a number of situations when you need to run pending-setups again. In some of the following cases, the script might have not been executed successfully, but nonetheless they are moved under the /etc/zextras/pending-setups.d/done, so simply invoking pending-setups again will not suffice.

After a failed setup or partial installation

If the initial pending-setups process fails or gets interrupted (e.g., due to a system crash, missing dependencies, or misconfigured services)

After manually fixing a configuration issue

If you manually adjust configuration files, services, or permissions

After upgrading Carbonio

If an update doesn’t fully apply

After restoring from a backup or migrating to a new server

If you restore a Carbonio system from a backup or migrate it to a new server, some configurations might need to be re-applied to match the new environment

When adding a new Carbonio Component

If you install a new Carbonio Component (e.g., Files, Chats), running pending-setups ensures that the new component is properly integrated into the system

Debugging and troubleshooting

If a service is misbehaving or showing unexpected errors, re-running pending-setups can sometimes reapply missing configurations and fix the issue

How to Run pending-setups Again#

There are two options to execute a failed script.

Option 1: Move the Script Back and Re-run pending-setups

The first one proves useful if you realise that multiple script have failed, or believe they have failed. In this case, the procedure is:

  1. Copy the script from /etc/zextras/pending-setups.d/done back to the main directory

    # cp /etc/zextras/pending-setups.d/done/<script-name>.sh \
/etc/zextras/pending-setups.d/

    Replace <script-name>.sh with the actual script name.

  2. Run the command

    # pending-setups -a

  3. The script will be executed again as part of the pending setups process, like described in Section Running pending-setups above

Option 2: Manually Execute the Script

If you have only one script to execute, youcan run the script manually.

  1. Navigate to the /etc/zextras/pending-setups.d/done directory

# cd /etc/zextras/pending-setups.d/done

  1. Execute the script directly. For example, to execute carbonio-videoserver.sh

# bash carbonio-videoserver.sh

  1. The script will immediately be executed

Carbonio and HTTP Proxy#

Many organisations operate within secured network environments where direct Internet access is restricted and blocked by firewall rules or corporate policies.

Using an HTTP proxy allows administrators to control and monitor outbound connections from the Carbonio server, ensuring that only approved services and destinations are accessible.

In a scenario like this, configuring an HTTP proxy is mandatory for Carbonio to function properly: this can be achieved using the zimbraHttpProxyURL attribute as follows.

Note

All commands in this section must be executed as the zextras user user.

First, login to the any Node installing the Proxy and check the current configuration of the attribute.

zextras$ carbonio prov getConfig zimbraHttpProxyURL

If there is no output, Carbonio tries to use a direct connection to the Internet, which in the scenario depicted above does not work, so we need to configure the attribute as follows.

Unauthenticated proxy
zextras$ carbonio prov modifyConfig zimbraHttpProxyURL http://proxy.example.com:8080

Replace http://proxy.example.com:8080 with the actual proxy that needs to be used.

Authenticated proxy
zextras$ carbonio prov modifyConfig zimbraHttpProxyURL http://username:password@proxy.example.com:8080

Replace http://username:password@proxy.example.com:8080 with the correct values

Finally, restart the service.

Execute, as the zextras user

zextras$ zmcontrol restart

Execute, as the root user

# systemctl start/stop/restart carbonio-proxy.target

Execute, as the zextras user

zextras$ zmcontrol restart

Execute, as the root user

# systemctl start/stop/restart carbonio-proxy.target

Freshclam and HTTP Proxy#

Similarly to the scenario described in Section Carbonio and HTTP Proxy, freshclam can not download the antivirus signatures if Carbonio is placed behind a proxy. The solution is to put the proxy information in the freshclam configuration template, which is /opt/zextras/conf/freshclam.conf.in.

Log in to the Node where the MTA AV/AS Component is installed and edit the file, by adding at the bottom the lines:

HTTPProxyServer  proxy.example.com
HTTPProxyPort    8080

As the zextras user, execute

zextras$ zmclamdctl restart

To verify that the new configuration is correct and the HTTP proxy is being used, check the log file

zextras$ tail -f /opt/zextras/log/freshclam.log

In the output you should find some lines similar to the following:

ClamAV update process started at Thu Mar 13 14:01:58 2025
Trying to retrieve CVD header from https://database.clamav.net/daily.cvd
OK
main database available for download (remote version: xx)
Testing database: '/opt/zextras/data/clamav/db/tmp.03d9f579e4/clamav-f220b006e75bbf945b40dd0f5b8a2f29.tmp-main.cvd' ...
Database test passed.
main.cvd updated (version: 62, sigs: 6647427, f-level: 90, builder: sigmgr)
Trying to retrieve CVD header from https://database.clamav.net/bytecode.cvd
OK
Make a copy of the configuration template

If you have modified freshclam's configuration template /opt/zextras/conf/freshclam.conf.in , you will likely need to edit it again after an upgrade, because upgrades often overwrite configuration templates. Since Carbonio regenerates freshclam.conf from the template file, when Carbonio or ClamAV updates, the template may be reset to default or overwritten with a new version, losing any changes you made to it. In this case, any custom modifications would be lost.

To make sure changes are preserved after an upgrade, create a backup of the template file

zextras$ cp /opt/zextras/conf/freshclam.conf.in /opt/zextras/conf/freshclam.conf.in.backup

After the upgrade, compare and restore changes

zextras$ diff /opt/zextras/conf/freshclam.conf.in.backup /opt/zextras/conf/freshclam.conf.in

If the output is empty, there is no difference between the new template and the backup, so freshclam will keep on working without issues. If you see any difference, you might want to restore the proxy settings, by following this procedure from the beginning or copying your backup file on the new template.

zextras$ cp /opt/zextras/conf/freshclam.conf.in.backup /opt/zextras/conf/freshclam.conf.in

Clean Activesync Status#

Background

In previous Carbonio releases, ActiveSync could (in some cases and with specific clients) create large amounts of historical sync state records in the mail_item MySQL table. Over time, this caused:

  • Large table sizes

  • Slower queries and sync performance

  • Excessive storage use

Carbonio 25.9.0 improvements

Release 25.9.0 introduces features to optimize database growth and maintenance:

  1. New manual index creation command

    A new CLI command has been introduced:

    zextras$ carbonio mobile createStateIndex

    • Creates an index on the ActiveSync table (required for new cleanup logic)

    • Execution time depends on the current table size (can be long on large installations)

    • Needs to be executed only once per infrastructure

  2. New retention period parameter for PurgeMobileState command

    doPurgeMobileState now supports a retention period parameter, allowing administrators to define the time window for keeping sync states.

    Example:

    zextras$ carbonio mobile doPurgeMobileState retention-period 90

    • Keeps sync states for a defined period (default: 90 days)

    • Deletes devices inactive beyond that window

  3. Automatic Space Recovery

    At the end of each purge task, a VACUUM operation is now executed on the database to reclaim physical storage space.

  4. Improved Sync Cleanup Logic

    During ActiveSync operations, old statuses are now automatically removed.

    This keeps the status table smaller and reduces long-term growth.

    Important

    This improvement only works if a new database index is created.

Admin Guidance

Initialisation

After upgrading to 25.9.0 or performing a new installation, to enable the improved cleanup logic, Administrators should run

zextras$ carbonio mobile createStateIndex

  • On a new installation with an empty database, this task completes quickly

  • On an already populated database execution time can be significantly longer. For this reason, it is strongly recommended to run the command during a period of low system load.

  • If your infrastructure includes multiple Mailstore & Provisioning Nodes, the command must be executed only once on a single Mailstore & Provisioning Node

Maintenance

Regularly use doPurgeMobileState retention-period <days> to keep sync states under control and storage usage optimised

zextras$ carbonio mobile doPurgeMobileState retention-period <days>

For automation, edit the crontab and configure it to run daily as the zextras user

zextras$ zextras$ crontab -e

Scroll to the very end of the file (after the comment ZEXTRAS-END -- DO NOT EDIT ANYTHING BETWEEN THIS LINE AND ZEXTRAS-START) and add:

45 23 * * * /opt/zextras/bin/carbonio mobile doPurgeMobileState > /dev/null 2>&1

This task will clear the state table every day at 23:45 (11:45 PM).

You can change the execution time by modifying the hour (23) and minute (45) values. Also in this case if your infrastructure includes multiple Mailstore & Provisioning Nodes, the command must be scheduled only on a single Mailstore & Provisioning Node, not on every Node.

Trust Self-Signed Certificates#

This guide explains how to configure Carbonio to trust either a self-signed certificate or a certificate signed by an internal Certificate Authority (CA) when connecting to a remote backend endpoint (e.g., S3-compatible storage or LDAP databases) protected by self-signed certificates.

For these connections to be successful and to avoid warnings and communication errors, it is mandatory to import the root or intermediate CA into:

  1. The Operating System’s trust store, to allow system tools to trust the certificate

  2. The Jetty keystore of Carbonio, to allow internal services, like mailboxd, to establish secure TLS connections without warnings or failures

To achieve these results, carry out this procedure on all Nodes that should access the backend. For example, if the remote endpoint is a Storage, carry out the procedure on all Nodes installing the Mailstore & Provisioning Component.

Preliminaries

Before carrying out the procedure, please pay attention to the following points.

  • Commands. All commands must be executed as the root user

  • Certificate file extension. Ensure the certificate file has extension .crt on Ubuntu systems

  • Certificate file permissions. The certificate file must be readable by the zextras user

  • Services restart. The last step of the procedure requires to restart Carbonio services, otherwise the new configuration will not be used

Step 1. Obtain the CA Certificate

Ensure your CA certificate is in PEM format (we will call it ca.pem): if it is in a .crt or .cer format, convert it to PEM format.

Step 2. Import the CA Certificate into the OS

This step ensures that all OS-level tools and libraries (e.g., curl, wget, backup utilities) can trust the endpoint.

The file must have a .crt extension.

# cp ca.pem /usr/local/share/ca-certificates/ca.crt
# update-ca-certificates

The file must have a .crt extension.

# cp ca.pem /usr/local/share/ca-certificates/ca.crt
# update-ca-certificates

# cp ca.pem /etc/pki/ca-trust/source/anchors/
# update-ca-trust

# cp ca.pem /etc/pki/ca-trust/source/anchors/
# update-ca-trust

Step 3. Import the CA Certificate into Carbonio

This step is mandatory to ensure that Carbonio’s internal Java-based services (Jetty) trust the certificate.

# chown zextras:zextras ca.pem
# /opt/zextras/bin/zmcertmgr addcacert ca.pem

If successful, the output will confirm that the certificate was added to the keystore.

Step 4. Restart the services.

Restart Carbonio services to apply the changes.

As the zextras user

zextras$ zmcontrol restart

As the root user

# systemctl restart carbonio-directory-server.target
# systemctl restart carbonio-appserver.target
# systemctl restart carbonio-mta.target
# systemctl restart carbonio-proxy.target

As the zextras user

zextras$ zmcontrol restart

As the root user

# systemctl restart carbonio-directory-server.target
# systemctl restart carbonio-appserver.target
# systemctl restart carbonio-mta.target
# systemctl restart carbonio-proxy.target
Contents