The OpenBI Gateway

OpenBI Gateway refreshes models on your OpenBI Server from files that only machines in your own network reach: an Excel file on a notebook, a folder on a file server. This page is for IT: what it does, how to install and register it, its commands and settings, and its security. It describes OpenBI Gateway 0.1.49.

What it does

A gateway is a named group of one to ten machines, its members, that refresh models for your OpenBI Server. Each member is OpenBI Gateway installed on a machine that reaches the data, and registered with your server. It connects out to your server and asks for work; when a model mapped to the gateway needs a refresh, a member runs it on its own machine and sends back the new data. Nothing on the machine listens to the network, and no cloud or relay sits in between: your server is the only other end.

A server in the same network as its data needs no gateway. It reads its sources itself, as it always has.

How a refresh runs

1. The member asks for work. Over HTTPS on port 443 it asks your server for a job; the server holds the question open until there is one, or for up to 50 seconds (a long poll). It speaks HTTPS only, checks the server’s certificate with the system’s own checks, and never follows a redirect.
2. The server picks a member for the refresh (see Two or more machines).
3. The member fetches the version that was published, checks it by its SHA-256 and unpacks it into its own scratch folder.
4. It refreshes in a strict mode. OpenBI’s engine reads only the files and folders declared on that machine for the model’s workspace. Anything else, another file, a database, the web, is refused before it is opened. It runs as the service’s own account, at low priority, with a memory cap.
5. It signs the result with its own key: the snapshot’s hash, the hash of each part, and the files it read.
6. The server checks it before it uses it: the signature, the size, every part and the whole file’s SHA-256, and that the data fits the version it was made for, in an engine with a memory cap that reads no source. Then it installs the data beside the version, which itself is never changed.
7. The history says where it ran: “Via the gateway ‘Sales’ on LAPTOP-07”, with the files it read and how much it sent.

If any check fails, nothing is installed and the report keeps its last good data. The member has no licence key of its own and never contacts the licence service: it works while your server’s licence allows refresh.

Two or more machines

A gateway has one to ten members. For each refresh, your server chooses among the members that are online, not disabled, on OpenBI Gateway 0.1.40 or later, and able to reach everything the model reads, as their latest tests say. Of those it takes the one with the most room (the fewest refreshes running for what it allows), then the lowest load. There is no primary member.

• A member that stops mid-refresh: when it has been quiet for 45 seconds, the refresh is tried once more on another member that can take it. What the first member had sent is discarded.
• Windows and Mac: a Windows path (D:\Sales, \\nas\data) is served by Windows members only, and a Mac’s path by Mac members only. Paths aren’t translated between systems. A model’s own project files (${PROJECT_DIR}) can be served by both.
• No member able: a refresh waits up to 15 minutes for a member that is busy, and a scheduled refresh also for a member that is offline. Otherwise it fails at once with each member’s reason, and the report keeps its last good data. A failed scheduled refresh is e-mailed to the people its schedule names.

Requirements

• OpenBI Server 0.1.40 or later. The server refuses members older than 0.1.40.
• On the machine: 64-bit Windows 10, 11 or Windows Server, or a Mac with Apple silicon and macOS 14 or later, and an administrator for the steps below.
• Network: HTTPS (port 443) out to your OpenBI Server. Nothing inbound.
• Licence: none of its own. It works while your server’s licence allows refresh.

Install

On Windows

Check the installer’s signature first. The status must be Valid, the signer Norway Analytics and its thumbprint 48D6BE98B89BE0766F85A2BC9136C85409B569D7:

Get-AuthenticodeSignature .\OpenBI-Gateway-0.1.49-x64.msi | Format-List Status, SignerCertificate

Then double-click it, or install it silently:

msiexec /i OpenBI-Gateway-0.1.49-x64.msi /qn /l*v gateway-install.log

On a Mac

