HS: Agent Architecture

Installer & System Setup

The Bodhi Agent is packaged for distribution as a digitally signed Microsoft Software Installer (MSI) named BodhAgentSetup-*.exe - where the * character references the specific machine’s processor architecture (x86 or x64). This MSI can be downloaded from the Internet at http://developer.bodhi.space/download

All software required by the agent is installed via this single MSI. The installer will install the following packages:

1. NSSM (available as public open source)
2. NodeJS (signed by Joyent Software)
3. Bodhi Agent (signed by HotSchedules)
4. BodhiAgent Uninstaller

The MSI allows the agent to install the agent anywhere on the local filesystem. The agent establishes the installation directory as its working directory via a shell variable (AGENT_DIR). This directory contains a stand alone directory structure. The general structure for the agent is described below:

/-AGENT_DIR

 |-/.storage (local & offline data storage)

 |-/node_modules (application components as CommonJS packages)

 |-.agent (binding information)

 |-agent.json (general configuration data)

 |-agent.pid (process identifier file)

 |-agent-cli.bat (system wrapper to command line functions)

 |-*.log (log files)

 |-*.msi (installers & uninstallers)

Note: The system has no dependency on the .Net Framework or the .Net CLR. The agent does not have a dependency on SQL Server or other RDBMS technology.

Agent Service

The agent process runs in the background as a windows service. The MSI creates the service binding for the Bodhi Agent during the installation process. The general interaction between the various components is described below:

NSSM - is a native, third-party service wrapper. The service wrapper provides the hooks for translating service manager events to the Bodhi Agent process. NSSM ensure the service starts on system reboot.

Bodhi Agent - is responsible for collecting POS data. The agent employs a number of different mechanisms for extracting data - polling, file system watchers, local network listeners, etc.

The Bodhi Agent can be managed via standard service management interfaces. It can be stopped such as Windows Task Manager or Windows Service Manager.

Network Usage

The worker process makes use of the BoH machines’ network stack. The diagram below describes the primary network interfaces and the external routes used by the worker:

Local Network Interface

The Bodhi Agent creates and listens on an embedded HTTP endpoint. The worker exposes an web service API endpoint and a single page web app for viewing configuration details over this interface. By default the endpoint listens on port 4444, but this port may be configured by an administrative use. The endpoint explicitly binds to the loopback address (127.0.0.1) limiting the connections it accepts to the local machine only. The binding address is not exposed as a configuration option and therefore may not be changed by an administrative user.

External Network Routes

All agents communicate with two external service providers. The primary service is the hotschedules.io cloud at https://hotschedules.io. The secondary service is the Bodhi Agent application repository at https://rbcplatform.artifactoryonline.com/. All communication with these service is encrypted using TLS 1.2 on port 443. The agent initiates all communication to these services. The services have no means to address the agent or establish a network connection to the agent. Requests to each of these services requires authentication tokens stored in files restricted to the agent.

In addition the customer may define additional external routes for use by the agent. This type of configuration is application specific and beyond the scope of this document.

Configuration & Installation Requirements

The machine should permit the download of the BodhiAgent from http://developer.bodhi.space/download

The machine must allow the installation of the BodhiAgentSetup-*.exe.

The machine must resolve the network addresses for hotschedules.io and rbcplatform.artifactoryonline.com via DNS.

The machine must resolve the network addresses for hotschedules.io and rbcplatform.artifactoryonline.com via DNS.

The machine must allow the agent’s core executable (node.exe) to establish connections on the remote ports 80 (http)  and 443 (https).

The agent must be allowed to listen on a user defined  unrestricted port (port > 1024) bound to the local interface address (127.0.0.1).  

The machine must allow connections to the servers on hotschedules.io

The agent must be allowed to verify the identify of the above servers using the traditional TLS exchange. The operating system must trust the certificate authorities in the trust chains below.

Trust Chain for hotschedules.io

ROOT: DigiCert High Assurance EV Root CA

INTERMEDIATE: |-> DigiCert SHA2 High Assurance Server CA

SEVER: |-> *.hotschedules.io

Note: The agent MAY be configured to use a web proxy to connect to the Internet. This configuration MAY be authenticated using HTTP Basic.

The most common tasks required to complete a standard integration are:

1. Opening specific ports on any firewalls to enable communication with our services (aka ‘whitelisting’).
2. Ensuring bandwidth spike rules don’t prevent Agent from downloading the appropriate POS package.
3. Disabling or adjusting any virus scanners / malware protection software that sometimes detects our Agent as a potential virus / malware.
4. Configuring things like content filtering to not block returns of requests. Content filtering is most often part of the firewall configuration.
5. High-speed internet connection, ie. no dial-up or cellular connection.