Retail Node Installer (RNI)
The Retail Node Installer (RNI) is a collection of scripts that enables network-wide PXE booting of customizable operating systems, referred to as "profiles". It has a lightweight footprint, requiring only Bash, Docker, and Docker Compose. Profiles can be any typical Linux distribution, such as RancherOS.
The main executable to setup a device as a Retail Node Installer is
build.sh. This script will automatically build a few Docker images, download necessary files as required by profiles, prepare the PXE boot menu, and launch the following dockerized services:
dnsmasq (provides DHCP and TFTP services)
Currently, only RancherOS is provided as an example profile. This profile uses a special kickstart to run
bootstrap.sh and install Rancher to disk. Future releases of Retail Node Installer aim to include enhanced integration with more popular operating systems.
This document will guide you through the following:
The following is required:
Profile - The git URL for at least one profile is required. You will be asked to paste the URL into the configuration file in the following instructions.
Retail Node Installer - Minimum Recommended Hardware or VM with 2 CPUs, 20GB HD and 2GB of RAM, running any Linux Distro (headless recommended) that supports Docker
docker18.09.3 or greater
docker-composev1.23.2 or greater (use the official installation guide)
bashv4.3.48 or greater
Target Device(s) - Bare-Metal or Virtual Machine(s) with the necessary specifications for your use case. The profile defines what will we be installed on the Target Device. Note: The Target Devices will be wiped clean during typical usage of the Retail Node Installer.
The Retail Node Installer must have a static IPv4 address. Additionally, Retail Node Installer must be the only DHCP server on the network. This means that any existing routers/gateway/switches that are acting as DHCP servers must have their DHCP-serving functionality disabled.
Because RNI is OS-agnostic and Docker-based, the configuration of your system's network is not something that this guide will cover.
Target Devices will be connected on the same LAN as the Retail Node Installer. On target devices, enable PXE Boot in the BIOS if it is not enabled. Most BIOS's have a boot menu option (F12) at POST time. Typically you can press (F12) to alter the boot sequence.
Installing the RNI
Once the prerequisites and network setup have been taken care of, the steps to deployment are as follows.
Clone the Retail Node Installer repository using your git protocol of choice, and navigate into the cloned directory - use the following code snippet as an example:
git clone -b master https://github.com/intel/retail-node-installer.git retail-node-installer cd retail-node-installer
cp conf/config.sample.yml conf/config.yml
The config file can look something like this - please modify the values below, this is not intended to be a working example:
--- dhcp_range_minimum: 192.168.1.100 dhcp_range_maximum: 192.168.1.250 network_broadcast_ip: 192.168.1.255 network_gateway_ip: 192.168.1.1 network_dns_secondary: 22.214.171.124 rni_ip: 192.168.1.11 profiles: - git_remote_url: https://github.com/intel/rni-profile-base-rancheros.git git_branch_name: master git_username: "" git_token: "" name: rancher-profile custom_git_arguments: ""
Make changes according to your needs, including your GitHub username and token if needed (using a password is not recommended for security reasons), with the following guidance:
- Under the
profilessection, update the git remote to match the HTTPS-based git remote URL for the Rancher profile.
- Ensure that the network configuration matches your needs. If values are not specified, Retail Node Installer will default to a
/24network with a DHCP range of
- For special situations, custom git flags can be added on the fly by setting
custom_git_arguments. It must be defined (see next bullet point), so if no custom git flags are needed, specify
- Every profile must have all values defined in the config. For example, you cannot remove
custom_git_arguments; you must specify a value. This is a known limitation.
nameof the profile will appear as a boot menu option on the target device's PXE menu. It can be any alphanumeric string.
./build.sh as root from the root folder. This script will perform various tasks, such as downloading files for the configured profiles in
conf/config.yml, generating a PXE boot menu, and other things. Depending on the profiles you've selected, the build process can take a few minutes, and is hands-off.
./run.sh as root. This will start the Retail Node Installer services. It is safe to press
ctrl+C to quit out of logging safely at any time.
Retail Node Installer has now been deployed successfully! The next step is to build a target device, which is detailed just below.
Building Target Devices
Booting Target Devices
Make sure the Retail Node Installer is the only active DHCP server in your LAN. If you have not already, disable DHCP on the router, switch, or any other network interface in your LAN.
Boot the target device while connected to your LAN. Make sure you boot this device from network instead of local disk or cd-rom. This will initiate the PXE boot of your target device from the Retail Node Installer.
After installation, the device will reboot. Manually select the local disk boot option in the PXE menu when it comes up. If the terminal comes up without an error message and notification to check the error log, then it has built successfully!
Users can get a list of all flags supported by running
Troubleshooting the Retail Node Installer
Log information is available in
rni.log in the root folder. In order to monitor the logs you can run
docker-compose logs -f
If it becomes necessary to delete the Retail Node Installer containers and re-create them, run
./run.sh -f (assuming there are no target devices in your network that are attempting to boot while running this command).
You can use
./run.sh -r to restart the Retail Node Installer containers.
For any other problems that you may encounter during deployment, please consult the Known Limitations section.
This section is not required for setting up an Retail Node Installer and building target devices, but it provides valuable information about profiles, templating, and file downloads that will help you build your own profiles.
Kernel arguments can be specified in a file called
conf/config.yml in the profile's repository, not in Retail Node Installer itself, like this:
--- kernel_arguments: rancher.cloud_init.datasources=[url:http://@@RNI_IP@@/profile/@@PROFILE_NAME@@/dyn-ks.yml]
Variables surrounded by
@@ symbols are handled by the templating engine in Retail Node Installer. Please read Templating for more information on this topic.
Retail Node Installer has a few essential templating capabilies that assist with profile configuration.
In a profile's
conf/config.yml, for the
kernel_arguments variable only, the following template variables are supported:
Any file with the suffix
.rnitemplate in a profile will support all of the above as well as:
File Downloads and Dependencies
A profile will likely require external files in order to boot and install. This is solved by specifying them in
conf/files.yml inside the profile repository, not in Retail Node Installer itself. For an example, please see the
files.yml.sample in the Rancher profile.
conf/config.ymlfile must specify ALL values comprehensively, as shown in the
conf/config.sample.yml. Please use
""for empty values.
sshprotocol for cloning git repositories is not currently supported. Please provide a
git_remote_urlthat uses the HTTPS protocol.
- IPv6 is not supported.
- Using a GitHub token or password is currently the only method of authenticating with git. SSH keys are not currently supported.
- Retail Node Installer must be run on a Linux-native file system, such as
ext4. Filesystems that cannot properly preserve file permissions are not supported.
- On some distributions of Linux (such as newer versions of Ubuntu 18.04),
systemd-resolvedis already running a DNS server on
localhost. This will cause the Retail Node installer to fail to start due to port binding conflicts. To fix this:
./build.shnormally. It will fail at the final deployment step.
/etc/systemd/resolved.confto include the line
- This step will cause your network connection to drop. Run
sudo systemctl daemon-reload && sudo systemctl restart systemd-resolved.service
./run.shto restart the Retail Node Installer services.
- Test that network connectivity works.
- Proceed to deploy your target devices.
- Retail Node Installer's usage of
aws-clican cause keyring issues on desktop versions of Linux. Consider disabling your distro's keyring service, or alternatively, a headless distribution such as Ubuntu server edition will resolve the issue.