Module - Host Agent
Module - Host Agent
Breadcrumbs

Installation & Setup

Installation & Setup

Prerequisites

Before installation:

  1. Confirm that the Gateway is running Ignition 8.3.0.

  2. Obtain Factory Host Agent 3.0.0 through an approved distribution channel.

  3. Identify the intended Linux, Windows, or macOS host and matching Host Client package.

  4. Confirm outbound connectivity from the host to the externally reachable Gateway URL.

  5. Configure protected transport with a certificate trusted by the host operating system for production use.

  6. Define which Gateway users may download bundles, approve hosts, request mappings, and issue commands.

  7. Confirm that unsigned artifacts are permitted by organizational policy.

Installing the Module

  1. Use the Ignition Gateway's standard module-management workflow to install the Factory Host Agent module.

  2. Confirm that version 3.0.0 is enabled.

  3. Verify that the following pages are present:

    • HostAgent Status;

    • HostAgent Installers; and

    • HostAgent Settings.

  4. Verify that the pfce_host_agents tag provider is available.

Initial Configuration

Gateway and Network

Configure the Gateway so that setup bundles contain the externally usable scheme, host, and port. When a reverse proxy is present, it must preserve the correct external request information.

The Host Client initiates the connection. Network policy must allow outbound communication from the host to the Gateway URL; the module does not require the Gateway to initiate a separate inbound connection to the host.

Gateway Settings

The active user-facing settings include:

  • Websocket Idle Timeout (seconds);

  • Heartbeat Timeout (seconds);

  • Max Binary Frame Size (bytes); and

  • Max File Chunk Size (bytes).

Changes to socket-level settings take effect after the module or Gateway restarts. Leave values at their supplied defaults unless the deployment has a tested reason to change them.

Other visible settings in this release are descriptive or not wired to runtime behavior. See User Guide & Components before relying on a displayed control.

Configuration Roles

Gateway Administrator

The Gateway administrator:

  • installs and configures the module;

  • controls Gateway access;

  • generates and distributes setup bundles;

  • reviews and approves pending hosts;

  • requests file or serial mappings;

  • monitors status and results; and

  • revokes trust when required.

Host Operator

The host operator:

  • receives and protects the setup bundle;

  • extracts and starts the Host Client;

  • starts or stops the Host Client's Gateway service;

  • creates local mappings;

  • reviews Gateway-initiated permission requests; and

  • ensures that the Host Client process has operating-system access to mapped resources.

Host Client Setup

  1. Open HostAgent Installers on the Gateway.

  2. Select the package for the intended operating-system family.

  3. Choose Download Setup Bundle.

  4. Transfer the bundle securely to the intended host.

  5. Extract it into a location protected by native operating-system permissions.

  6. Run the Host Client from the extracted bundle.

  7. Open Status and select Start gateway service.

  8. Keep the service running while enrollment is pending.

The setup bundle contains a live, time-limited enrollment credential. Treat the complete bundle as confidential and remove unused copies according to organizational policy.

Download Installer Only does not include normal enrollment configuration and is not sufficient by itself for standard onboarding.

Host Approval

  1. Open HostAgent Status in the Gateway.

  2. Locate the pending host.

  3. Review the visible host identity and operating-system information.

  4. Confirm independently that the request belongs to the intended host.

  5. Select Approve.

  6. Verify that the Host Client becomes trusted and connected.

Do not approve an unexpected or unidentified request.

File and Directory Setup

  1. Open Permissions in the Host Client.

  2. Add an explicit directory path or review a Gateway request.

  3. Choose the narrowest scope and access mode that supports the workflow.

  4. Review the Diff & confirm summary.

  5. Select Apply changes.

  6. Keep the Gateway service running so the updated snapshot reaches the Gateway.

  7. Verify the mapping in Opt-In Permissions and in the managed tags where applicable.

Read-write mappings may permit replacement or permanent deletion. Avoid broad recursive mappings when a narrower mapping is sufficient.

Serial Setup

  1. Confirm that the host operating system detects the serial port.

  2. Add a specific port mapping in Permissions when possible.

  3. Use Allow all serial ports only when broad access is intentionally required.

  4. Save and confirm the mapping.

  5. Locate the authorized port in the serial area of the managed tag provider.

  6. Configure the device settings and apply them.

  7. Connect the port and confirm the reported current state.

Security Recommendations

  • Use protected WebSocket transport for production.

  • Use a certificate trusted by the host operating system and matching the configured Gateway hostname.

  • Apply least-privilege Ignition access to installer, approval, permission, and command operations.

  • Protect setup bundles and extracted Host Client configuration as sensitive material.

  • Protect Gateway backups containing module identity and trust state.

  • Approve only verified hosts and narrowly scoped mappings.

  • Do not work around certificate validation or manually alter identity information.

  • Confirm the risk acceptance process for unsigned artifacts.

Verification

After setup, confirm:

  • the module is enabled;

  • the Host Client service is running;

  • the host is connected and trusted;

  • heartbeat and telemetry values continue updating;

  • the intended mappings are active;

  • the pfce_host_agents provider shows the host;

  • approved files or serial ports appear as expected; and

  • command acknowledgements or transfer results confirm completed operations.

Last updated: