How to Configure Zimbra GAL Auto-Sync and Verify It Is Working

What GAL auto-sync actually does in Zimbra

If users can search the Global Address List (GAL) but newly created or changed contacts do not appear until much later, the usual issue is not “GAL is disabled.” More often, the GAL sync account exists, but its datasource polling interval is too long, the datasource is disabled, or the last scheduled sync failed.

Zimbra’s current Daffodil (v10) Administrator Guide describes GAL as a per-domain feature with three modes: Internal, External, and Both. A GAL sync account stores synchronized GAL contacts in an address book so clients can get faster autocomplete and browsing. Zimbra also notes that if a GAL sync account is unavailable, the system can fall back to traditional LDAP-based search. That distinction matters: successful lookup does not prove scheduled GAL synchronization is healthy.

Reference: Zimbra Daffodil v10 Administrator Guide.

Before changing anything, identify the current GAL mode and sync account

Run administrative commands as the zimbra operating-system user:

su - zimbra
zmprov gd example.com | egrep 'zimbraGalMode|zimbraGalMaxResults|zimbraGalAccountId'

Replace example.com with the real Zimbra domain. The useful first result is the GAL mode:

• Internal: GAL data comes from the Zimbra LDAP directory.
• External: GAL lookup and synchronization use an external LDAP directory such as Active Directory.
• Both: Zimbra combines internal and external GAL sources.

Common misunderstanding: GAL mode and GAL synchronization are not the same setting. GAL mode tells Zimbra where directory information comes from. Auto-sync is controlled by the GAL datasource and its polling interval. Action: confirm the domain mode first, then inspect the datasource rather than changing unrelated autocomplete settings.

Inspect the GAL sync datasource before editing the schedule

If the domain already has a GAL sync account, list its datasources:

zmprov gds galsync@example.com

Look for values such as:

zimbraDataSourceName: InternalGAL
zimbraDataSourceEnabled: TRUE
zimbraDataSourcePollingInterval: 1d
zimbraGalLastSuccessfulSyncTimestamp: ...
zimbraGalLastFailedSyncTimestamp: ...
zimbraGalStatus: enabled

The exact datasource name may differ. InternalGAL is a common name for an internal datasource; an external datasource may be named ExternalGAL, ADGAL, or something chosen by the administrator.

Zimbra’s Tech Center documentation shows that the datasource polling interval determines how often automated imports occur. The current v10 Administrator Guide also states that the interval can be expressed in days, hours, minutes, or seconds and is set per datasource.

Reference: Zimbra Tech Center: GAL Sync Account.

Set a practical GAL polling interval

To change an existing datasource to synchronize once per hour:

zmprov mds galsync@example.com InternalGAL   zimbraDataSourcePollingInterval 1h

Other examples include 30m, 12h, or 1d. Zimbra’s published schema documentation uses duration units such as h, m, s, and d.

A shorter interval is not automatically better. For a small internal directory, one hour may be reasonable. For a large external LDAP directory or a WAN-connected Active Directory, aggressive polling can create unnecessary directory and mailbox-server load. Action: choose an interval based on how quickly directory changes must appear and how expensive a full or incremental sync is in your environment.

Common misunderstanding: forceSync does not configure auto-sync. It starts an immediate synchronization. The recurring schedule comes from zimbraDataSourcePollingInterval. Action: set the interval first, then use a forced sync only to validate the configuration immediately.

Force one sync to verify the configuration

After setting the interval, trigger an immediate synchronization:

zmgsautil forceSync -a galsync@example.com -n InternalGAL

Use the exact datasource name returned by zmprov gds. Zimbra’s official Tech Center documentation uses this command for both internal and external GAL datasources.

Then inspect the datasource again:

zmprov gds galsync@example.com | egrep 'zimbraDataSourceName|zimbraDataSourceEnabled|zimbraDataSourcePollingInterval|zimbraGalLastSuccessfulSyncTimestamp|zimbraGalLastFailedSyncTimestamp|zimbraGalStatus'

A useful verification result is not merely “the command returned without an obvious error.” You want to see a recent successful-sync timestamp, an enabled datasource, the expected polling interval, and no newer failed-sync timestamp that indicates the operation is repeatedly failing.

How to configure GAL auto-sync from the Admin Console

For a new or reconfigured domain, the supported graphical path in Zimbra v10 is through the domain’s GAL configuration:

1. Open the Zimbra Administration Console.
2. Go to Configure → Domains.
3. Select the required domain.
4. Open Configure GAL from the domain actions.
5. Select Internal, External, or Both as appropriate.
6. Confirm the GAL sync account and datasource names.
7. Set the GAL polling interval.
8. Finish the wizard, then use zmgsautil forceSync if you need an immediate test.

The v10 Administrator Guide specifically notes that when GAL mode is Both, an address book is created for each LDAP datasource. It also warns administrators not to edit those synchronized address books directly because synchronization can overwrite manual changes. Action: make directory changes at the authoritative LDAP source, not in the GAL sync account’s generated address book.

What if the GAL sync account does not exist?

For new deployments, use the Admin Console when possible because it keeps the domain, GAL account, and datasource relationship consistent.

Zimbra’s Tech Center also documents CLI creation with zmgsautil createAccount. A documented internal-GAL example is:

zmgsautil createAccount   -a galsync@example.com   -n InternalGAL   --domain example.com   -s mailstore.example.com   -t zimbra   -f _InternalGAL

The -s mailbox-server option is documented for ZCS 8 and later in the Tech Center article. Because exact command-line behavior can vary by release and packaging, check zmgsautil help on the installed server before creating a new account rather than copying an old command blindly.

Common misunderstanding: deleting a broken GAL account with a generic account-deletion command is not equivalent to removing it with the GAL utility. Zimbra’s Tech Center warns that deleting a GAL account incorrectly can leave the domain’s zimbraGalAccountId pointing to an invalid account. Action: if you truly need to remove and recreate a GAL account, follow the documented zmgsautil deleteAccount procedure instead of treating it like a normal mailbox account.

Reference: Zimbra Tech Center: remove, create, and force-sync a GAL account.

External LDAP or Active Directory: what changes?

With an external GAL, the scheduled mechanism is still the GAL datasource polling interval, but successful synchronization also depends on external LDAP configuration: server URL, bind DN, bind password, search base, and filter.

Zimbra documents that the first external datasource can inherit GAL configuration from the domain. Additional datasources can be configured with their own LDAP connection settings. If external synchronization fails, reducing the polling interval will not fix a bad bind password, unreachable LDAP host, incorrect search base, TLS problem, or filter that excludes the expected users.

Action: if forceSync fails, verify the external directory connection and filter before lowering the interval further.

How to tell whether auto-sync is really working

Use this short validation checklist after configuration:

Do not use autocomplete alone as the only health check. Because Zimbra can fall back to LDAP-based GAL searching when the sync account is unavailable, users may still find names even while the scheduled GAL address-book sync is stale.

Troubleshooting when the schedule looks correct but data stays stale

Check for a failed synchronization timestamp

If zimbraGalLastFailedSyncTimestamp is newer than the last successful timestamp, the scheduler may be running correctly but the datasource is failing. That is different from “auto-sync is disabled.” Action: troubleshoot the datasource instead of repeatedly changing the polling interval.

Check mailbox logs around the sync attempt

Zimbra documents /opt/zimbra/log/mailbox.log as the main mailboxd activity log. Use it to correlate errors around the time of a forced or scheduled GAL operation:

tail -f /opt/zimbra/log/mailbox.log

For a production system, avoid enabling broad debug logging unless you need it and understand the extra log volume.

Check overlapping datasources if you see duplicate contacts

Zimbra notes that multiple GAL datasources with overlapping search scopes can import duplicate entries; the system does not automatically reconcile those duplicates. Action: narrow the LDAP search base or filter so each datasource has a clear scope, then run a new sync.

Do not rename an existing GAL sync account

The current Zimbra v10 Administrator Guide says that changing the name after creation can break synchronization. To change the name, remove and recreate the GAL configuration using the supported process. Action: leave a working GAL sync account name unchanged unless there is a real operational reason to rebuild it.

Recommended configuration pattern

For a typical single-domain deployment, a reliable approach is:

• Keep the correct GAL mode for the directory architecture.
• Use a dedicated GAL sync account created through Zimbra’s GAL configuration workflow.
• Keep each datasource enabled.
• Set a polling interval that matches the acceptable directory-change delay.
• Use zmgsautil forceSync only for immediate validation or troubleshooting.
• Confirm success with datasource timestamps, not only with user autocomplete.
• For external LDAP, treat connectivity, bind credentials, search base, and filters as separate dependencies.

If those checks pass, Zimbra should update its GAL sync address book on the configured schedule. If the timestamps stop advancing or forced synchronization fails, the next step is not a shorter interval; it is to identify the datasource or LDAP error that is preventing the scheduled job from completing.