6.13.2. OS Installation

RackHD workflow support installing Operating System automatically from remote http repository. Setting up RackHD OS repository with image service

Image servie provides a convinient method for users to setup OS repository, details please refer to https://github.com/RackHD/image-service. Alternatively, users could setup the repos by executing Configuring RackHD OS Mirrors and Making the Mirrors. Configuring RackHD OS Mirrors

Setting up a Windows OS repo

  • Mounting the OS Image:

Windows’ installation requires that Windows OS’ ISO image must be mounted to a directory accessable to the node. In the example below a windows server 2012 ISO image is being mounted to a directory name Licensedwin2012

sudo mount -o loop /var/renasar/on-http/static/http/W2K2012_2015-06-08_1040.iso /var/renasar/on-http/static/http/Licensedwin2012
  • Export the directory

Edit the samba config file in order to export the shared directory

sudo nano /etc/samba/smb.conf
    comment = not windows server 201
    path = /var/renasar/on-http/static/http/Licensedwin2012
    browseable = yes
    guest ok = yes
    writable = no
    printable = no
  • Restart the samba share
sudo service samba restart


Mirrors may not be something you need to configure if you’re utilizing the proxy capabilities of RackHD. If you previously configured proxies to support OS installation workflows, then those should be configured to provide access to the files needed. If you do not, or can not, utilize proxies, then you can host the OS installation files directly on the same instance with RackHD. The following instructions show how to create OS installation mirrors in support of the existing workflows.

Set the Links to the Mirrors:

sudo ln -s /var/mirrors/ubuntu <on-http directory>/static/http/ubuntu
sudo ln -s /var/mirrors/ubuntu/14.04/mirror/mirror.pnl.gov/ubuntu/ <on-http directory>/static/http/trusty
sudo ln -s /var/mirrors/centos <on-http directory>/static/http/centos
sudo ln -s /var/mirrors/suse <on-http directory>/static/http/suse Making the Mirrors

Centos 6.5

Notes: Because CentOS 6.5 was deprecated by provider, the following rsync source is not available to make mirror. Just leave it for an example.

sudo rsync --progress -av --delete --delete-excluded --exclude "local*" \
--exclude "i386" rsync://centos.eecs.wsu.edu/centos/6.5/ /var/mirrors/centos/6.5

Centos 7.0

sudo rsync --progress -av --delete --delete-excluded --exclude "local*" \
--exclude "i386" rsync://centos.eecs.wsu.edu/centos/7/ /var/mirrors/centos/7

OpenSuse 12.3

sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/distribution/12.3/ /var/mirrors/suse/distribution/12.3
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/12.3 /var/mirrors/suse/update
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/12.3-non-oss /var/mirrors/suse/update

OpenSuse 13.1

sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/distribution/13.1/ /var/mirrors/suse/distribution/13.1
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/13.1 /var/mirrors/suse/update
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/13.1-non-oss /var/mirrors/suse/update

OpenSuse 13.2

sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/distribution/13.2/ /var/mirrors/suse/distribution/13.2
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/13.2 /var/mirrors/suse/update
sudo rsync --progress -av --delete --delete-excluded --exclude "local*" --exclude "i386" --exclude "i586" --exclude "i686" rsync://mirror.clarkson.edu/opensuse/update/13.2-non-oss /var/mirrors/suse/update


[IMPORTANT] DNS server is required in Ubuntu 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;

[Method-1] For iso installation, see this payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_ubuntu_payload_iso_minimal.json Remember to replace {{ file.server }} with your own, see ‘fileServerAddress’ and ‘fileServerPort’ in /opt/monorail/config.json

mkdir ~/iso && cd !/iso

# Download iso file
wget http://releases.ubuntu.com/13.04/ubuntu-14.04.5-server-amd64.iso

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

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

# Mount iso
sudo mount ubuntu-14.04.5-server-amd64.iso /var/mirrors/ubuntu

sudo ln -s /var/mirrors/ubuntu {on-http-dir}/static/http/mirrors/

# Create workflow
# Replace the 9090 port if you are using other ports
# You can configure the port in /opt/monorail/config.json -> 'httpEndPoints' -> 'northbound-api-router'
curl -X POST -H 'Content-Type: application/json' -d @install_ubuntu_payload_iso_minimal.json{node-id}/workflows?name=Graph.InstallUbuntu | jq '.'

