Skip to main content

Agama network-based installation

The Agama installer ships as a Live ISO image generated by KIWI NG.

It can be booted directly from an USB stick, CD/DVD or from the network using the initrd and the kernel extracted from the ISO as it is documented by KIWI.

As the remote boot process of a live ISO image places the ISO file into a ramdisk by default it is recommended to also extract the compressed root file system (squashfs.img).

Once extracted, these files must be copied to an appropriate location accessible via FTP, TFTP, HTTP, HTTPS...

sudo mount -oro,loop /srv/install/iso/agama-installer.iso /mnt
sudo cp /mnt/boot/x86_64/loader/linux  /srv/tftpboot/boot/images/agama/x86_64/
sudo cp /mnt/boot/x86_64/loader/initrd /srv/tftpboot/boot/images/agama/x86_64/
sudo cp /mnt/LiveOS/squashfs.img /srv/tftpboot/boot/images/agama/x86_64/

How to set up a PXE server is out of scope of this guide but some documentation for SLES can be found at PXE Server.

Important changes compared to YaST installer​

There are some important changes that affect the installation workflow and specially the kernel boot options.

  • Linuxrc is not included and dracut. takes care of booting the installer.
  • NetworkManager is the default network backend.

We tried to provide some compatibility with Linuxrc options but we recommend migrating to dracut specific ones because not all the use cases are supported.

Kernel boot options​

As there is no Linuxrc anymore, the options given as kernel parameters should be replaced by dracut specific ones like the network configuration and the installer sources.

For Agama specific options check the boot options section.

Specify the installer image location​

It already requires network configuration enforcing rd.neednet=1.

  • root=live:http://192.168.0.1/boot/images/agama/x86_64/squashfs.img ip=dhcp

    Sets the SquashFS image or ISO to be fetched by the livenet dracut module.

  • inst.install_url=http://192.168.0.1/install/agama/x86_84

    Sets the repositories to be used by the installer instead of the defaults repositories for the selected product. It is not necessary in case of an online installation with a registered product.

Network configuration​

Network will be configured by dracut only if really required so, there are some kernel boot options like root=live:<URL> that already requires or enforces the network to be configured, but not all the kernel options (e.g., inst.install_url, ip) do so, therefore, to ensure the network is configured by dracut set rd.neednet=1.

warning

If explicit network configuration is provided using the ip= kernel boot option, Agama will disable the NetworkManager DHCP autosetup when starting the installer marking the NetworkManager connections generated by the nm-initrd-generator to be persisted after the installation by default.

The inst.copy_network=0 kernel boot option can be used to disable the copy of NetworkManager connections from /etc/NetworkManager/system-connections to the target system.

DHCP configuration​

  • ip=dhcp

    nm-initrd-generator will generate a profile using DHCP allowing multiple devices to apply it at the same time.

  • ip=enp1s0:dhcp

    The generated profile will be assigned to enp1s0 interface.

  • ip=aa-bb-cc-dd-ee-ff:dhcp

    The generated profile will be assigned to the device with the specified mac address

DHCP static configuration​

  • ip=<client-IP>:[<peer>]:<gateway-IP>:<netmask>:<client_hostname>:<interface>:{none|off|dhcp|on|any|dhcp6|auto6|ibft}[:[<dns1>][:<dns2>]]

  • ip=10.144.136.45::10.144.136.254:24:agama1.suse.cz:enc800

    Static configuration using a prefix length as the netmask.

  • ip=192.168.100.228::192.168.100.1:255.255.255.0:agama.test:aa-bb-cc-dd-ee-ff

    The interface can be also a mac address.

Use custom interface naming​

  • ifname=<interface>:<MAC>

    Assign network device name <interface> to the NIC with the MAC <MAC>.

  • ifname=bootnet:AA:BB:CC:DD:EE:FF ip=bootnet:dhcp rd.neednet=1

    warning

    Agama will persist the renaming of the interface after the installation through a systemd network link file (e.g., /etc/systemd/network/10-agama-ifname-bootnet.link).

    The file can be removed using a post-installation script at the Agama configuration.

Booting from iSCSI (iBFT)​

When the firmware boots the system from iSCSI, it describes the connection in the iSCSI Boot Firmware Table (iBFT): the initiator name, the targets and the network configuration of each NIC involved (IP address, gateway, VLAN, MAC address, etc.). Agama shows the initiator and the targets configured by the firmware, but the network interfaces must be configured during boot so that the targets can be reached.

NetworkManager does not read iBFT once the system is running. Only nm-initrd-generator, run by dracut in the initramfs, reads it, and only when it is asked to through a boot option.

Boot options​

  • rd.iscsi.ibft=1 (or just rd.iscsi.ibft)

    It is the recommended option.

  • ip=ibft

    It configures the same network interfaces, but Agama considers it an explicit network configuration, like any other ip= option (see Network configuration): it turns off the automatic DHCP configuration of the rest of the network interfaces and it copies the generated profiles to the installed system.

What gets configured​

nm-initrd-generator creates one connection profile for each NIC in the table, named ibft0, ibft1, etc. after the index of its record, including the VLAN if the record has one, and NetworkManager activates them.

Every NIC in the table gets its profile, not only the one used for booting, so no additional network option is needed when the iSCSI targets are reachable through more than one NIC.

To check it, /sys/firmware/ibft/ must exist (otherwise the firmware does not provide the table), and nmcli connection show lists the ibft* profiles. Agama shows them as any other connection in the network settings.

In the installed system​

The generated profiles do not need to be copied to the installed system. When its root file system is on an iSCSI target described in iBFT, dracut adds rd.iscsi.ibft=1 to the configuration of its initramfs, so nm-initrd-generator generates them again from the firmware on every boot. It does not add it for the iSCSI offload cards using the bnx2i driver, which use a different MAC address for the iSCSI traffic.

PXE server documentation​

For more information about setting up a PXE Boot Server on SUSE Linux Enterprise Server 16.0 refer to this guide.