Self-Hosted Bindplane Enterprise Deployments

Enterprise environments often enforce strict network controls that prevent servers from reaching the public internet. This guide covers three strategies for deploying Bindplane and its collectors in these air-gapped or internet-restricted environments:

1. Gateways in the DMZ — a Bindplane Gateway collector sits in a DMZ or network boundary zone and proxies telemetry from fully isolated internal agents to the outside world.

2. Offline agent installation — install and manage collectors without relying on internet access to GitHub, using configuration management tooling or Bindplane's built-in offline package hosting.

3. Windows Event Forwarding (WEF) — for Windows servers locked down so completely that no outbound traffic is possible, use the native WEF mechanism to forward events to a collector that does have network access.

These strategies can be combined. A typical enterprise deployment might use a DMZ gateway alongside WEF for fully-locked-down Windows endpoints, with all agents installed offline via Ansible.

Prerequisites

• A self-hosted Bindplane Enterprise instance. See the VM installation guide for setup instructions.

• A valid Bindplane Enterprise license key. Offline package hosting and other features used in this guide require the Enterprise plan.

• Network access from the Bindplane server to PostgreSQL.

• Collectors meeting the supported operating system requirements.

Strategy 1: Deploy a Bindplane Gateway in the DMZ

The gateway pattern is the primary recommended architecture for air-gapped environments. The idea is simple: internal agents cannot reach Bindplane or external destinations, but a gateway collector sitting in the DMZ can. Agents forward their telemetry to the gateway over an internal network path; the gateway forwards it onward.

This strategy addresses two concerns at once: it keeps your internal servers fully isolated, and it limits how many machines need credentials for external destinations like SIEMs or cloud storage. Only the gateway nodes need outbound internet access and destination credentials.

How It Works

There are two types of gateways relevant here:

• Telemetry gateway — receives OTLP telemetry from agents and forwards it to destinations. Configured using the Bindplane Gateway source and Bindplane Gateway destination.

• OpAMP gateway — proxies OpAMP management traffic so that agents behind a firewall can still be managed by Bindplane. Uses the opampgateway extension. See the OpAMP Gateway feature guide for full reference.

In most air-gapped deployments you will use both: the OpAMP gateway so Bindplane can push configurations to isolated agents, and a telemetry gateway so those agents can deliver data to your destination.

Step 1: Deploy Bindplane in a Zone with External Access

Install the Bindplane server on a host that has outbound access to your license validation endpoint and, if applicable, your telemetry destination. Internal network segments must be able to reach Bindplane on port 3001 (configurable).

See the Install Bindplane Server guide for installation steps.

Step 2: Deploy a Gateway Collector in the DMZ

Install the BDOT Collector on a host in your DMZ or perimeter zone. This host must be reachable from your internal agents and must itself be able to reach Bindplane.

From the Bindplane UI, navigate to Agents and generate an install command for the gateway host platform. Run it on the gateway host.

If the gateway host also lacks internet access during installation, follow Strategy 2 (offline agent installation) to get the collector package onto the host first.

Step 3: Configure the Telemetry Gateway

In Bindplane, create a new Configuration for the gateway collector:

1. Add a Bindplane Gateway source. This opens a listener on ports 4317 (gRPC) and 4318 (HTTP) by default.

2. Add your destination(s) — for example, a SIEM or cloud storage destination.

3. Add any processors you want to run centrally (filtering, parsing, sampling).

4. Roll out the configuration to the gateway collector.

Step 4: Configure the OpAMP Gateway (Optional but Recommended)

If your isolated agents cannot reach Bindplane directly, add the OpAMP Gateway extension to the gateway collector's configuration so Bindplane can still manage them:

1. Open the Configuration for your gateway collector.

2. Click the extensions icon and add the OpAMP Gateway extension.

