Setting up relay agents

Install an agent near the target, pair it with the capture agent, open the relay port, and create a relayed pipeline.

A relayed pipeline needs two agents: the capture agent near the source, which the pipeline runs on, and an apply agent near the target. You pick the apply agent; the control plane pairs the two and sets up their mutual TLS.

Before you begin

• Install an agent near the target and approve it. See Agents. It needs the connector for the target's engine, network access to the target, and the target's credentials.
• Make sure both agents are online. A relay can't be paired, started or verified while either agent is offline.
• Plan the network path. The capture agent opens a TCP connection to the apply agent on the relay port, 7420 unless you change it. The apply agent's host must accept that connection. Both agents also need their usual outbound HTTPS connection to the control plane.
• Don't use a standby agent as the apply agent. An agent linked as a standby can't run pipeline work of its own.

Create a relayed pipeline

In the pipeline wizard, the relay is part of the Target step. The wizard offers it for every source and capture mode.

1. On the Source step, choose the source and its Capture mode, and choose the capture agent under Runs on.
2. On the Target step, choose the target.
3. Under Where this target is applied, set Apply this pipeline target on to apply agent (over the relay).
4. Fill in the target connection. Host names are resolved by the apply agent, so localhost means the apply agent's machine.
5. Click Test connection. The test runs on the apply agent.
6. Click Next. The Pair the relay screen opens, and Pair & verify runs on its own: the control plane pairs the agents, both agents enroll their relay identities, and the capture agent dials the apply agent.
7. Wait for the status line to read Verified: capture agent connected. If it reads Failed at, see Troubleshooting.
8. Click Next, and continue with Tables, Prepare and Review.
9. On Review, check the relay rows, then click Create and start.

See Relay for every field on the Pair the relay screen.

Apply a target on another agent

To relay a target you add to an existing pipeline:

1. Open the pipeline. On the Overview tab, in the Targets card, click Add target.
2. Choose the Target engine.
3. In Apply this target on, choose apply agent (over the relay).
4. In the relay panel that opens, click Pair & verify and wait for Verified:.
5. Fill in the target's connection and click Add target.

Targets applied by the same agent share one relay pairing and one endpoint. A pipeline created with a relay in the wizard can't add targets.

Open the relay port

The Pair the relay screen shows the exact rule under Details > Firewall, for example "Open TCP port 7420 on relay host (the relay agent's host) to capture agent."

• The apply agent listens on all its interfaces, or only on the address you give as Relay host when that address belongs to its host. You can also give an address the capture agent reaches through NAT, such as a public IP address.
• One apply agent uses one listening port for every pipeline paired with it. Once a pipeline uses the port, it can't change until no pipeline uses it.
• In an air-gapped deployment, you can change the proposed port for new listeners with the control plane setting Relay:ListenPort (Relay__ListenPort as an environment variable). An apply agent that already listens keeps its port.

The capture agent tries the Relay host you typed, if any, then the apply agent's own host names and IPv4 addresses, and keeps the first one that answers. Details > More details on the Pair the relay screen shows the list. If none of them is reachable from the capture agent, set Relay host.

Pairing states

Details > Pairing shows the pairing's state:

The wizard and Add target accept only a verified pairing. When the dial is refused, times out or can't resolve the host, Pair & verify keeps retrying for about 30 seconds before it reports the failure, because the apply agent may still be starting its listener.

Verify

• On the pipeline's page, the line under the metrics shows Relay with capture: and apply: both reporting.
• The Details card lists the Capture agent, Apply agent, Relay endpoint, Relay pairing and Relay security.

See Monitoring relay.

Troubleshooting

Failed at tcp, refused or timeout

The capture agent can't reach the apply agent on the relay port. Open the port on the apply agent's host and any firewall between them, check that the apply agent is online, then click Verify dial.

Failed at dns

The capture agent can't resolve the host. Click Change next to Relay host and enter a name or IPv4 address the capture agent can resolve and reach, then click Re-pair & verify.

Failed at tls or identity

The capture agent reached a listener, but the certificate didn't match the pinned identity or the TLS server name. Check that the host leads to the apply agent and not to another machine, review the agents' enrolled identities under Details, then click Verify dial.

Failed at pinned

A pipeline already uses this pairing, so its endpoint can't move. Delete the pipeline that references the pairing, then pair again.

"Port 7420 on … is already used by another pipeline."

Another pipeline uses the apply agent's listener. New pipelines share that port; to change it, delete the pipelines that use it first.

"A relay needs both agents online"

One of the two agents is offline or stale. Start its service, or choose another online agent.

See also

• How relay works
• Relay
• Network and ports
• On-premises SQL Server → Azure SQL over a WAN with relay agents