Installation
Network and ports
Plan the firewall rules for the SQL Flow control plane, agents and log brokers, and see which side opens each connection.
SQL Flow components connect outbound wherever they can. Agents and log brokers dial the control plane, agents dial databases and brokers, and the control plane dials nothing in your data path. This page lists the rules to open on each host. For the full table with every setting, see Ports and network.
How the components connect
A pipeline without relay runs on one agent, which connects to both the source and the target.
Rules by host
Control plane
- Inbound: HTTPS from users' browsers, CLI machines, agents and brokers. In the hybrid model this is the hosted service on port 443. When you run the control plane yourself, it is the port you bind; the container image uses 5100.
- Outbound, air-gapped only: PostgreSQL (5432 by default). Optionally HTTPS to a mail provider and to webhook endpoints for notifications. Webhook endpoints need public addresses unless you allow private ones; see Notifications.
The control plane never connects to agents, brokers or databases. Connection tests in the wizard run on an agent.
Agent hosts
- Outbound: HTTPS to the control plane. TCP to each source and target the agent's pipelines use. TCP 7003 to each log broker it reads through. For a relay pipeline, the capture agent connects to TCP 7420 on the apply agent.
- Inbound: none, except TCP 7420 on an apply agent in a relay pipeline, from its capture agent.
Log broker hosts
- Outbound: HTTPS to the control plane.
- Inbound: TCP 7003 from the agents that read through the broker. Restrict the sources further with the broker's
--allow-ips.
Database hosts
- Inbound: the database's port, from the agents that capture from or apply to it. The control plane needs no access.
Change the default ports
| Port | Default | How to change it |
|---|---|---|
| Control plane | 443 (hosted), 5100 (container image) | Air-gapped: the https:// binding in ASPNETCORE_URLS. Agents and brokers then use the matching --control-plane URL. |
| Log broker data port | 7003 | Air-gapped: Broker:ListenPort on the control plane, for every broker. A second broker on the same host takes its own port with --listen-port. |
| Relay listener | 7420 | The port on the relay pairing in the pipeline wizard, per apply agent. Relay:ListenPort on the control plane sets the proposed default. |
Proxies and TLS inspection
Some firewalls and proxies decrypt HTTPS to inspect it, replacing the server's certificate with one from your organization's own certificate authority. Agents and brokers trust only the control plane's own certificate authority, which they stored at install, so they refuse the replaced certificate and can't install, enroll or connect, even though a browser on the same network reaches the control plane.
In the firewall or proxy, add an exception that doesn't decrypt traffic to the control plane's host name, often called a no-decrypt or bypass rule. The rule can still allow or block the traffic by host name.
Broker and relay connections are pinned the same way. If a firewall between those hosts decrypts TLS, exempt the broker and relay ports too (TCP 7003 and 7420 by default).
To send the agent's and broker's control-plane traffic through an HTTP proxy, set the HTTPS_PROXY and NO_PROXY environment variables in the service's environment, not in your shell, because a service doesn't inherit your shell's environment. The broker data port and the relay port are plain TCP connections between your hosts and don't go through an HTTP proxy.
A load balancer or reverse proxy in front of a control plane you run must pass the original Host header and connect to the control plane over HTTPS. The control plane builds the address it prints in install commands from the request it receives.
Verify
- On the Agents page, a newly installed agent or broker appears within seconds. If it doesn't, check outbound HTTPS from its host.
- In the pipeline wizard, Test connection & list tables runs on the agent, so it proves the agent's route to the source, and to the broker when the capture mode uses one.