Check the package first. pkgutil must name the Developer ID with Team ID 896HW73HL8, and spctl must answer accepted, source=Notarized Developer ID:

pkgutil --check-signature OpenBI-Gateway-0.1.49-arm64.pkg
spctl -a -vvv -t install OpenBI-Gateway-0.1.49-arm64.pkg

Then open it, or install it from Terminal:

sudo installer -pkg OpenBI-Gateway-0.1.49-arm64.pkg -target /

Create the gateway on your server

1. On OpenBI Server, open Settings (the gear) and choose Manage gateways.
2. Under New gateway, give it a name and tick the workspaces it serves.
3. Choose Make it and get its code. You get the command to run on the machine, and apart from it a one-time code, valid for 15 minutes, once.

Who may: a server administrator, or someone who is an Admin of every workspace the gateway serves, since a member serves all of them. The same holds for adding members later (Add a member on the gateway’s page), disabling and removing them, changing the gateway’s admins, letting it serve another workspace and removing it. The gateway’s admins and the server’s administrators are e-mailed when a machine joins. A code stops working when the workspaces the gateway serves change.

Any Admin of a workspace may stop a gateway serving it (Stop serving this workspace on the gateway’s page). Its models mapped to the gateway are then refreshed by the server itself again, and keep their last good data meanwhile.

Register the machine

On Windows, in PowerShell opened with Run as administrator; on a Mac, in Terminal:

cd "C:\Program Files\OpenBI Gateway"
.\OpenBI.Gateway.exe register --server https://bi.<domain>

sudo openbi-gateway register --server https://bi.<domain>

It asks for the code, showing nothing as you paste it. Before it keeps anything, it shows the server’s name, version and licensee, its certificate (subject, issuer, expiry and SHA-256) and the gateway the code is for, and asks you to type yes.

• --member-name <name> names the member on the gateway’s page; the machine’s own name is the default.
• In a script, pipe the code in with --yes, or give --code-file <file>, a file only its owner can read (chmod 600).
• On a Mac the code is never put on the command line: other accounts can see any command’s arguments there.

A machine is a member of one gateway at a time; to move it, run unregister first.

Declare what it may read

A member serves only what its own administrator declares on it, and your server can’t add to that. Each declaration has a name, one target and whom it serves:

.\OpenBI.Gateway.exe source add --name "Sales workbook" --file "C:\Data\Sales 2026.xlsx" --workspace Sales
.\OpenBI.Gateway.exe source add --name "Shared sales" --folder "E:\Shared\Sales" --workspace Sales
.\OpenBI.Gateway.exe source add --name "Budget project" --project "D:\Models\Budget" --item Sales/Budget
.\OpenBI.Gateway.exe source test

sudo openbi-gateway source add --name "Sales workbook" --file "/Users/Shared/Data/Sales 2026.xlsx" --workspace Sales
sudo openbi-gateway source test

Never declared: a drive’s or disk’s root, the system’s folders, a person’s whole profile (or all of them), hidden folders in a profile such as .ssh and a Mac user’s Library, programs’ AppData, the gateway’s own program and data folders, device paths, a share of the machine’s own, administrative shares (C$), and paths with .. or ;. A Windows path can’t be declared on a Mac. source add warns when people other than administrators may write in a declared folder.

Access: the service reads as its own account, NT SERVICE\OpenBIGateway or _openbigw, never as the person who installed it. Grant that account read access; when it can’t read a declaration, source test prints the fix, for example:

icacls "E:\Shared\Sales" /grant "NT SERVICE\OpenBIGateway:(OI)(CI)R"

On a Mac, people’s Desktop, Documents and Downloads folders, iCloud Drive and other volumes are kept private from services: give OpenBI Gateway Full Disk Access (System Settings, Privacy & Security), or keep the data in /Users/Shared.

The member tests every declaration when it changes and every five minutes, and reports to the server whether it reaches each.

Start it and check it

.\OpenBI.Gateway.exe service start
.\OpenBI.Gateway.exe status

sudo openbi-gateway status

On a Mac the daemon starts by itself within seconds of the registration. status shows where the member is registered, its engine and each declaration with ok or NO and why. On the gateway’s page the member shows as Online, and its Connections table shows what each member declares and whether its last test reached it.

Point a model at the gateway

In OpenBI Server, open the model’s settings. The section Gateway connection lists what the model reads against each member of the gateway, with a tick or the reason, and which member a refresh would run on now. Choose Refresh through ‘<gateway>’, then Use it. The workspace’s Admins and Members may do this. It is refused unless everything the model reads is declared on a member. None: the server reads its sources takes it back.

From then on, Refresh now and the schedule run through the gateway. The whole refresh runs on one member, so every source the model reads must be declared there.

Commands

On Windows, .\OpenBI.Gateway.exe <command> in an elevated PowerShell in C:\Program Files\OpenBI Gateway; on a Mac, sudo openbi-gateway <command>. register, status, source, member settings and sbom also answer in JSON with --json.

--data <folder> (or the variable OPENBI_GATEWAY_DATA) uses another data folder: a second member on one machine, for a test.

Settings

Each member’s settings are its own, set on the machine by its administrator with member settings:

The engine runs at low priority. A version larger than 2 GB is not downloaded.

Logs

• logs shows the end of the member’s log. The files are in logs in its data folder, one a day (gateway-<yyyymmdd>.log, one JSON line per event, never a secret).
• When the service doesn’t start: on Windows, the Application log under the source OpenBI Gateway and logs\service-start.log; on a Mac, /Library/Logs/OpenBI Gateway/launchd.log.
• On the server, each model’s refresh history, and the gateway’s page (Recent jobs: model, state, member and why that member).

Upgrade and uninstall

Upgrade: install the newer installer over it, the same way. The registration, the declarations and the settings stay. The service stops while its files are replaced (it tells the server, which gives a running refresh to another member) and starts again. On Windows a lower version is refused. Upgrade a gateway’s members one at a time.

Uninstall removes the service, the program and the command line, and leaves the data, so a reinstall resumes the membership:

msiexec /x OpenBI-Gateway-0.1.49-x64.msi /qn

sudo "/Library/OpenBI Gateway/uninstall.sh"

To leave the gateway for good, unregister first. On Windows, run unregister --all, uninstall, then delete C:\ProgramData\OpenBI Gateway. On a Mac, uninstall.sh --all does all of it, including the account _openbigw:

.\OpenBI.Gateway.exe unregister --all

sudo "/Library/OpenBI Gateway/uninstall.sh" --all

A machine that can no longer reach its server is removed on the gateway’s page instead (Members, Remove): its key stops working at once on every server node. On a Mac, status then says so, and unregister --all wipes what is left.

When your server moves to a new name

When your server’s administrators change its domain (see Change domain), its old names answer, for a transition period, with 308 Permanent Redirect to the same path under the new name. A member on OpenBI Gateway 0.1.49 or later follows that move by itself:

• It follows that redirect only: a 308 to an https address with the same path and query, and the same first label, bi. to bi., on another host. Any other redirect is refused as before.
• It asks for a new token at the new name, with its own key, and asks again once there. No token got from the old name ever goes to the new one.
• It keeps the new address in gateway.json or, where the service may not write that file, in logs\moved.json beside it, and says so once in its log: “The server moved from https://bi.<old> to https://bi.<new>: this member now connects to https://bi.<new> (saved).” status shows it.
• Registering at the old address registers at the new one, and says so.

A member that is off, or older than 0.1.49, for the whole transition is refused by the old name afterwards: register it again at the new address. Upgrade members to 0.1.49 before the domain changes.

Security

