Install Rancher OS via iPXE

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

#!ipxe
# 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

boot

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.

rancher.cloud_init.datasources=[url:http://example.com/cloud-config]

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.

#cloud-config
ssh_authorized_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.