[Method-2] For live installation, see this payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_ubuntu_payload_minimal.json Remember to replace repo with your own {fileServerAddress}:{fileServerPort}/ubuntu, you can find the proper parameters in /opt/monorail/config.json

Add following block into httpProxies in /opt/monorail/config.json

  "localPath": "/ubuntu",
  "server": "http://us.archive.ubuntu.com/",
  "remotePath": "/ubuntu/"
# Create workflow
# Replace the 9090 port if you are using other ports
# You can configure the port in /opt/monorail/config.json -> 'httpEndPoints' -> 'northbound-api-router'
curl -X POST -H 'Content-Type: application/json' -d @install_ubuntu_payload_minimal.json{node-id}/workflows?name=Graph.InstallUbuntu | jq '.'

[Method-3] For the Ubuntu repo, you need some additional installation. The mirrors are easily made on Ubuntu, but not so easily replicated on other OS. On any recent distribution of Ubuntu:

    # make the mirror directory (can sometimes hit a permissions issue)
    sudo mkdir -p /var/mirrors/ubuntu/14.04/mirror
    # create a file in /etc/apt/mirror.list (config below)
    sudo vi /etc/apt/mirror.list
    # run the mirror
    sudo apt-mirror

############# config ##################
set base_path    /var/mirrors/ubuntu/14.04
# set mirror_path  $base_path/mirror
# set skel_path    $base_path/skel
# set var_path     $base_path/var
# set cleanscript $var_path/clean.sh
# set defaultarch  <running host architecture>
# set postmirror_script $var_path/postmirror.sh
# set run_postmirror 0
set nthreads     20
set _tilde 0
############# end config ##############

deb-amd64 http://mirror.pnl.gov/ubuntu trusty main
deb-amd64 http://mirror.pnl.gov/ubuntu trusty-updates main
deb-amd64 http://mirror.pnl.gov/ubuntu trusty-security main
clean http://mirror.pnl.gov/ubuntu

#end of file

Reference: Here are some useful links to vendor’s official website about Mirros setup. Supported OS Installation Workflows

Supported OSes and their workflows are listed in table, and the listed versions have been verified by RackHD, but not limited to these, this table will be updated when more versions are verified.

OS Workflow Version
ESXi Graph.InstallESXi 5.5/6.0
RHEL Graph.InstallRHEL 7.0
CentOS Graph.InstallCentOS 6.5/7
Ubuntu Graph.InstallUbuntu trusty(14.04)/xenial(16.04)/artful(17.10)
SUSE Graph.InstallSUSE openSUSE: leap/42.1, SLES: 11/12
CoreOS Graph.InstallCoreOS 899.17.0
Windows Graph.InstallWindowsServer Server 2012
PhotonOS Graph.InstallPhotonOS 1.0 OS Installation Workflow APIs

An example of starting an OS installation workflow for CentOS:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d @params.json \