• Declared sources only. A member reads only what its own administrator declared, for the workspaces named; the server can’t widen it, and the engine refuses anything else before it opens it.
• Outbound only. HTTPS to your own server on port 443. No relay, no cloud, no Norway Analytics service in the path; nothing listening on the machine.
• Its own account. NT SERVICE\OpenBIGateway on Windows, _openbigw on a Mac (hidden, no shell, no home), reading only what you grant it. The program’s folder is the administrators’; the data folder is open to administrators and the service only, and the service writes only its cache, scratch and logs.
• Keys. Each member makes its own key pair (ECDSA P-256) when it registers. The private key never leaves the machine; it is sealed in its data folder (on a Mac with the seal in a folder of its own). The key gets short-lived tokens from the server, which keeps only their hashes. Removing a member revokes its key at once.
• Signed and checked. Each upload is signed by its member and checked by the server before it is installed (see How a refresh runs).
• Governance. Who may add machines and change a gateway is set out in Create the gateway; every change is in the server’s audit log, and a new member is e-mailed to the gateway’s admins and the server’s administrators.
• Signed installers. The MSI by Norway Analytics (Authenticode, thumbprint 48D6BE98B89BE0766F85A2BC9136C85409B569D7); the Mac package with Apple Team ID 896HW73HL8, notarized.
• Reviewed. Three independent security reviews of its code before release, by reviewers who did not build it. Every finding rated medium or higher was fixed; the last review cleared it for production.

The bill of materials

Installed beside the program: sbom.cdx.json (CycloneDX 1.5) and sbom.html, which loads nothing from the internet. It lists every third-party component, what it is for, its licence, each file with its SHA-256, and its known vulnerabilities, looked up in OSV and NVD when the installer was built. A known vulnerability in what ships, a stale file or a file the bill doesn’t list stops the build, unless Norway Analytics has assessed that finding as not exploitable as shipped and accepted it, by its id, for that component and version alone: sbom then lists it as ACCEPTED, and the bill carries the assessment for scanners. OpenBI Gateway 0.1.49 has none (see Accepted findings).

.\OpenBI.Gateway.exe sbom --verify

Its exit code: 0 checked, and no known vulnerability in what ships but those accepted; 1 no bill, or a file differs; 2 a known vulnerability in what ships that isn’t accepted; 3 not checked. --verify finds a stale or partial install; the proof against tampering is the installer’s signature.

What leaves the network

Only what goes to your own OpenBI Server: the refreshed data, signed; when the machine registers, its name, system, processor type, its own and its engine’s versions, and its public key; while it runs, its state and load, and its declarations with whether it reaches each. Nothing goes to Norway Analytics.

Good practice

• Declare folders whose parent folders only administrators can change. Someone who can write in a declared folder’s parent could swap the folder for a link to another one; source add warns about the folder itself.
• Mind the disk. A member keeps each version it downloaded in its cache until unregister; keep --max-parallel low on small disks.
• Leaving for another server? Run unregister --all: plain unregister keeps the declarations, which a new registration would serve at once.
• Certificates: the member checks your server’s certificate, but not whether it has been revoked.

Not yet

• Databases and web sources through a gateway come later, with their passwords typed and kept on the member. Today a member serves files, folders and project folders, so a model that also reads a database can’t be mapped to a gateway.
• Live queries: import refresh only. Live connections and DirectQuery through a gateway come later.
• Linux members come later.
• Updates are installed by hand on each member. Updates rolled out from your own server come later.

Frequently asked questions

Does the notebook have to be on?

Yes, at refresh time: awake, on the network and able to reach your server. Add a second member that reaches the same files, a file server for one, so that refreshes don’t depend on one notebook.

Does it need admin rights?

To install, register and declare, yes, once. After that it runs as its own restricted account, and the person using the machine needs no rights at all.

What if it’s off?

The refresh fails with each member’s reason, or a scheduled one waits up to 15 minutes first; the report keeps its last good data.

Last updated 6 November 2026 · OpenBI Gateway 0.1.49