Using HIL as a Client

Interaction with HIL occurs via its REST API. The high-level semantics of the API are documented in API Description, and the mapping to HTTP is described in REST API.

The hil command line tool is a wrapper around this API. Running hil help will display an overview of the available commands. To tell hil which HIL instance to use, be sure to do one of:

  1. Set the HIL_ENDPOINT environmental variable. An example (using the default port used when running hil-admin run-dev-server) would be
  2. Ensure that there is a hil.cfg in the current directory which contains a valid client section. A valid config file in this case could look like
endpoint =
  • If both configuration methods are present, the HIL_ENDPOINT environmental variable will take precedence over whatever is contained within hil.cfg.
  • Though insignificant in some circumstances, the presence or absence of trailing slashes within the endpoint URL can cause issues in communicating with the HIL server, such as “404” errors. For example, using vs

If using the basic auth/database auth backend, you must set the environment variables HIL_USERNAME and HIL_PASSWORD to the correct credentials.

If using the auth/keystone auth backend, first make sure that the keystonemiddleware library is installed by running pip install keystonemiddleware. Next, ensure that there are OS environment variables set for the following OpenStack authentication credentials: OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME.

Deploying Machines

The most basic workflow for deploying machines onto a set of nodes allocated with HIL is as follows. First, create a headnode, and attach it to the network that the hardware nodes PXE boot off of. Then, enter the headnode by VNCing to it from the headnode host. The VNC port can be found with the REST show_headnode call. Authentication support is slated for a future release. From there, you can set up SSH access to the headnode, or you can continue to use VNC if you prefer.

Next, configure DHCP and TFTP servers that will boot nodes into some automated install image. We have an example of this in examples/puppet_headnode. In this example, we use Kickstart to automate a Centos install. Our kickstart file configures very little of the system, but complicated configuration can be done this way, especially by using Kickstart to install a tool such as Puppet.

Our setup has one additional trick. We run a server that, firstly, serves the Kickstart file, but secondly makes it so each node only PXE boots the installer once. The last thing each node does while installing is to tell the server to delete its symlink from the TFTP config, which will make the machine fall back to hard-disk booting the installed system.

This is, as the filepath states, merely an example of how you might deploy to physical nodes. Existing deployment systems such as Canonical’s MAAS have also been run succesfully.

Usage examples

Included here with are some examples about

  • Interacting with HIL API directly using the curl utility.
  • And using equivalent cli calls are also included.

1) Register a switch with HIL:

  • Switch name: mockswitch01
  • Switch type: mock
  • Host name: switchhost01
  • User name: switchuser01
  • Password: password1234

api call

curl -X put -d '
    {"type": "",
    "hostname": "switchhost01",
    "username": "switchuser01",
    "password": "password1234"}'

cli call

$ hil switch register mockswitch02 mock switchhost01 switchuser01 password1234

2) Registering a Node

  • Node name: dummyNoderHIL-02
  • OBMd uri: ````
  • OBMd admin token: d7c9e587124fb1cb0d03f79933a9ce28

For a node with the above information, use the following api call:

curl -X PUT -d '{
>     "obmd": {
>         "uri": "",
>         "admin_token": "d7c9e587124fb1cb0d03f79933a9ce28"
>     }
> }'

Corresponding cli calls will be as follows:

$ hil node register dummyNoderHIL-02 \  \

3) Creating a Project in HIL

  • Project name: mockproject01

api call

curl -X put

cli call

$ hil project create mockproject01

4) Register a node in HIL

  • Node name: mocknode01
  • Node type: mock
  • Host name: mockhost01
  • User name: nodeuser01
  • Password: password1234

api call

curl -X put -d '
> {"type": "",
> "hostname": "mockhost01",
> "username": "nodeuser01",
> "password": "password1234"}'

cli call

$ hil node register mocknode01 mock mockhost01 nodeuser01 password1234

4) Creating a Network in HIL

  • Network name: mocknetwork01
  • owner: admin
  • access: mockproject
  • net_id: 101

api call

curl -X put -d '
    {"owner": "admin",
    "access": "mockproject",
    "net_id": "101"}'

cli call

$ hil network create mocnetwork01 admin mockproject 101