Gateway Agent

Note

<relay-host> below is the Fresco BI relay of your region. The Add gateway dialog in Fresco BI shows the commands with the real address filled in.

The Gateway Agent lets Fresco BI read a database that sits inside your own network. It runs on one of your machines, reads the database over your LAN, and only calls out to the Fresco BI relay <relay-host> on port 443. You open no inbound port.

When you need it

Connection type	Use it when	Firewall
Cloud	The database is reachable from the internet (RDS, Azure SQL, a VM with a public IP)	Allow Fresco BI’s IP addresses on the database
On-premises (via Gateway)	The database is in a private network, for example 10.0.0.10:5432	Nothing inbound; the agent machine calls out to <relay-host>:443

Machine requirements

	Minimum	Recommended
CPU	1 vCPU (Ubuntu), 2 vCPU (Windows)	2 vCPU
RAM	2 GB (Ubuntu), 4 GB (Windows)	4 GB (Ubuntu), 8 GB (Windows)
Free disk	2 GB	10 GB
OS	Ubuntu 24.04 64-bit (the tested system); Windows Server 2019 or later, Windows 10 (1809) or Windows 11, x64	The same, kept up to date
Network	Outbound HTTPS (443) to <relay-host>; reach from the machine to each database host and port	10 Mbit/s or more upload to <relay-host>

• Each bundle brings its own Python and every library it needs, so you install nothing first, and installing needs no internet access (Ubuntu and Windows).
• Keep the machine on; for failover add a second machine (see Several agents).

Where the numbers come from: the agent uses about 150 MB of memory when idle. It runs at most 4 tasks at a time, each in its own process of about 150 MB; data is streamed in batches of about 8 MB and never written to disk, so a large table needs more time, not more memory. Each task process is capped at 2 GB of memory. The installed program (with its own Python) takes about 0.6 GB; an upgrade needs room for a second copy, plus logs. The rest is for the operating system (Windows needs more than Ubuntu).

Bandwidth decides how long a refresh takes: 1 million rows of 5 columns is about 100 MB, about 80 seconds at 10 Mbit/s.

Size up (more RAM and CPU, or a second machine, see Several agents) when many refreshes run at the same time (beyond 4 tasks they wait in line), when you import large tables often, or when reports query the gateway live (realtime).

Where to install: two layouts

Both work on Ubuntu and on Windows.

Layout	Data source host	Allow list cidr
(a) Agent on a separate machine B, database on machine A	A’s internal IP, for example 10.0.0.10	"10.0.0.10/32" (A’s IP)
(b) Agent on the database machine itself	127.0.0.1 (or localhost)	"127.0.0.1/32"

Layout (b) allows exactly one loopback address (127.0.0.1/32 or ::1/128). A loopback range such as 127.0.0.0/8 is refused outside dev and test.

Network rules

The agent opens every connection itself: it calls out to the Fresco BI relay and to your databases. Fresco BI never connects into your network, so you open no inbound port and need no VPN, port forwarding or public IP on the agent machine.

Rules to open

Give these rules to your network or security team. Replace <agent IP> with the internal IP of the agent machine.

#	Direction	Source	Destination	Protocol / port	Needed for
1	Outbound	<agent IP>	<relay-host>	TCP 443 (HTTPS, TLS 1.2+)	Always: enrollment, tasks, results, and the bundle download
2	Outbound	<agent IP>	Each database host, for example 10.0.0.10	TCP, the database port: PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521	Always
3	Outbound	<agent IP>	Your DNS servers	UDP/TCP 53	Always: resolve <relay-host> and database host names
4	Outbound	<agent IP>	Your NTP servers	UDP 123	Always: the clock must be within 2 minutes of real time
5	Inbound	anything	<agent IP>	none	Never

• Allow <relay-host> by name (FQDN rule) if your firewall supports it. Its IP addresses can change; do not pin one IP.
• Rule 2 is inside your LAN. Open only the databases this agent reads, and list the same hosts and ports in the allow list (policy.toml). The agent refuses any other destination even if the firewall allows it.
• Rule 4 matters: every request to the relay is signed with a timestamp. A clock more than 2 minutes off is refused (gateway-unauthorized). On Ubuntu, timedatectl must show System clock synchronized: yes.
• Installing needs no internet: the bundle contains everything, including its own Python. Rule 1 is enough to download it with wget (see Install on Ubuntu).
• Bandwidth: plan 10 Mbit/s or more upload from the agent to <relay-host>.