3. Set the upstream endpoint to your Bindplane OpAMP URL (for example, wss://bindplane.internal:3001/v1/opamp).

4. Set the downstream listener to 0.0.0.0:4320.

The resulting extension config that Bindplane pushes to the gateway looks like this:

extensions:
  opampgateway:
    server:
      endpoint: wss://bindplane.internal:3001/v1/opamp
      headers:
        Authorization: "Secret-Key ${env:OPAMP_SECRET_KEY}"
      connections: 3
    listener:
      endpoint: 0.0.0.0:4320

See the OpAMP Gateway feature guide for the full reference including TLS options.

Step 5: Point Internal Agents at the Gateway

For each internal agent, update its manager.yaml to point at the gateway instead of Bindplane directly:

# /opt/observiq-otel-collector/manager.yaml (Linux)
# C:\Program Files\observIQ OpenTelemetry Collector\manager.yaml (Windows)
endpoint: ws://<gateway-host>:4320/v1/opamp
secret_key: <your-bindplane-secret-key>

When using Bindplane to manage agent configurations, set the agent's destination to the Bindplane Gateway destination type pointed at the gateway host.

The secret_key in manager.yaml is the Bindplane project secret key, not a gateway-specific key. Authentication between the agent and the OpAMP gateway is handled by the key being forwarded upstream to Bindplane.

---

Strategy 2: Offline Agent Installation

When target hosts have no internet access, the standard one-line install script fails because it pulls the collector binary from GitHub. Bindplane Enterprise provides a built-in mechanism to host collector packages locally so the install can proceed entirely within your network. For mass deployments, configuration management tools like Ansible are the recommended approach.

Option A: Bindplane Offline Package Hosting (Enterprise)

Bindplane can host collector installer packages and serve them to agents during installation and upgrades. Enable this on your Bindplane server and upload the packages you need.

1. Enable Offline Mode in Bindplane

Edit /etc/bindplane/config.yaml and add offline: true:

name: default
apiVersion: bindplane.observiq.com/v1

offline: true

auth:
  secretKey: your-secret-key
  username: admin
  password: password
  sessionSecret: your-session-secret

network:
  host: 0.0.0.0
  port: '3001'
  remoteURL: http://bindplane.internal:3001

agentVersions:
  agentUpgradesFolder: /var/lib/bindplane/agent-upgrades

store:
  type: postgres
  postgres:
    database: bindplane

Restart Bindplane after saving:

sudo systemctl restart bindplane

2. Download and Upload the Collector Artifact Package

On a machine with internet access, download the collector artifact package from the BDOT Collector releases page:

curl -LO https://github.com/observIQ/bindplane-otel-collector/releases/download/v1.59.1/observiq-otel-collector-v1.59.1-artifacts.tar.gz

Transfer the file to a machine that can reach your Bindplane server, then upload it using the Bindplane CLI:

# Configure a CLI profile if you haven't already
bindplane profile set "local" \
  --remote-url "http://bindplane.internal:3001" \
  --username "admin" \
  --password "password"

bindplane profile use "local"

# Upload the artifact package
bindplane upload agent-upgrade ./observiq-otel-collector-v1.59.1-artifacts.tar.gz

Bindplane now serves this package to agents that request it. The Bindplane UI will show install commands that reference your local server rather than GitHub.

3. Install Agents Using the Local Install Script

From the Bindplane UI, navigate to Agents and copy the install command. In offline mode, the generated command references your Bindplane server as the package source. Run it on each target host within your internal network.

To delete old packages and free disk space, use: bindplane delete agent-version observiq-otel-collector-v1.59.1

Option B: Deploy Collectors via Configuration Management

For environments where you want to use existing CM infrastructure (Ansible, Chef, Puppet, or similar), you can install the collector package independently and provide the manager.yaml configuration so it connects to Bindplane automatically on first start.

Using Ansible

Bindplane provides an official Ansible role for deploying the BDOT Collector.

Clone the role into your playbook's roles directory:

git clone https://github.com/observIQ/bindplane-agent-ansible.git roles/bindplane_agent

Reference it in your playbook with the required parameters:

- name: deploy-bindplane-collectors
  hosts: all_servers
  become: yes
  roles:
    - role: bindplane_agent
      version: '1.59.1'
      endpoint: 'ws://bindplane.internal:3001/v1/opamp'
      secret_key: 'your-secret-key'

Run the playbook:

ansible-playbook playbook.yml -i inventory.yml

In an air-gapped environment, the Ansible role needs access to the collector package. Either pre-stage the .deb/.rpm/.msi package on an internal artifact repository, or configure the role to pull from your Bindplane server using the offline hosting feature described in Option A.

Manual manager.yaml Deployment (Chef, Puppet, or Any CM Tool)

If your CM tool does not use the Ansible role directly, the simplest approach is:

1. Distribute the collector binary package via your internal artifact repository.

2. Install the package using your CM tool's package resource.

3. Write the following minimal manager.yaml to the correct path:

endpoint: ws://bindplane.internal:3001/v1/opamp
secret_key: your-secret-key
labels: configuration=<your-configuration-name>

Default paths:

• Linux: /opt/observiq-otel-collector/manager.yaml

• Windows: C:\Program Files\observIQ OpenTelemetry Collector\manager.yaml

1. Start the observiq-otel-collector service.

The collector will connect to Bindplane on startup, register itself, and receive its pipeline configuration. No additional local configuration is required.

---

Strategy 3: Windows Event Forwarding (WEF)

Some Windows servers in regulated or high-security environments are configured with no outbound network connectivity whatsoever. Installing a collector on these hosts is not feasible. Windows Event Forwarding (WEF) provides a native Microsoft solution: a locked-down Windows server can push its event logs to a designated Windows Event Collector (WEC) host that does have network access.

Architecture

[Locked-down Windows servers]
    |  (WEF — WinRM over HTTPS, port 5986)
    v
[Windows Event Collector (WEC) host]  <--- has network access
    |  (BDOT Collector with Windows Event Log source)
    v
[Gateway or destination]

The WEC host is the only server that needs a Bindplane-managed collector installed. The locked-down Windows servers use the built-in Windows Event Forwarding mechanism and do not require any third-party software.

Step 1: Configure the Windows Event Collector Host

On the WEC host (a Windows Server with network access), enable the Windows Event Collector service:

# Enable and start the Windows Event Collector service
wecutil qc /q

# Verify the service is running
Get-Service -Name "Wecsvc"

Step 2: Create a WEF Subscription

Use wecutil to create a subscription that pulls events from source computers. Create a subscription configuration file subscription.xml:

<Subscription xmlns="http://schemas.microsoft.com/2006/03/windows/events/subscription">
  <SubscriptionId>SecurityEvents</SubscriptionId>
  <SubscriptionType>SourceInitiated</SubscriptionType>
  <Description>Security events from locked-down servers</Description>
  <Enabled>true</Enabled>
  <Uri>http://schemas.microsoft.com/wbem/wsman/1/windows/EventLog</Uri>
  <ConfigurationMode>MinLatency</ConfigurationMode>
  <Delivery Mode="Push">
    <Batching>
      <MaxItems>20</MaxItems>
      <MaxLatencyTime>3000</MaxLatencyTime>
    </Batching>
    <PushSettings>
      <Heartbeat Interval="40000"/>
    </PushSettings>
  </Delivery>
  <Query>
    <![CDATA[
      <QueryList>
        <Query Id="0">
          <Select Path="Security">*</Select>
          <Select Path="System">*[System[Level&lt;=3]]</Select>
        </Query>
      </QueryList>
    ]]>
  </Query>
  <ReadExistingEvents>false</ReadExistingEvents>
  <TransportName>HTTPS</TransportName>
  <ContentFormat>RenderedText</ContentFormat>
  <Locale Language="en-US"/>
  <LogFile>ForwardedEvents</LogFile>
  <AllowedSourceNonDomainComputers></AllowedSourceNonDomainComputers>
  <AllowedSourceDomainComputers>O:NSG:NSD:(A;;GA;;;DC)(A;;GA;;;NS)</AllowedSourceDomainComputers>
</Subscription>

Apply the subscription:

wecutil cs subscription.xml

Step 3: Configure Source Computers

On each locked-down Windows server (the event sources), configure the Windows Remote Management service and point it at the WEC host. This can be done via Group Policy for bulk deployment.

Using GPO (Computer Configuration > Administrative Templates > Windows Components > Event Forwarding):

• Set Configure the server address, refresh interval, and issuer certificate authority of a target Subscription Manager to: Server=https://<WEC-hostname>:5986/wsman/SubscriptionManager/WEC,Refresh=60

Or run directly on the source computer:

# Enable WinRM
winrm quickconfig -quiet

# Add the WEC server as a subscription manager
winrm set winrm/config/client '@{TrustedHosts="<WEC-hostname>"}'

Source computers only need outbound access to the WEC host on port 5986 (WinRM/HTTPS). No internet access is required on the locked-down servers.

Step 4: Install a Bindplane Collector on the WEC Host

Install the BDOT Collector on the WEC host using the install command from Bindplane (or via offline install if the WEC host is also internet-restricted). See Strategy 2 for offline installation options.

Step 5: Configure the Collector to Read Forwarded Events

In Bindplane, create a Configuration for the WEC host collector:

1. Add a Windows Event Log source.

2. Set the channel to ForwardedEvents — this is the log channel where WEF writes all forwarded events.

3. Enable Raw Logs under Advanced settings if you are sending to a SIEM like Google SecOps that performs its own parsing.

4. Add your destination.

5. Roll out the configuration to the WEC collector.

A single WEC host can collect forwarded events from many locked-down servers and forward them all through one Bindplane-managed collector. This consolidation reduces the number of collectors you need to manage and limits the number of hosts that need outbound network access.

---

Putting It All Together

A complete air-gapped enterprise deployment typically looks like this:

Layer	Component	Network Requirement
Bindplane server	Self-hosted on internal VM	Reachable from internal agents on port 3001
DMZ gateway collector	BDOT Collector with OpAMP + telemetry gateway	Outbound to Bindplane and destination; inbound from internal agents
Internal Linux/Windows agents	BDOT Collector	Outbound to DMZ gateway only
Locked-down Windows servers	No collector — WEF source only	Outbound to WEC host on port 5986 only
WEC host	BDOT Collector reading ForwardedEvents	Outbound to DMZ gateway

Network Ports Summary

Traffic	Source	Destination	Port
OpAMP agent management	Internal agents	DMZ gateway	4320
OpAMP gateway upstream	DMZ gateway	Bindplane server	3001
OTLP telemetry	Internal agents	DMZ gateway	4317/4318
OTLP telemetry forwarding	DMZ gateway	External destination	varies
Windows Event Forwarding	Locked-down Windows servers	WEC host	5986
OTLP from WEC	WEC host	DMZ gateway	4317/4318

---

Further Reading

• OpAMP Gateway — full reference for the OpAMP Gateway extension

• Agents v. Gateways — when to use the gateway pattern

• Offline Collector Package Installation and Upgrades — detailed reference for Bindplane's offline hosting feature

• Ansible Deployment — Bindplane Collector Ansible role

• Using TLS — securing traffic between agents, gateways, and Bindplane

• Golden Images and Ephemeral Collectors — pre-baking the collector into VM images for rapid deployment