configure-replication-agent

What this skill does

# Configure AEM Replication Agent

This skill guides you through configuring replication agents in Adobe Experience Manager 6.5 LTS. Replication agents are the core mechanism for distributing content from Author to Publish environments, managing Dispatcher cache, and handling user-generated content flows.

## When to Use This Skill

Use this skill when you need to:
- Set up new replication agents for Publish instances
- Configure Dispatcher Flush agents for cache invalidation
- Implement Reverse Replication for user-generated content
- Add replication agents for multiple publish instances
- Troubleshoot or reconfigure existing replication agents
- Implement custom replication workflows

## Prerequisites

- AEM 6.5 Author instance running (typically port 4502)
- AEM 6.5 Publish instance(s) running (typically port 4503+)
- Administrator access to AEM Author environment
- Network connectivity between Author and Publish instances
- Understanding of your deployment topology (single/multiple publish instances)

## Replication Agent Types

AEM supports several replication agent types for different purposes:

| Agent Type | Purpose | Location | Serialization Type |
|------------|---------|----------|-------------------|
| **Default Agent** | Publishes content from Author to Publish | Author | Default |
| **Dispatcher Flush** | Invalidates Dispatcher cache | Publish | Dispatcher Flush |
| **Reverse Replication** | Returns user input from Publish to Author | Author (polling) + Publish (outbox) | Default |
| **Static Agent** | Stores static node representation to filesystem | Author/Publish | Static Content Builder |

## Configuration Workflow

### Step 1: Access Replication Agent Configuration

**Classic UI:**
1. Navigate to `http://localhost:4502/etc/replication/agents.author.html`
2. Or go to Tools → Replication → Agents on author

**Touch UI:**
1. Navigate to Tools → Deployment → Replication
2. Select "Agents on author"

### Step 2: Create or Edit Replication Agent

**For new agent:**
1. Click "New..." or "Create" button
2. Enter a unique name (e.g., `publish_instance_1`, `dispatcher_flush`)
3. Select template based on agent type
4. Click "Create"

**For existing agent:**
1. Select the agent from the list
2. Click "Edit" to open configuration

### Step 3: Configure Settings Tab

Essential settings to configure:

```
Field: Enabled
Value: ✓ (checked)
Purpose: Activates the replication agent

Field: Serialization Type
Values: 
  - Default (standard content replication)
  - Dispatcher Flush (cache invalidation only)
  - Static Content Builder (filesystem storage)
Purpose: Determines how content is packaged

Field: Retry Delay (ms)
Value: 60000 (default)
Purpose: Time between retry attempts on failure

Field: Agent User Id
Value: replication-service (create dedicated user)
Purpose: Service account with minimal required permissions
WARNING: Never use 'admin' account in production

Field: Log Level
Values: Error | Info | Debug
Purpose: Controls logging verbosity for troubleshooting
```

**Security Best Practice:**
Create a dedicated replication service account:
1. Navigate to Security → Users
2. Create new user `replication-service`
3. Grant minimum permissions: read on source paths, replicate privilege
4. Set this user in "Agent User Id" field

### Step 4: Configure Transport Tab

Configure connection details to target instance:

```
Field: URI
Format: http[s]://<hostname>:<port>/bin/receive?sling:authRequestLogin=1
Examples:
  - http://localhost:4503/bin/receive?sling:authRequestLogin=1
  - https://publish1.example.com:4503/bin/receive?sling:authRequestLogin=1

Field: User
Value: admin (or dedicated replication receiver account)
Purpose: Authentication to Publish instance

Field: Password
Value: [secure password]
Purpose: Authentication credentials

Field: OAuth Settings
Value: Leave empty unless using OAuth
Purpose: Alternative authentication mechanism

Field: NTLM Domain/Host/User/Password
Value: Configure if using Windows NTLM authentication
Purpose: Domain-based authentication

Field: SSL
Options:
  - Relaxed SSL: Allow self-signed certificates (development only)
  - Allow expired: Accept expired certificates (not recommended)
Purpose: SSL/TLS configuration
```

