Back to Projects

zm-federation

This federation system enables **transparent cross-instance sharing** between completely separated Zimbra instances without creating proxy accounts or using shared LDAP.

zimbrashare
View on GitHub

Zimbra Federation Layer - Patch Scripts

This directory contains scripts to apply and manage the Zimbra Federation implementation.

Available Scripts

1. apply-federation-patch.sh - Complete Implementation Script

Purpose: Applies all federation changes to a clean Zimbra10FOSS installation

What it does:

  • Creates backup of original files
  • Creates 3 new Java source files (FederatedProvisioning, FederatedShareNotifier, CreateFederatedMountpoint)
  • Patches existing files (FolderAction, MailService, MailConstants)
  • Builds zm-mailbox with federation implementation
  • Creates deployment package with JARs and configuration scripts

Usage:

cd /path/to/Zimbra10FOSS
./apply-federation-patch.sh

Requirements:

  • Must be run from Zimbra10FOSS root directory
  • Requires ant build tools
  • Java development environment configured

Output:

  • federation-backup-TIMESTAMP/ - Backups of original files
  • federation-deployment-TIMESTAMP/ - Deployment package containing:
    • Built JAR files
    • configure-federation.sh - LocalConfig setup script
    • DEPLOY.md - Deployment instructions
    • FEDERATION_IMPLEMENTATION_GUIDE.md - Complete documentation

2. generate-federation-patch.sh - Git Patch Generator

Purpose: Creates a git patch file from current federation implementation

What it does:

  • Generates zimbra-federation.patch containing all changes
  • Includes both modified files and new files
  • Creates a portable patch that can be applied on other systems

Usage:

cd /path/to/Zimbra10FOSS
./generate-federation-patch.sh

Output:

  • zimbra-federation.patch - Git patch file

To apply generated patch on another system:

# Check the patch
git apply --stat zimbra-federation.patch
git apply --check zimbra-federation.patch

# Apply the patch
git apply zimbra-federation.patch

# Build
cd zm-mailbox
ant -Dzimbra.buildinfo.version=10.0.0_GA_1 all

Federation Implementation Overview

What Gets Created

New Files:

  1. zm-mailbox/store/src/java/com/zimbra/cs/account/ldap/FederatedProvisioning.java (285 lines)

    • Multi-instance LDAP account lookup
    • Searches across multiple Zimbra instances

  2. zm-mailbox/store/src/java/com/zimbra/cs/service/mail/FederatedShareNotifier.java (251 lines)

    • Share notification bridge
    • Sends SOAP notifications to remote instances

  3. zm-mailbox/store/src/java/com/zimbra/cs/service/mail/CreateFederatedMountpoint.java (197 lines)

    • Auto mountpoint creation SOAP handler
    • Receives federated share notifications

Modified Files:

  1. zm-mailbox/store/src/java/com/zimbra/cs/service/mail/FolderAction.java

    • Added federation hooks in grant operation (lines ~244-267)
    • Added federation hooks in revoke operation (lines ~168-212)
    • Added ZimbraLog and Folder imports

  2. zm-mailbox/store/src/java/com/zimbra/cs/service/mail/MailService.java

    • Registered CreateFederatedMountpoint SOAP handler (line ~94)

  3. zm-mailbox/common/src/java/com/zimbra/common/soap/MailConstants.java

    • Added E_CREATE_FEDERATED_MOUNTPOINT_REQUEST constant
    • Added E_CREATE_FEDERATED_MOUNTPOINT_RESPONSE constant
    • Added corresponding QName constants

How It Works

┌──────────────────────────────────────────────────────────┐
│           TRANSPARENT SHARING FLOW                        │
└──────────────────────────────────────────────────────────┘

1. UserA@Zimbra1 grants share to UserB@Zimbra2
   ↓
2. FolderAction detects grant operation
   ↓
3. FederatedProvisioning searches federated instances for UserB
   ↓
4. FederatedShareNotifier sends SOAP notification to Zimbra2
   ↓
5. CreateFederatedMountpoint on Zimbra2 receives notification
   ↓
6. Auto-creates mountpoint in UserB's mailbox
   ↓
7. UserB sees shared folder automatically (TRANSPARENT!)
   ↓
8. UserB accesses folder → SOAP proxying → Zimbra1 (TRANSPARENT!)

Quick Start

Option A: Use All-in-One Script (Recommended)

