HeadSpin Documentation


On-Premise Architecture (v1)

The full software capabilities form the dedicated hosted environment can be be deployed into an isolated network managed entirely by the customer. In the onprem deployment all of the customer data and intra-service communication remains inside the isolated network. Additionally usage of the isolated network is usually granted to users on the corporate LAN with a network address translation (NAT) from the customer LAN to the isolated network.

The onprem deployments comes with additional tools and hardware to make deployment, maintanance, and security of devices more seamless. The HeadSpin technologies specific to on-premise environment are below.

Technology Description
Management Tools The unifiedcontroller has a number of command line tools to scale and manage hosts, devices, and security inside the isolated network.
Physical layout and physical security The HeadSpin hardware and devices can be racked in an RF-neutral, data-center safe tray, or deployed inside a PIN-lock box that audits access and device removal.
Updates Software updates are delivered in a self-contained installer that runs on the unifiedcontroller inside the isolated network. The ease of installation allows customers to patch their on-premise deployments with the latest updates from the hosted platform.

Isolated Network

The hosts in the on-premise deployment should be connected to a LAN that has no packet route from inside the LAN to outside. The isolated LAN must have a DHCP server and DNS server, and allow packets from any IP in the LAN to reach any other IP in the LAN. Users on one or more separate networks should be granted access to the isolated LAN via a NAT. The separate networks must add DNS entries that refer to the translated address of hosts inside the isolated network.

While there are cell or wifi devices connected to proxy hosts inside the isolated network, no communication that originates inside the isolated network leaves the isolated network via a connected device. There may be man-in-the-middle captures for performance where packets from a device are routed to a host that intercepts all packets and retransmits them back out via a cell or wifi device; however, the information sent from the man-in-the-middle translation is a function of the packets originating from the device.

If you have questions or encounter obstacles in setting up your isolated network, please reach out to your HeadSpin administrators.

Management Tools

The on-premise unifiedcontroller comes with a number of command line tools to manage accounts, deploy new hosts, and perform security maintenance. A brief description of the tools is below, followed by the usage information for each tool.

Tool Description
hsops Manage users, auth, teams, and orgs.
hssecurity Manage host access.
hsbootstrap Wipe and prepare hosts for setup.
hssetup Setup a host for normal operation.

<code class="dcode">hsops</code>

  hsops org ls [--json]
  hsops org inspect <org_id>
  hsops org create-headspin-org
  hsops org create --name=<org_name> [--support_email=<support_email>]
                                     [--domains=<domains>] [--new_ui]
  hsops org modify <org_id> [--name=<name>] [--add_permissions=<permission>]
                            [--rm_permissions=<permission>] [--recursive]
  hsops org delete <org_id>
  hsops org-hosts modify <org_id> [--add_hosts=<hostnames>] [--rm_hosts=<hostnames>]
  hsops org-admin add <org_id> (--user_id=<user_id> | --email=<email>)
  hsops org-admin delete <org_id> --user_id=<user_id>
  hsops permission ls
  hsops feature-role create <role_id> --name=<name> --extra_permissions=<permissions>
  hsops user ls [--with_permissions=<permissions>]
  hsops user create --email=<email> --name=<name> --org_id=<org_id>
  hsops user create-with-auth-link --email=<email> --name=<name> --org_id=<org_id> --role_id=<role_id>
  hsops user inspect <user_id>
  hsops user modify <user_id> [--email=<email>] [--name=<name>] [--org_id=<org_id>]
  hsops team inspect <team_id>
  hsops team create --name=<name> --description=<description> --org_id=<org_id>
  hsops team modify <team_id> [--name=<new_name>]
                              [--add_permissions=<permission>] [--rm_permissions=<permission>]
                              [--description=<new_description>] [--recursive]
  hsops team delete <team_id>
  hsops team-user add <team_id> (--user_id=<user_id> | --email=<email>) [--role_name=<role_name>]
  hsops team-user delete <team_id> --user_id=<user_id>
  hsops team-hosts modify <team_id> [--add_hosts=<hostnames>] [--rm_hosts=<hostnames>]
  hsops host inspect <hostnames>
  hsops role create --name=<role_name> --add_permissions=<permissions> --org_id=<org_id> [--role_id=<role_id>]
  hsops role inspect <role_id>
  hsops role delete <role_id>
  hsops role modify <role_id> [--enable|--disable] [--name=<name>]
                              [--add_permissions=<permission>] [--rm_permissions=<permission>]
                              [--add_pools=<pool_keys>] [--rm_pools=<pool_keys>] [--team_id=<team_id>] [--org_id=<org_id>]
  hsops pool ls
  hsops pool reachability
  hsops pool create --key=<pool_key> --name=<pool_name> [--hosts=<hostnames>]
  hsops pool inspect <pool_key>
  hsops pool delete <pool_key>
  hsops pool modify <pool_key> [--name=<new_name>]
                               [--add_hosts=<hostnames>] [--rm_hosts=<hostnames>]
  hsops lease ls [--with_permissions=<permissions>] [--email=<email>]
  hsops lease create --user_id=<user_id> --role_id=<role_id>
  hsops lease delete --user_i


  hssecurity (-h | --help)
  hssecurity key status
  hssecurity key <role> [-y] [--user=<user_role>]
  hssecurity key create --name=<name>
  hssecurity key revoke <key>
  hssecurity user [--user=<user_role>]
  hssecurity certificate create
  hssecurity certificate sign server --key=<public-key> --hostname=<host> [--expiration=<time>]
  hssecurity certificate sign client --key=<public-key> --username=<name> [--expiration=<time>]
  hssecurity certificate show-server
  hssecurity certificate client-key
  hssecurity password create [--extra_chars]
  hssecurity password ls [--env=<env>] [--user=<user>] [--host=<host>]
  hssecurity ssh-config [--env=<env>]
  hssecurity check-server-ssh --host=<host>


    hsbootstrap env create <name>
    hsbootstrap env ls
    hsbootstrap env delete <name>
    hsbootstrap email setup [--env=<name>]
    hsbootstrap vpc create --env=<name> [--region=<region>] [--ip=<ip>]
    hsbootstrap vpn ls
    hsbootstrap vpn create [--env=<name>]
    hsbootstrap vpn setup [--env=<name> --identity=<pem>] --vpn-subnet=<subnet>
    hsbootstrap vpn sync [--env=<name> --identity=<pem>] [--no-reboot]
    hsbootstrap vpn sync-dns [--env=<name> --identity=<pem>]
    hsbootstrap vpn user add [--env=<name> --identity=<pem>] --user=<user> [--ip=<ip>] [--macos]
    hsbootstrap vpn user ls [--env=<name> --identity=<pem>]
    hsbootstrap vpn connect [--env=<name> --identity=<pem>]
    hsbootstrap syslog ls
    hsbootstrap syslog create [--env=<name>]
    hsbootstrap syslog setup [--env=<name> --identity=<pem>]
    hsbootstrap syslog vpn-ip [--env=<name>]
    hsbootstrap honeypot ls
    hsbootstrap honeypot create [--env=<name>]
    hsbootstrap honeypot setup [--env=<name>]