**Connection String Examples:**

| Scenario | URI Pattern |
|----------|-------------|
| Local Publish | `http://localhost:4503/bin/receive?sling:authRequestLogin=1` |
| Remote Publish | `https://publish.example.com:4503/bin/receive?sling:authRequestLogin=1` |
| Multiple Instances | Create separate agents for each: port 4503, 4504, 4505, etc. |

### Step 5: Configure Proxy Tab (Optional)

Only configure if network routing requires proxy:

```
Field: Proxy Host
Value: proxy.corporate.com

Field: Proxy Port
Value: 8080

Field: Proxy User/Password
Value: [proxy credentials if required]
```

### Step 6: Configure Extended Tab

Advanced HTTP settings:

```
Field: HTTP Method
Values: GET (default) | POST
Purpose: HTTP verb for replication requests

Field: HTTP Headers
Default headers:
  CQ-Action:{action}
  CQ-Handle:{path}
  CQ-Path:{path}
Purpose: Custom headers for replication requests

Field: Connection Timeout (ms)
Value: 10000 (default)
Purpose: Maximum time to establish connection

Field: Socket Timeout (ms)
Value: 10000 (default)
Purpose: Maximum time waiting for data

Field: Protocol Version
Values: HTTP/1.0 | HTTP/1.1
Default: HTTP/1.0
Purpose: HTTP protocol version
```

### Step 7: Configure Triggers Tab

Control when the agent activates:

```
Option: Ignore default
Effect: Excludes agent from default replication
Use case: Custom workflows only

Option: On Modification
Effect: Auto-activates on page changes
Use case: Automatic publishing workflows

Option: On Distribute
Effect: Triggers on distribution events
Use case: Package replication

Option: On Receive
Effect: Chains replication from incoming events
Use case: Multi-tier replication

Option: No Status Update
Effect: Doesn't update replication status
Use case: Read-only monitoring agents

Option: No Versioning
Effect: Skips version creation
Use case: Performance optimization
```

### Step 8: Test Connection

**Before enabling:**
1. Click "Test Connection" button in Transport tab
2. Verify success message: "Replication test succeeded"
3. Check for any authentication or connectivity errors

**Common test failures:**

| Error | Cause | Solution |
|-------|-------|----------|
| Connection refused | Publish instance not running | Start Publish instance |
| 401 Unauthorized | Invalid credentials | Verify user/password |
| Timeout | Network/firewall issue | Check connectivity, adjust timeouts |
| SSL handshake failed | Certificate issue | Configure SSL settings or update certificates |

### Step 9: Enable and Save

1. Ensure "Enabled" checkbox is checked on Settings tab
2. Click "OK" to save configuration
3. Agent status should show green indicator (idle/ready state)

## Agent-Specific Configuration

### Default Replication Agent (Author to Publish)

**Purpose:** Publishes content from Author to Publish environment

**Configuration specifics:**
- Serialization Type: **Default**
- Transport URI: `http://publish-host:4503/bin/receive?sling:authRequestLogin=1`
- Location: Author instance (`/etc/replication/agents.author`)
- Triggers: Enable "On Modification" for automatic publishing
- User: Dedicated replication-service account with read permissions

**Multiple Publish Instances:**
Create one agent per Publish instance:
- Agent 1: `publish_instance_1` → `http://publish1:4503/bin/receive`
- Agent 2: `publish_instance_2` → `http://publish2:4504/bin/receive`
- Agent 3: `publish_instance_3` → `http://publish3:4505/bin/receive`

### Dispatcher Flush Agent

**Purpose:** Invalidates Dispatcher cache when content is published

**Configuration specifics:**
- Serialization Type: **Dispatcher Flush**
- Transport URI: `http://dispatcher-host:80/dispatcher/invalidate.cache`
- Location: Publish instance (`/etc/replication/agents.publish`)
- HTTP Method: GET or