# Apply complete federation implementation
./apply-federation-patch.sh

# Follow the deployment instructions in the generated package
cd federation-deployment-TIMESTAMP/
cat DEPLOY.md

Option B: Use Git Patch

# Generate patch from current implementation
./generate-federation-patch.sh

# Transfer patch to another system
scp zimbra-federation.patch user@other-system:/path/to/Zimbra10FOSS/

# On other system, apply patch
cd /path/to/Zimbra10FOSS
git apply zimbra-federation.patch

# Build
cd zm-mailbox
ant -Dzimbra.buildinfo.version=10.0.0_GA_1 all

Deployment Workflow

After running the patch script:

  1. Review Generated Package

    cd federation-deployment-TIMESTAMP/
ls -la

  2. Deploy to Both Zimbra Instances

    # Copy JARs to each Zimbra server
scp *.jar root@zimbra1:/opt/zimbra/lib/jars/
scp *.jar root@zimbra2:/opt/zimbra/lib/jars/

# Copy configuration script
scp configure-federation.sh zimbra@zimbra1:~/
scp configure-federation.sh zimbra@zimbra2:~/

  3. Configure Federation on Each Instance

    # On Zimbra1
su - zimbra
./configure-federation.sh

# On Zimbra2
su - zimbra
./configure-federation.sh

  4. Restart Services

    # On both instances
zmmailboxdctl restart

  5. Test Federation

    # On Zimbra1
zmmailbox -z -m userA@example.com mfg /Calendar rw userB@example.com

# On Zimbra2, verify mountpoint
zmmailbox -z -m userB@example.com gaf

Configuration

Federation is configured via LocalConfig on each instance:

# Enable federation
zmlocalconfig -e zimbra_federation_enabled=true

# Configure remote instances (comma-separated LDAP URLs)
zmlocalconfig -e zimbra_federation_instances="ldap://remote:389"

# LDAP credentials for remote lookup
zmlocalconfig -e zimbra_federation_bind_dn="uid=zimbra,cn=admins,cn=zimbra"
zmlocalconfig -e zimbra_federation_bind_password="<password>"
zmlocalconfig -e zimbra_federation_base_dn="dc=example,dc=com"

Network Requirements

  • LDAP (389): Remote account lookup
  • HTTPS (7071): Admin SOAP endpoint for share notifications
  • HTTPS (443, 8443): Mail proxy for accessing shared content

Troubleshooting

Build Fails

Check:

  • Java version (Java 8 or 11)
  • Ant version
  • Build log: /tmp/zimbra-federation-build.log

Solution:

# View full build output
cat /tmp/zimbra-federation-build.log

Patch Already Applied

Error: "patch: **** malformed patch"

Solution:

  • Check if federation is already implemented
  • Restore from backup if needed: 
    cp -r federation-backup-TIMESTAMP/* .

Federation Not Working

Check logs:

tail -f /opt/zimbra/log/mailbox.log | grep -i federation

Common issues:

  1. LDAP connectivity - test with telnet remote-zimbra 389
  2. LDAP credentials - verify with ldapsearch
  3. SOAP connectivity - test with telnet remote-zimbra 7071

Rollback

To rollback federation implementation:

# Restore from backup
cp -r federation-backup-TIMESTAMP/zm-mailbox/* zm-mailbox/

# Remove new files
rm -f zm-mailbox/store/src/java/com/zimbra/cs/account/ldap/FederatedProvisioning.java
rm -f zm-mailbox/store/src/java/com/zimbra/cs/service/mail/FederatedShareNotifier.java
rm -f zm-mailbox/store/src/java/com/zimbra/cs/service/mail/CreateFederatedMountpoint.java

# Rebuild
cd zm-mailbox
ant clean
ant -Dzimbra.buildinfo.version=10.0.0_GA_1 all

Support

For detailed implementation documentation, see:

  • FEDERATION_IMPLEMENTATION_GUIDE.md - Complete implementation guide
  • Generated deployment package DEPLOY.md - Deployment instructions

License

This federation implementation follows the same license as Zimbra Collaboration Suite Server (GPL v2).

Important Notes:

  1. Always backup your Zimbra instances before deploying
  2. Test in a non-production environment first
  3. Both Zimbra instances must run the same federation-enabled code
  4. Federation requires network connectivity between instances
  5. LDAP credentials must allow account lookup on remote instances