HTTPS proxy and TLS inspection

• If outbound traffic must go through a proxy, set HTTPS_PROXY=http://proxy.example.local:3128 for the service (Ubuntu: sudo systemctl edit fresco-gateway and add Environment=HTTPS_PROXY=... under [Service]; Windows: a machine-wide environment variable). The proxy must allow CONNECT <relay-host>:443.
• Best: exempt <relay-host> from TLS inspection. Calls stay open for up to 20 seconds (long polling) and carry results of several MB, which some inspecting proxies cut.
• If your proxy must inspect it, enroll with --ca-file /path/to/company-ca.pem (the PEM file of the CA your proxy signs with). The agent then trusts that file only, not the system store, so the file must include every CA it needs.

Check from the agent machine

Run these before you enroll:

# DNS and HTTPS to the relay: expect an HTTP status (401 or 404), not a timeout or a TLS error
curl -sS -o /dev/null -w '%{http_code}\n' https://<relay-host>/gw/v1/poll -X POST

# Your database port: expect "succeeded"
nc -vz 10.0.0.10 5432

# Clock
timedatectl | grep synchronized

On Windows, use Test-NetConnection <relay-host> -Port 443 and Test-NetConnection 10.0.0.10 -Port 1433.

1. Create the gateway in Fresco BI

1. Gateways › Add gateway. Enter a name, for example HQ.
2. Confirm with your MFA code.
3. The dialog shows a one-time enrollment token (valid 1 hour) and the install steps. Keep it open.

2. Install on Ubuntu (systemd)

Download and verify

The agent machine already reaches <relay-host> on 443 (rule 1 of Network rules), so download the bundle there directly. The dialog, tab Ubuntu (systemd), shows these commands with the current version filled in. If the tab shows no wget command, this server does not offer the download from the relay yet: use the browser download below. The commands:

wget https://<relay-host>/gw/v1/agent/fresco-gateway-agent-<version>.tar.gz
echo "<SHA-256 from the dialog>  fresco-gateway-agent-<version>.tar.gz" | sha256sum -c -

The check must print fresco-gateway-agent-<version>.tar.gz: OK. The command checks the file against the SHA-256 the dialog shows (you are signed in there), not against a hash downloaded from the same server. If it prints FAILED, do not install; download again. The relay allows a few downloads per minute per address and may answer 503 for a moment when many machines download at once: wait a minute and run it again.

No outbound access on this machine yet? Click Download fresco-gateway-agent-<version>.tar.gz in the dialog, copy the file to the agent machine (for example with scp), and check it with sha256sum fresco-gateway-agent-<version>.tar.gz against the value in the dialog.

Install

tar -xzf fresco-gateway-agent-<version>.tar.gz
cd fresco-gateway-agent
sudo ./install.sh

The installer creates the system user fresco-gw, installs the agent in /opt/fresco-gateway, writes the allow list /etc/fresco-gateway/policy.toml (only the first time), creates the state directory /var/lib/fresco-gateway (mode 0700) and enables the fresco-gateway service. The service starts only after enrollment. The installer first copies the bundle into a private folder only root can open and installs from that copy; it refuses to run if another user could change the unpacked files (unpack in your home folder, not a shared one). Running it again with a newer bundle upgrades: if the upgrade fails, the previous version is put back and restarted.

Allow list

Edit /etc/fresco-gateway/policy.toml (see Allow list below):

sudo nano /etc/fresco-gateway/policy.toml

Enroll

sudo -u fresco-gw fresco-gateway --state-dir /var/lib/fresco-gateway enroll \
  --url https://<relay-host> --token-file - --name "$(hostname)"

Paste the token, press Enter, then Ctrl-D. The command prints:

Registered. Compare this fingerprint with the one shown in Fresco: XXXX-XXXX-…

Start

sudo systemctl start fresco-gateway
systemctl status fresco-gateway

3. Install on Windows (service)

Run every command in PowerShell as Administrator.

Download and verify

1. In the dialog, tab Windows (service), click Download fresco-gateway-agent-windows-<version>.zip.
2. Copy the file to the agent machine.
3. Check the SHA-256. The Hash must equal the value shown in the dialog (case does not matter):