An example of params.json with minimal parameters for installing CentOS workflow:

    "options": {
        "defaults": {
            "version": "7",
            "repo": ""

An example of params.json with full set of parameters for installing CentOS workflow:

    "options": {
        "defaults": {
            "version": "7",
            "repo": "",
            "rootPassword": "root12345",
            "hostname": "rackhd-node",
            "domain": "abc.com",
            "users": [
                    "name": "rackhd1",
                    "password": "123456",
                    "uid": 1010,
                    "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJQ631/sw3D40h/6JfA+PFVy5Ofz6eu7caxbv0zdw4fTJsrFcOliHZTEtAvqx7Oa8gqSC6d7v61M0croQxtt1DGUcH2G4yhfdZOlK4pr5McwtX0T/APACdAr1HtP7Bt7u43mgHpUG4bHGc+NoY7cWCISkxl4apkYWbvcoJy/5bQn0uRgLuHUNXxK/XuLT5vG76xxY+1xRa5+OIoJ6l78nglNGrj2V+jH3+9yZxI43S9I3NOCl4BvX5Cp3CFMHyt80gk2yM1BJpQZZ4GHewkI/XOIFPU3rR5+toEYXHz7kzykZsqt1PtbaTwG3TX9GJI4C7aWyH9H+9Bt76vH/pLBIn rackhd@rackhd-demo"
                    "name": "rackhd2",
                    "password": "123456",
                    "uid": 1011,
                    "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJQ631/sw3D40h/6JfA+PFVy5Ofz6eu7caxbv0zdw4fTJsrFcOliHZTEtAvqx7Oa8gqSC6d7v61M0croQxtt1DGUcH2G4yhfdZOlK4pr5McwtX0T/APACdAr1HtP7Bt7u43mgHpUG4bHGc+NoY7cWCISkxl4apkYWbvcoJy/5bQn0uRgLuHUNXxK/XuLT5vG76xxY+1xRa5+OIoJ6l78nglNGrj2V+jH3+9yZxI43S9I3NOCl4BvX5Cp3CFMHyt80gk2yM1BJpQZZ4GHewkI/XOIFPU3rR5+toEYXHz7kzykZsqt1PtbaTwG3TX9GJI4C7aWyH9H+9Bt76vH/pLBIn rackhd@rackhd-demo"
            "rootSshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJQ631/sw3D40h/6JfA+PFVy5Ofz6eu7caxbv0zdw4fTJsrFcOliHZTEtAvqx7Oa8gqSC6d7v61M0croQxtt1DGUcH2G4yhfdZOlK4pr5McwtX0T/APACdAr1HtP7Bt7u43mgHpUG4bHGc+NoY7cWCISkxl4apkYWbvcoJy/5bQn0uRgLuHUNXxK/XuLT5vG76xxY+1xRa5+OIoJ6l78nglNGrj2V+jH3+9yZxI43S9I3NOCl4BvX5Cp3CFMHyt80gk2yM1BJpQZZ4GHewkI/XOIFPU3rR5+toEYXHz7kzykZsqt1PtbaTwG3TX9GJI4C7aWyH9H+9Bt76vH/pLBIn rackhd@rackhd-demo",
            "dnsServers": ["", ""],
            "networkDevices": [
                    "device": "eth0",
                    "ipv4": {
                        "ipAddr": "",
                        "gateway": "",
                        "netmask": "",
                        "vlanIds": [104, 105]
                    "ipv6": {
                        "ipAddr": "fec0::6ab4:0:5efe:",
                        "gateway": "fe80::5efe:",
                        "netmask": "ffff.ffff.ffff.ffff.",
                        "vlanIds": [101, 106]
                    "device": "eth1",
                    "ipv4": {
                        "ipAddr": "",
                        "gateway": "",
                        "netmask": "",
                        "vlanIds": [105, 109]
                    "ipv6": {
                        "ipAddr": "fec0::6ab4:0:5efe:",
                        "gateway": "fe80::5efe:",
                        "netmask": "ffff.ffff.ffff.ffff.",
                        "vlanIds": [106, 108]
            "kvm": true,
            "installDisk": "/dev/sda",
            "installPartitions": [
                    "mountPoint": "/boot",
                    "size": "500",
                    "fsType": "ext3"
                    "mountPoint": "swap",
                    "size": "500",
                    "fsType": "swap"
                    "mountPoint": "/",
                    "size": "auto",
                    "fsType": "ext3"

There are few more payload examples at https://github.com/RackHD/RackHD/tree/master/example/samples.

Check the active workflow running on a node

curl <server>/api/current/nodes/<identifier>/workflows?active=true

Deprecated 1.1 API - Check the active workflow running on a node

curl <server>/api/1.1/nodes/<identifier>/workflows/active

Stop the currently active workflow on a node:

curl -X PUT \
-H 'Content-Type: application/json' \
-d '{"command": "cancel"}' \

Deprecated 1.1 API - Stop the active workflow to cancel OS installation:

curl -X DELETE <server>/api/1.1/nodes/<identifier>/workflows/active Non-Windows OS Installation Workflow Payload

All parameters descriptions of OS installation workflow payload are listed below, they are fit for use with all supported OSes except for CoreOS (see note below).

NOTE: The CoreOS installer is pretty basic, and only supports certain parameters shown below. Configurations not directly supported by RackHD may still be made via a custom Ignition template. Typical parameters for CoreOS include: version, repo, and installScriptUri*|*ignitionScriptUri and optionally vaultToken and grubLinuxAppend.

Parameters Type Flags Description
version String required The version number of target OS that needs to install. NOTE: For Ubuntu, version should be the codename, not numbers, for example, it should be “trusty”, not “14.04”
repo String required The OS repository address, currently only supports HTTP. Some examples of free OS distributions for reference. For CentOS, http://mirror.centos.org/centos/7/os/x86_64/. For Ubuntu, http://us.archive.ubuntu.com/ubuntu/. For openSUSE, http://download.opensuse.org/distribution/leap/42.1/repo/oss/. For ESXi, RHEL, SLES and PhotonOS, the repository is the directory of mounted DVD ISO image, and http service is provided for this directory.
rootPassword String optional The password for the OS root account, it could be clear text, RackHD will do encryption before store it into OS installer’s config file. default rootPassword is “RackHDRocks!”. Some OS distributions’ password requirements must be satisfied. For ESXi 5.5, ESXi 5 Password Requirements. For ESXi 6.0, ESXi 6 Password Requirements.
hostname String optional The hostname for target OS, default hostname is “localhost”
domain String optional The domain for target OS
users Array optional If specified, this contains an array of objects, each object contains the user account information that will be created after OS installation. 0, 1, or multiple users could be specified. If users is omitted, null or empty, no user will be created. See users for more details.
dnsServers Array optional If specified, this contains an array of string, each element is the Domain Name Server, the first one will be primary, others are alternative.
ntpServers Array optional If specified, this contains an array of string, each element is the Network Time Protocol Server.
networkDevices Array optional The static IP setting for network devices after OS installation. If it is omitted, null or empty, RackHD will not touch any network devices setting, so all network devices remain at the default state (usually default is DHCP).If there is multiple setting for same device, RackHD will choose the last one as the final setting, both ipv4 and ipv6 are supported here. (ESXi only, RackHD will choose the first one in networkDevices as the boot network interface.) See networkDevices for more details.
rootSshKey String optional The public SSH key that will be appended to target OS.
installDisk String/Number optional installDisk is to specify the target disk which the OS will be installed on. It can be a string or a number. For string, it is a disk path that the OS can recongize, its format varies with OS. For example, “/dev/sda” or “/dev/disk/by-id/scsi-36001636121940cc01df404d80c1e761e” for CentOS/RHEL, “t10.ATA_____SATADOM2DSV_3SE__________________________20130522AA0990120088” or “naa.6001636101840bb01df404d80c2d76fe” or “mpx.vmhba1:C0:T1:L0” or “vml.0000000000766d686261313a313a30” for ESXi. For number, it is a RackHD generated disk identifier (it could be obtained from “driveId” catalog). If installDisk is omitted, RackHD will assign the default disk by order: SATADOM -> first disk in “driveId” catalog -> “sda” for Linux OS. NOTE: Users need to make sure the installDisk (either specified by user or by default) is the first bootable drive from BIOS and raid controller setup. PhotonOS only supports ‘/dev/sd*’ format currently.
installPartitions Array optional installPartitions is to specify the installDisk‘s partitions when OS installer’s default auto partitioning is not wanted. (Only support CentOS at present, Other Linux OS will be supported). See installPartitions for more details.
kvm Boolean optional The value is true or false to indicates to install kvm or not, default is false. (ESXi, PhotonOS doesn’t support this parameter)
switchDevices Array optional (ESXi only) If specified, this contains an array of objects with switchName, uplinks (optional), and failoverPolicy (optional) parameters. If uplinks is omitted, null or empty, the vswitch will be created with no uplinks. If failoverPolicy is omitted, null or empty, the default ESXi policy will be used. See switchDevices for more details.
postInstallCommands Array optional (ESXi only) If specified, this contains an array of string commands that will be run at the end of the post installation step. This can be used by the customer to tweak final system configuration.
installType String optional (PhotonOS only) The value is minimal or full to indicate the type of installed OS, defualt installType is minimal
installScriptUri String optional The download URI for a custom kickstart/preseed/autoyast/cloud-config template to be used for automatic installation/configuration.
ignitionScriptUri String optional (CoreOS only) The download URI for a custom Ignition template used for post-install system configurations for CoreOS Container Linux
vaultToken String optional (CoreOS only) The token used for unwrapping a wrapped Vault response – currently only an Ignition template (ignitionScriptUri) or cloud-config userdata (installScriptUri) payload is supported.
grubLinuxAppend String optional

(CoreOS only) Extra (persistent) kernel boot parameters

NOTE: There are RackHD specific commands within all default install templates that should be copied into any custom install templates. The built-in templates support the above options, and any additional install logic is best added by copying the default templates and modifying from there. The default install scripts can be found in https://github.com/RackHD/on-http/tree/master/data/templates, and the filename is specified by the installScript field in the various OS installer task definitions (e.g. https://github.com/RackHD/on-tasks/blob/master/lib/task-data/tasks/install-centos.js)

remoteLogging Boolean optional If set to true, OS installation logs will be sent to RackHD server from nodes if installer supports remote logging. Note you must configure rsyslog on RackHD server if you want to receive those logs. Please refer to https://github.com/RackHD/RackHD/blob/master/example/config/rsyslog_rackhd.cfg.example as how to enable rsyslog service on RackHD server. Currently only CentOS installation supports this feature, we are still working on other OS installation workflows to enable this feature.

For users in payload:

Parameters Type Flags Description
name String required The name of user. it should start with a letter or digit or underline and the length of it should larger than 1(>=1).
password String required The password of user, it could be clear text, RackHD will do encryption before store it into OS installer’s config file. The length of password should larger than 4(>=5). Some OS distributions’ password requirements must be satisfied. For ESXi 5.5, ESXi 5 Password Requirements. For ESXi 6.0, ESXi 6 Password Requirements.
uid Number optional The unique identifier of user. It should be between 500 and 65535.(Not support for ESXi OS)
sshKey String optional The public SSH key that will be appended into target OS.

For networkDevices in payload, both ipv4 and ipv6 are supported

Parameters Type Flags Description
device String required Network device name (ESXi only, or MAC address) in target OS (ex. “eth0”, “enp0s1” for Linux, “vmnic0” or “2c:60:0c:ad:d5:ba” for ESXi)
ipv4 Object optional See ipv4 or ipv6 more details.
ipv6 Object optional See ipv4 or ipv6 more details.
esxSwitchName String optional (ESXi only) The vswitch to attach the vmk device to. vSwitch0 is used by default if no esxSwitchName is specified.

For installPartitions in payload:

Parameters Type Flags Description
mountPoint String required Mount point, it could be “/boot”, “/”, “swap”, etc. just like the mount point input when manually installing OS.
size String required Partition size, it could be a number string or “auto”, For number, default unit is MB. For “auto”, all available free disk space will be used.
fsType String optional File system supported by OS, it could be “ext3”, “xfs”, “swap”, etc. If mountPoint is “swap”, the fsType must be “swap”.

For ipv4 or ipv6 configurations:

Parameters Type Flags Description
ipAddr String required The assigned static IP address
gateway String required The gateway.
netmask String required The subnet mask.
vlanIds Array optional The VLAN ID. This is an array of integers (0-4095). In the case of Windows OS, the vlan is an array of one parameter only

For switchDevices (ESXi only) in payload:

Parameters Type Flags Description
switchName String required The name of the vswitch
uplinks String optional The array of vmnic# devices or MAC address to set as the uplinks.(Ex: uplinks: [“vmnic0”, “2c:60:0c:ad:d5:ba”]). If an uplink is attached to a vSwitch, it will be removed from the old vSwitch before being added to the vSwitch named by ‘switchName’.
failoverPolicy String optional This can be one of the following options: explicit: Always use the highest order uplink from the list of active adapters which pass failover criteria. iphash: Route based on hashing the src and destination IP addresses mac: Route based on the MAC address of the packet source. portid: Route based on the originating virtual port ID. Windows OS Installation Workflow Payload

Parameters Type Flags Description
productkey String required Windows License
domain String optional Windows domain
hostname String optional Windows hostname to be giving to the node after installation
smbUser String required Smb user for the share to which Windows’ iso is mounted
smbPassword String required Smb password
repo String required The share to to which Windows’ iso is mounted

Example of minimum payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_windows_payload_minimal.json

Example of full payload https://github.com/RackHD/RackHD/blob/master/example/samples/install_windows_payload_full.json