hssetup [options] host1 host2...
  --no-restart-vpn: Do not modify the machine to automatically restart the vpn

Physical Layout and Physical Security

Hosts on the isolated network are physically deployed into either a rack-mountable tray or PIN-lock enabled box. Auditing can be enabled to track user open of the box followed by device removal.

When the geo location of a tray or box changes, the hosts must be boostrapped to reflect the new location. For example if a host moves from us-sf to us-la, the host name would change from {env}-us-sf-0-proxy-0 to {env}-us-la-0-proxy-0. The boostrap process is designed to reset the host from scratch, so that a host can be shipped to the destination location in a wiped state.


When an on-premise unit is delivered, HeadSpin will securely send two configuration directories: keys-{env} and keys-{env}-red. These are the configuration and security configuration of the unit, respectively. They should be stored on a secure drive.

When an update installer is delivered, it will internally have the latest known keys-{env} and keys-{env}-red packaged. The customer may replace these with their copy of the keys. The installer will merge the in-place configuration with the packaged configuration according to the rules in the on-prem upgrade guide.


Changes to a customer environment are tracked by a cryptographically signed version file, shown below. Only a signed version of the softare may be deployed to a customer env.

  "number": "0.12.18", 
  "refs": {
    "common": "db6b8597cbb8df414e3a10e244b9969e5cadc135", 
    "controlfreak": "ef8deaa91b81c725023b7842606be9e33147ffa2", 
    "devtools": "0.12 37f1e0620e97d3d882ca800c3f88fdebb300ec44", 
    "docs": "da26d7bfc204b2da12a4f4e4afd718d464cb2f12", 
    "git-lfs": "17ca4a5b091cc94e8d5d6b486f2e610d2e6c21a3", 
    "headspin-cli": "febd210649bee0dff827e07b2db1c7cff789da2a", 
    "mar": "8f5f5d4e8012c43f4a4af61f8fb6818c0b856e71", 
    "mirrors": "3eb9bcba63dcb3634b6b7d281b9447e01ee48a67", 
    "mirrors-resources": "c5395063668585ffedfb7482f9c9b19ace3da614", 
    "mobile": "da71a24fa4b5521ae3cb21199dd92629601ca93d", 
    "mobile-opt": "69b88cf03885d786b473425557306976ab86cce4", 
    "ops": "0.12 bf4c8af545a58c7d3689e6da0cb469a17d2aa2d9", 
    "pbox": "0.12 9030272e09af17506f3ed474c21df96f7dfc7f81", 
    "platform": "0.12 fe341d24eb76965db870de8a1d8699bdbcfb8648", 
    "stf": "76e6364fc0e588ccdf2ec2fea7e0b8cc1097456f", 
    "tether": "8fcc2bdc4d89c914eb9081ac84152e99a56e9338", 
    "tp": "594acc48613cdb0c6a5bbd3058294a4638f66f5a", 
    "vendor": "87bc3321dc96705b819c58714999208d6e2fa903", 
    "web": "0.12 2b55ac54969028635444321eb2c81b75e65022b1"
  "schema_version": 1, 
  "timestamp": "2017-11-03 03:06:58"

Platform upgrades must be done from the unifiedcontroller using the on-premise installer. HeadSpon will provide a signed installer image that must be mounted on the unifiedcontroller. The on-premise upgrade guide covers usage of the on-premise installer.

File System Layout

Teams managing the on-premise environment may want to set up their own dev ops practive for SSH key management, SSL certificates, OS patches, and more. The file system layout document describes the file system layout of each host type - unifiedcontroller, proxy, display - so that the customer can automate the management of individual files if needed.

iOS Provisioning

Remote control and Appium execution on iOS devices in the environment require a provisioning profile provided by Apple. The environment comes set up with a profile provided by HeadSpin for a set of demo devices. However, the customer will need to move to a profile managed by the customer to use more devices beyond the initial set of demo devices. The iOS provisioning document describes the process for a customer to create a new provisioning profile and install it into the environment.


isolated net

There is one geo component per physcial location, for example us-nyc. The geo and host names are set by the customer using the host bootstrap tools. The geo component must be on the isolated network.