Get-FileHash .\fresco-gateway-agent-windows-<version>.zip -Algorithm SHA256

Install

Unblock-File .\fresco-gateway-agent-windows-<version>.zip
Expand-Archive -Path .\fresco-gateway-agent-windows-<version>.zip -DestinationPath .
cd .\fresco-gateway-agent-windows
powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer puts the agent and its own Python in %ProgramFiles%\FrescoGateway, creates %ProgramData%\FrescoGateway with state (keys, enrollment, audit.log), logs and policy.toml (only the first time), readable only by SYSTEM, Administrators and the service, and registers the FrescoGateway service (account NT SERVICE\FrescoGateway, delayed automatic start, restart on failure). The service starts only after enrollment. The agent refuses to start if its state folder is open to anyone else; run install.ps1 again to reset the access lists.

Allow list

notepad "$env:ProgramData\FrescoGateway\policy.toml"

Enroll

Read-Host 'Enrollment token' | & "$env:ProgramFiles\FrescoGateway\fresco-gateway.cmd" --state-dir "$env:ProgramData\FrescoGateway\state" enroll `
  --url https://<relay-host> --token-file - --name $env:COMPUTERNAME

Paste the token at the Enrollment token prompt and press Enter (it stays out of the PowerShell history). The command prints the fingerprint.

Start

Start-Service FrescoGateway
Get-Service FrescoGateway

Allow list (policy.toml)

The agent connects only to the networks, ports and connector types listed here, whatever a data source asks. An empty list denies everything. Keep each entry narrow: one /32 per database.

PostgreSQL:

env = "prod"

[[allow]]
cidr = "10.0.0.10/32"
ports = [5432]
connectors = ["postgres"]

MySQL and SQL Server on one host:

[[allow]]
cidr = "10.0.0.20/32"
ports = [3306, 1433]
connectors = ["mysql", "sqlserver"]

Agent installed on the database machine (layout b):

[[allow]]
cidr = "127.0.0.1/32"
ports = [5432]
connectors = ["postgres"]

connectors takes the connector type of the data source: postgres, mysql, mariadb, sqlserver, and so on.

A network wider than /24 (IPv4) or /64 (IPv6) is refused unless you add i_understand_broad = true:

[[allow]]
cidr = "10.20.0.0/16"
ports = [5432]
connectors = ["postgres"]
i_understand_broad = true

Always refused: link-local and cloud metadata addresses (169.254.0.0/16…), multicast, reserved ranges, and any loopback range wider than one address (127.0.0.0/8). Optional limits:

[limits]
max_rows = 1000000
timeout_s = 225

The agent reads the file at start: restart the service after a change (sudo systemctl restart fresco-gateway, or Restart-Service FrescoGateway).

4. Approve in Fresco BI

1. Back in the dialog, the agent appears with its name, host, version and fingerprint.
2. Compare it with the fingerprint printed on the machine. To print it again:

sudo -u fresco-gw fresco-gateway --state-dir /var/lib/fresco-gateway fingerprint

& "$env:ProgramFiles\FrescoGateway\fresco-gateway.cmd" --state-dir "$env:ProgramData\FrescoGateway\state" fingerprint

3. Tick I have compared the fingerprint, then Approve. If they differ, click Reject.

5. Create the data source

1. Workspace › Sources › New source, pick the connector.
2. Connection type: On-premises (via Gateway), choose the gateway cluster.
3. Enter the database host as the agent machine sees it: A’s internal IP (layout a, for example 10.0.0.10) or 127.0.0.1 (layout b). Then port, user, password.
4. Test connection, then Save.

Check status

• Gateways page: cluster status (Online, Degraded, Offline), each member’s heartbeat, version, allow list size and policy hash.
• Ubuntu: systemctl status fresco-gateway and journalctl -u fresco-gateway -f.
• Windows: Get-Service FrescoGateway; Event Viewer › Windows Logs › Application, source FrescoGateway (warnings and errors); Get-Content "$env:ProgramData\FrescoGateway\logs\gateway.log" -Tail 50 -Wait.
• Each task the agent runs is written to audit.log in the state directory (time, task, connector, result; no data, no passwords).

Several agents (failover)

Install the agent on a second machine and enroll it into the same gateway: Gateways, open the gateway, Add member, confirm with MFA, and follow the same steps with the new token. Tasks go to any online member; when one stops, the others carry on. Give every member the same allow list: the Gateways page warns when policies differ.

Upgrade

Download the new bundle from the dialog, verify its SHA-256, then run the installer again. The allow list and the enrollment are kept, and the service restarts on the new version.

• Ubuntu: unpack, then sudo ./install.sh.
• Windows: unpack, then powershell -ExecutionPolicy Bypass -File .\install.ps1. It stops the service, replaces the program files, keeps the policy, keys and logs, and starts the service again.

Uninstall

Run the uninstall command on the agent machine. It first tells Fresco BI that this machine leaves the gateway (signed with the machine’s own key, no user sign-in), so Fresco BI never accepts it again and the gateway can be deleted at once. Then it stops and removes the service, the keys and enrollment, the allow list and the program files, and prints a confirmation line.

Ubuntu:

sudo /opt/fresco-gateway/uninstall.sh

Windows (PowerShell as Administrator):

powershell -ExecutionPolicy Bypass -File "$env:ProgramFiles\FrescoGateway\install.ps1" -Uninstall

If the machine cannot reach the relay, the command stops and changes nothing. Add --force (Ubuntu) or -Force (Windows) to remove the agent anyway: Fresco BI then shows the member as possibly connected until it has had no heartbeat for 24 hours.

Delete a gateway

In Gateways, open the gateway and click Delete. Delete is allowed when:

• setup never finished (no member was approved), or
• every member is fully disconnected: uninstalled with the command above, revoked, or without a heartbeat for at least 24 hours,

and no data source uses the gateway. Otherwise the dialog shows what blocks it: the data sources that use it, and each member with its status. Delete asks you to sign in again and to type the gateway name.

The gateway moves to Settings > Trash for 30 days. Its members are revoked and open enrollments are cancelled. Restore brings the gateway back, but its members stay revoked: enroll an agent again (Continue setup).

Revoke a member

To stop one machine without uninstalling it, open the gateway and click Revoke on the member. A revoked agent stops and does not restart; uninstall it from the machine afterwards.

The Windows agent does not support SSH tunnels: the gateway already runs inside your network, so connect to the database directly.

Troubleshooting

What you see	Meaning	What to do
Download: “The Gateway Agent bundle is not available on this server”	The server has no bundle for that system	Ask your Fresco BI administrator
SHA-256 does not match	The file is incomplete or changed	Download again; never install it
error: the relay refused the request (enrollment-invalid)	Token wrong, already used or expired	Create a new token in the dialog
already enrolled: remove the state directory to enroll again	This machine is already a member	Revoke the old member, remove the state directory, enroll again
error: … is wider than /24: set i_understand_broad	Allow list entry too wide	Narrow the cidr or add i_understand_broad = true
error: … overlaps an always-blocked range	Metadata, link-local or similar range	Remove that entry
gateway-unavailable: “No Gateway Agent of this cluster is online”	No member online	Check the service and outbound 443 to <relay-host>
gateway-offline: “The gateway is offline; the connection cannot be tested”	Same, at Test connection	As above
gateway-cluster-required	On-premises chosen without a cluster	Pick a gateway cluster
gateway-not-supported	This connector is Cloud only	Use Cloud
blocked_address	The host is not in the allow list (or is blocked)	Add its address, port and connector to policy.toml, restart
dns_failure	The agent machine cannot resolve the host	Use an IP or fix DNS on the agent machine
network_unreachable	Nothing listens there, or a firewall between agent and database	Check host, port and the internal firewall
timeout	The database did not answer in time	Usually a firewall dropping packets
tls_error	The SSL mode does not match the server	Check the SSL mode and the CA certificate
auth_failed	Wrong user or password	Fix the credentials
Member “Revoked”, service stopped	The member was revoked	Enroll again with a new token if needed

Security notes

• The enrollment token works once and for 1 hour. It is read from standard input, never from the command line, so it stays out of shell history and process lists. Fresco BI keeps only its hash.
• Approve a member only after comparing the fingerprint.
• Keys and state live in a directory only the service account and administrators can read (/var/lib/fresco-gateway, mode 0700; %ProgramData%\FrescoGateway\state, an access list with only SYSTEM, Administrators and NT SERVICE\FrescoGateway).
• Data source passwords are sealed for the gateway and opened only on the agent machine.
• The allow list is yours: Fresco BI cannot change it.
• audit.log records each task the agent ran.