File README.onie of Package openSUSE-MicroOS
Installing MicroOS using ONIE
-----------------------------
ONIE is an "install environment", a minimal preinstalled OS with the single
purpose to aid in installing an operating system over various paths. This
document describes how to install MicroOS on x86_64 systems with ONIE.
Server setup
------------
There are several options for configuring a server so that it can be discovered
by ONIE. See the ONIE documentation at
https://opencomputeproject.github.io/onie/design-spec/discovery.html
for details. The discovery process has to find the "onie-installer" script,
which is next to this README.
After the installation script was discovered by ONIE, the script performs some
preparation and then downloads the data from the installation source. Currently
this is hardcoded to be a HTTP server at "192.168.43.1". To use a different
location, it has to be changed in the script manually. The scripts expects to
reach the data generated by the "qcow2toonie.sh" script there.
For example, using ISC-DHCP as server and a local HTTP server on the same host
at 192.168.43.1, this could be used in the dhcpd configuration:
```
subnet 192.168.43.0 netmask 255.255.255.0 {
range 192.168.43.10 192.168.43.20;
default-lease-time 14400;
max-lease-time 172800;
option default-url = "http://192.168.43.1/onie-installer";
}
```
The qcow2 file built from this image has to be transferred to the server and
the qcow2toonie.sh script run with the file and the server's target directory
as parameters, e.g.
bash qcow2toonie.sh openSUSE-MicroOS.x86_64-onie-Current.qcow2 /srv/www/htdocs/
The example URL in the DHCP configuration points to the same location, so the
onie-installer script has to be copied there as well.
Performing the install
----------------------
After the server is set up and connected to the target, just boot ONIE into the
"Install OS" mode. After successful discovery and installation, it reboots into
the installed system. The default image has salt-minion enabled by default, but
also has the root password set to "linux" to allow immediate login over the
serial console. FOR SECURITY REASONS, MAKE SURE to change the password (or
disable login by password) and also stop and disable salt-minion if unused!
Design
------
ONIE basically downloads an executable file and runs it, so there are multiple
possible ways to install MicroOS.
MicroOS needs btrfs, that means:
* Deployment via tarball is not directly possible (would have to redo subvol
setup and so on)
* ONIE's btrfs support is too old, let's avoid writing (would probably break
qroups at least)
Ideally, we could use kiwi's code to dump an OEM image onto the disk but that:
* Needs kexec, which is present, but might not work
* Doesn't care about ONIE and probably deletes it
Next idea, Yomi!
* More complex, much slower, more overhead
* Also needs kexec (or install Yomi first, then boot into it?)
This follows a hybrid approach:
* The root partition is created and then the data dd'd onto it
* (EFI) Using a chroot and a workaround to allow it with read-only /,
shim-install is called to write into the ESP and register boot entries
* (non-EFI) The existing grub core image is dd'd into the grub core partition.
It includes a mount by UUID, so boots the right partition automatically.
* The image itself defaults to non-EFI, i.e. no /boot/efi entry in fstab and
LOADER_TYPE set to grub2. On the first boot, the image adjusts itself to
whether it's EFI or not.
How it works
------------
Compared to the kvm-and-xen images:
* Also for bare-metal, so includes kernel-firmware-all
* There is a single btrfs partition, /var is a subvolume
* Defaults to serial console for grub and kernel
* /boot/efi entry removed from /etc/fstab, onie-adjust-boottype.service adds it
back on the first boot if applicable
* /etc/grub.d/85_onie adds an entry to get back to ONIE
The qcow2toonie.sh script converts the built qcow2 image into a file containing
the grub core partition and a compressed raw image of the root partition.
