Debian Installation

RackHD Debian installation support multiple versions. Please refer to Supported OS Installation Workflows to see which versions are supported. We’ll take Debian Stretch as the example below. If you want to install another version’s Debian, please replace with corresponding version’s image, mirror, payload, etc.


DNS server is required in Debian installation, make sure you have put following lines in /etc/dhcp/dhcpd.conf. is a default option in RackHD

option domain-name-servers;
option routers;

Setup Mirror

A mirror should be setup firstly before installation. For Debian, there are two ways to setup mirror currently.

  • Local ISO mirror: Download Debian ISO image, mount ISO image in a local server as the repository, http service for this repository is provided so that a node could access without proxy.
  • Public mirror: The node could access a public or remote site’s mirror repository with proxy.


For local mirror (ISO or sync), RackHD on-http service internally has a default file service to provide file downloading for nodes. Its default root path is {on-http-dir}/static/http/mirrors/. You also could use your own file service instead of the internal file service in the same server or another server, just notice that the file service’s ip address fileServerAddress and the port fileServerPort in /opt/monorail/config.json should be configured. For more details, please refer to Static File Service Setup. Remember to restart on-http service after modifying /opt/monorail/config.json.

For public mirror, RackHD on-http service also internally has a default http proxy for nodes to access remote file service. It could be configured by httpProxies in /opt/monorail/config.json. For more details, please refer to Configuration. Remember to restart on-http service after modifying /opt/monorail/config.json.

mkdir ~/iso && cd !/iso

# Download iso file

# Create mirror folder
mkdir -p /var/mirrors/debian

# Replace {on-http-dir} with your own
mkdir -p {on-http-dir}/static/http/mirrors

# Mount iso
sudo mount debian-9.4.0-amd64-xfce-CD-1.iso /var/mirrors/debian

# Replace {on-http-dir} with your own
sudo ln -s /var/mirrors/debian {on-http-dir}/static/http/mirrors/

Add following block into httpProxies in /opt/monorail/config.json, and restart on-http service.

  "localPath": "/debian",
  "server": "",
  "remotePath": "/debian/"

Call API to Install OS

After the mirror is setup, We could download payload and call workflow API to install OS.

Get payload example.


Call OS installation workflow API to install OS. is according to the configuration address and port of httpEndPoints -> northbound-api-router in /opt/monorail/config.json

curl -X POST -H 'Content-Type: application/json' -d @install_debian_payload_minimal.json{node-id}/workflows?name=Graph.InstallDebain | jq '.'

Please record the API’s returned result, it’s this workflow’s Id (like 342cce19-7385-43a0-b2ad-16afde072715), it will be used to check result later.


{{ file.server }} in payload will be replaced with fileServerAddress and fileServerPort in /opt/monorail/config.json by RackHD automatically while running. It also could be customized by {your-ip}:{your-port} for your own file service.

For more details about payload file please refer to Non-Windows OS Installation Workflow Payload

Check Result

You could use following API to check if installation is succeded. 342cce19-7385-43a0-b2ad-16afde072715 is the returned workflow Id returned from install OS API above, please replace it with yours.

curl -X GET{node-id}/workflows | jq '.[] | select(.context.graphId == "342cce19-7385-43a0-b2ad-16afde072715") | ._status'

If the result is running please wait until it’s succeeded.

You also could login the host console to see if installation succeed or not. By default, the root user will be created, and its password could be seen from rootPassword field from Non-Windows OS Installation Workflow Payload