Learn How To Install Rancher OS via iPXE

February 27, 2020

Table of Contents

Rancher OS is a very lightweight Linux distribution built around Docker. The OS itself weighs in around 20MB. This tutorial will get you up and running with a persistent Rancher OS using all of the available disk space. Cloud-config instructions are not included in this doc.

  1. Create a new Custom PXE start up script and name it RancherOS.
  2. Paste in the script template below.
  3. Generate a new secure password and replace CHANGETHIS.
  4. Save the script.
  5. Deploy a new server using the ISO Custom option and select iPXE and your new RancherOS script from the dropdown.
  6. Wait several minutes for the installation to complete.
  7. Login with rancher@xxx.xxx.xxx.xxx and your new password.
  8. Setup is complete. At this point you can start configuring your rancher server or bootstrap it server to another rancher server.

Script template

# Boots RancherOS in Ramdisk with persistent storage on disk /dev/vda
# Location of Kernel/Initrd images
set base-url http://releases.rancher.com/os/latest
kernel ${base-url}/vmlinuz rancher.state.dev=LABEL=RANCHER_STATE rancher.state.autoformat=[/dev/vda] rancher.password=CHANGETHIS
initrd ${base-url}/initrd

Security note

While setting the rancher.password kernel parameter works, the Rancher team advises not doing this in production. Kernel parameters will be readable by any container launched, including unprivileged ones. A better method would be to add an SSH key via cloud-config. Specifying a cloud-config file is done by adding a kernel parameter. An example of this parameter is shown below. You would need to replace the URL in the parameter to the location of your cloud-config file.


Here is an example cloud-config file template that includes SSH keys. This file is in YAML format. Replace the SSH keys in the template with one or more of your own keys.

  - ssh-rsa AAA...ZZZ example1@rancher
  - ssh-rsa BBB...ZZZ example2@rancher

More information on using cloud-config with Rancher OS is provided in the official documentation.

Need help?

Do you need help setting up this on your own service?
Please contact us and we’ll provide you the best possible quote!