HeadSpin Documentation

On-Premise Fully Managed Network Admin

Network Admin

DNS Setup

Map the following host IP addresses to DNS A records in {domain}:


The following hosts need to be an alias of the unifiedcontroller <code class="dcode">({env}-unifiedcontroller-{index})</code>:


Deploying dnsmasq instead of replacing the *.headspin.io

The on-premise unit comes with a wildcard certificate for <code class="dcode">*.headspin.io</code> issued by DigiCert. This requires that the hostnames of all the hosts are under <code class="dcode">.headspin.io</code>, for example <code class="dcode">&lt;env>-unifiedcontroller.headspin.io</code>. The headspin.io zone is controlled by HeadSpin and not exposed for customers to modify; however, if customers want to keep the default certificate, they will need to be able to add the IPs for their hosts to the DNS zone. The solution is to use dnsmasq as the DNS server in the deployed subnet that overrides the customer host entries.

Install dnsmasq on a host on the subnet (call it <code class="dcode">&lt;env>-dnsmasq.headspin.io)</code>. This can be done on the subnet router. This can also be done on the unifiedcontroller. Add this config to <code class="dcode">/etc/dnsmasq.conf</code>:


Now in the DHCP server, set the DNS IP to that of dnsmasq host. At this point restart all the hosts (or refresh their leases with <code class="dcode">dhclient</code>) to update their DNS servers. dnsmasq is now deployed.

On the dnsmasq host, all overrides are places in <code class="dcode">/etc/hosts</code>. Add the entries there described by the <code class="dcode">dns_setup</code> guide.

Change the domain

The on-premise unit comes by default under the headspin.io domain. You are expected to mask the DNS entries listed in network_setup_checklist on the DNS server for the subnet, e.g. dnsmasq.

The next step is to move the unit into your domain. This affects the TLS certificates and SSH certificates, which will need to be re-deployed after changing the domain.

The TLS certificate needs to be isssued by a trusted root cert on each of the hosts. See the last section for setting up a custom root cert on each host for an in-house authority.

SSL Certificates and SSH Keys

SSL certs need to be wildcard, for <code class="dcode">*.&lt;domain></cod>, e.g. *.headspin.io for hosted, or <code class="dcode">*.headspin.&lt;customer></code> for on-premise.

<code class="dcode">{env}</code> below means the customer env.

The host role comes from the hostname, e.g. <code class="dcode">proxy-&lt;env>-&lt;geo></code> has role <code class="dcode">proxy</code>. Each role is set up with a template with a different file layout than the other roles.

Service Host Roles Type OS Certificate Files Notes
Controlfreak proxy SSL macOS 10.15 /Users/hs/.controlfreak/nginx/cert.pem
STF proxy SSL Ubuntu 16.04 /srv/stf/nginx/cert.pem
Janus (Media) proxy SSL Ubuntu 16.04 /opt/janus/share/janus/certs/cert.pem
Usage Scraper unifiedcontroller SSH Ubuntu 16.04 /home/ubuntu/headspinio-root/ To be deprecated
Platform Endpoints unifiedcontroller SSL Ubuntu 16.04 /etc/nginx/cert.pem
SSH proxy RSA Public Ubuntu 16.04 /home/hs/.ssh/authorized_keys deprecated in v1 setup
SSH proxy RSA Public macOS 10.15 /Users/hs/.ssh/authorized_keys deprecated in v1 setup
SSH unifiedcontroller RSA Public Ubuntu 16.04 /home/ubuntu/.ssh/authorized_keys
SSH proxy RSA Public Ubuntu 16.04 /etc/ssh/
SSH proxy RSA Public Ubuntu 16.04 /etc/ssh/


Generate a new signed SSL certificate (private, public, CA) and SSH key pair. Then replace the files above with the new files.

Configuring the email system

The emailer can be configured to use an SMTP server or Mailgun. The config is on the unifiedcontroller at $HEADSPIN_HOME/keys-{env}/email.yml. Below are the keys for email.yml.

# email.yml
mail_service: smtp | mailgun
default_headspin_email_address: from_addr, e.g. Company <support@company.com>
smtp_host: e.g. smtp.gmail.com
smtp_port: e.g. 587 (tls default)
smtp_mode: tls | ssl | plain
smtp_user: e.g. ops@headspin.io
smtp_pass: e.g. a1234567889
mailgun_api_key: key-b123456789
mailgun_domain: e.g. customer.com

After changing the email config, restart all services on the unifiedcontroller.

$ sudo supervisorctl restart all