Skip to content
Big Picture

Syncing Local License Server

This workflow covers synchronizing entitlements from cloud license servers to local license servers in air-gapped or regulated environments. Local servers pull entitlement updates via outbound-only connections.

Prerequisites

Section titled “Prerequisites”
  • Local license server deployed and configured
  • Outbound network access from local server to cloud server
  • API credentials for cloud server
  • Understanding of conflict resolution strategies

Understanding Local License Server Sync

Section titled “Understanding Local License Server Sync”

Local license server sync enables:

  • Outbound-only connections — Local server initiates connections (no inbound firewall requirements)
  • Pull model — Local server pulls entitlement updates from cloud
  • Conflict resolution — Handle conflicts between cloud and local entitlements
  • Scheduled sync — Configurable sync frequency and triggers

Step 1: Configure Sync

Section titled “Step 1: Configure Sync”

Configure sync on the local license server:

# Local server configuration
sync:
  enabled: true
  cloud_server_url: "https://cloud.bigpicture.io"
  local_server_id: "local-server-abc123"


  schedule:
    enabled: true
    interval: "1h"  # Sync every hour


  conflict_resolution: "cloud_wins"  # cloud_wins, local_wins, merge, manual


  authentication:
    method: "bearer_token"
    token: "${SYNC_TOKEN}"


  retry:
    max_attempts: 5
    initial_delay_seconds: 1
    max_delay_seconds: 300

Step 2: Initiate Sync

Section titled “Step 2: Initiate Sync”

Local server initiates sync request:

Terminal window
# On local license server
curl -X POST "http://localhost:8080/v1/sync/entitlements" \
  -H "Authorization: Bearer $LOCAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "last_sync_token": "sync_previous_token"
  }'

Response:

{
  "sync_token": "sync_abc123",
  "sync_timestamp": "2024-01-15T10:30:00Z",
  "changes": [
    {
      "action": "create",
      "entitlement": {
        "entitlement_id": "ent_abc123",
        "tenant_id": "tenant_xyz789",
        "product_id": "prod_xyz789",
        "policy": {
          "type": "concurrent",
          "max_seats": 25
        },
        "starts_at": "2024-01-01T00:00:00Z",
        "ends_at": "2024-12-31T23:59:59Z"
      }
    },
    {
      "action": "update",
      "entitlement": {
        "entitlement_id": "ent_def456",
        "ends_at": "2025-12-31T23:59:59Z"
      }
    },
    {
      "action": "delete",
      "entitlement_id": "ent_ghi789"
    }
  ]
}

Step 3: Apply Changes

Section titled “Step 3: Apply Changes”

Local server applies changes:

For create actions:

  • Create new entitlement in local database

For update actions:

  • Update existing entitlement in local database

For delete actions:

  • Delete entitlement from local database

Changes are applied according to the configured conflict resolution strategy.

Step 4: Handle Conflicts

Section titled “Step 4: Handle Conflicts”

If conflicts are detected:

Cloud wins (default):

  • Cloud server changes take precedence
  • Local changes are overwritten

Local wins:

  • Local changes take precedence
  • Cloud changes are ignored

Merge:

  • Merge changes where possible
  • Prefer more recent timestamp

Manual:

  • Flag conflicts for manual review
  • Don’t apply conflicting changes

Step 5: Check Sync Status

Section titled “Step 5: Check Sync Status”

Query sync status:

Terminal window
curl "http://localhost:8080/v1/sync/status" \
  -H "Authorization: Bearer $LOCAL_API_TOKEN"

Response:

{
  "status": "success",
  "last_sync_at": "2024-01-15T10:30:00Z",
  "last_sync_token": "sync_abc123",
  "next_sync_at": "2024-01-15T11:30:00Z",
  "sync_count": 150,
  "conflict_count": 0,
  "error_count": 0
}

Scheduled Sync

Section titled “Scheduled Sync”

Sync runs automatically based on schedule:

Configuration:

schedule:
  enabled: true
  interval: "1h"  # Sync every hour
  cron: null  # Or use cron: "0 * * * *"

Sync triggers:

  • Scheduled sync — Periodic sync based on schedule
  • Manual sync — Triggered via API or admin interface
  • Event-driven sync — Sync triggered by local events
  • Startup sync — Sync on local server startup

Manual Sync

Section titled “Manual Sync”

Trigger manual sync:

Terminal window
curl -X POST "http://localhost:8080/v1/sync/trigger" \
  -H "Authorization: Bearer $LOCAL_API_TOKEN"

Sync Failure Handling

Section titled “Sync Failure Handling”

If sync fails:

Retry logic:

  • Automatic retry with exponential backoff
  • Maximum retry attempts configurable
  • Alerts on persistent failures

Failure scenarios:

  • Network failure — Connection timeout, DNS resolution failure
  • Authentication failure — Invalid credentials, expired tokens
  • Data validation failure — Invalid entitlement data
  • Conflict resolution failure — Unresolvable conflicts

Monitoring Sync

Section titled “Monitoring Sync”

Monitor sync metrics:

Key metrics:

  • Sync success rate
  • Sync duration
  • Number of changes synced
  • Conflict count
  • Error count
  • Last sync timestamp

Alerts:

  • Sync failure after max retries
  • Repeated sync failures
  • Authentication failures
  • High conflict count

Best Practices

Section titled “Best Practices”

Outbound-only: Ensure sync uses outbound-only connections (no inbound firewall requirements).

Scheduled sync: Use scheduled sync for regular updates.

Conflict resolution: Choose appropriate conflict resolution strategy for your use case.

Retry logic: Implement robust retry logic with exponential backoff.

Monitoring: Monitor sync status and metrics regularly.

Authentication: Use secure authentication (bearer tokens or mTLS).

Error handling: Handle sync failures gracefully.

Audit trail: Maintain audit trail of sync operations.

Next Steps

Section titled “Next Steps”