Skip to content

QuickStartGuide

Jump to bottom Edit New page
Olivier LAHAYE edited this page Feb 10, 2023 · 64 revisions

Quick start guide for SystemImager v5 pre

Requirements

Configurations

  • /etc/httpd/conf.d/systemimager.conf

    • Check access (add "Require ip <your_admin_computer_ip>" if needed)
    • make sure httpd is enabled and running (systemctl enable http; systemctl start http)
    • on CentOS-7 / RHEL-7 may have to open up firewall rules to allow port 80 access with "firewall-cmd --permanent --add-port=80/tcp"
    • try to access http://<your server or localhost>/ You should see the main menu below: NOTE: Only the 3 upper icons are effective. The 3 lowers are still stubs as of build 20211029.
    • Click on "SystemImager Configuration" gears icon. Edit preferences and save (green checkmark) (defaults (plain green button) is also ok). NOTE: To navigate upward, just click on the systemimager logo.

  • /etc/systemimager/systemimager.conf (deprecated by above WebGUI except on golden client)

    • Check if all default values suit your needs and filesystem hierarchy is correct.

  • DHCP

    • /usr/sbin/si_mkdhcpserver (soon deprecated by WebGUI)
      • This will produce a /etc/dhcp/dhcpd.conf file. Check it and tweak it for your needs, then restart the dhcpd service on systemd: systemctl restart dhcpd.service on init.d: service dhcpd restart

  • PXE

    • /usr/sbin/si_mkbootserver
    • Check that you have at least a correct entry in the <tftpdir>/pxelinux.cfg/default
      • example:
LABEL sisCO7
   MENU DEFAULT
   MENU LABEL ^7 - Install an OSCAR Node using CentOS7 imager
   KERNEL CO7-kernel
   APPEND initrd=CO7-initrd.img si.skip-local-cfg=yes si.image-server=10.0.2.2 si.monitor-server=10.0.0.2 si.monitor-console=yes si.config=mynode.conf si.post-action=directboot acpi=no noapic vga=795 splash quiet rd.vconsole.keymap=fr

Make sure that /var/lib/tftpboot/{CO7-initrd.img,CO7-kernel} exists if you're using above example. These files are the imager. They can be found as /usr/share/systemimager/boot/x86_64/standard/{initrd.img,kernel}

  • Rsync

    • si_mkrsyncd_conf (you should have /etc/systemimager/rsync_stubs/40<yourimagename> created, /etc/systemimager/rsyncd.conf updated and rsync daemon running the systemimager rsync configuration.)

  • Systemimager parameters: => SystemImager supports multiple ways to specify parameters.

    • DHCP options traditional way, but it only supports few parameters: image-server, log-server-port, ssh-download-url, flamethrower-directory-port-base and tmpfs-staging

    • PXE cmdline just like any dracut based initramfs, systemimager supports cmdline parameters all starting with the "si." prefix. => see SystemImager imager parameters. => man systemimager.cmdline => man dracut.cmdline => man kernel.cmdline

    • configs directory: /var/lib/systemimager/scripts/configs/ it contains files with systemimager variables similar to local.cfg except that it's not local ;-) The file is retrieved once network is established. it is either specified using the si.config= PXE cmdline parameter or if a ${IMAGENAME}.conf exists in this directory, then it is read. example: see template

    • disks-layouts directory: /var/lib/systemimager/scripts/disks-layouts It contains files with disks layout and bootloader infos in xml format. man systemimager.disks-layout for description of format. example (complex one) This is the evolution of autoinstallscript.conf that was stored in <imagedir>/<imagename>/etc/systemimager/autoinstallscript.conf => If you are migrating, just copy the old autoinstallscript.conf anf add a bootloader section. To verify file concistency: si_lint --disks-layout=<you disk layout file.xml>

    • network-configs directory: /var/lib/systemimager/scripts/network-configs It contains files with client network configurations in xml format. This file is optional but highly recommanded. IF it is missing, the imager will configure the PXE booted interface in client. (This config file support bonding, infiniband and aliases, so it's convenient if you want to configure more than one interface) man <systemimager.network-config> for description of format. example: (complex one) To verify file concistency: si_lint --network-config=<you network config file.xml>

    • local.cfg (deprecated but still supported) Same as above except it is read from old hard drive or from a floppy (USB stick will be supported later). example: /usr/share/doc/systemimager-server/local.cfg

Creating the image (2 methods)

  • Using golden client and si_getimage

    On client: install systemimager-client (yum -y install systemimager-client)

    Then (bug workaround), copy /etc/systemimager/systemimager.json from server to golden client.

    Then issue the following command:

    si_prepareclient --server <hostname or ip of your systemimager server>

    => The disks layout will be generated in /etc/systemimager/disks-layout.xml on the golden client (not generated if ran from a container)

    => An rsyncd daemon will be started in background waiting for si_getimage.

    => If golden client has selinux in enforcing mode and a firewall enabled:

    setsebool -P rsync_full_access on ; firewall-cmd --add-service=rsyncd --permanent ; firewall-cmd --reload

    Then, on server do: si_getimage --golden-client <your golden client hostname or ip> --image <image-name> --post-install=directboot

    => Don't forget to stop the rsyncd daemon on the golden client (useless now and more secure) and reenable security if needed.

    => Move the /var/lib/systemimager/images/<image-name>/etc/systemimager/disks-layout.xml to /var/lib/systemimager/scripts/disks-layout/<image-name>.xml (or any suitable name as per naming rules or specific configuration filename)

    NOTE: The disks layout file will lack the bootloder section (not yet generated by si_prepareclient). You'll have to add it manually.

    => After updating and reviewing the /var/lib/systemimager/scripts/disks-layout/<image-name>.xml file, check the syntax using the si_lint command:

    si_lint --disks-layout=&lt;image-name&gt.xml

    => Correct errors before continuing. Note that if your nodes have a dash in hostname, and if lvm is used, the lvmgroup name will be rejected by si_lint. Remove the dash in all lvm groups in the file.

    => Note that, now, the imaging main script is optional and thus not generated by default. If you want one, you can ask for it, but it'll be a mostly empty skeleton as all disk, image download and extraction, and network configuration command are now dynamically done by imager from the xml configuration files. These method is smarter and doesn't require any regeneration upon configuration change. (and is robust as the xml is validated)

  • Using mksiimage from systeminstaller-oscar package (fails on CentOS-8 and all new dnf based distros. Fix in progress) mksiimage --name <name of image> --filename /usr/share/oscar/oscarsamples/pkglists/centos-7-x86_64.pkglist

Deploying the image

  • Prerequisites:
    • dhcp server is up and running
    • rsyncd is up and running
    • an image exists in /var/lib/systemimager/images/<imagename>
    • a disk layout exists in /var/lib/systemimager/scripts/disks-layouts/<name>.xml You can validate it using the following command: si_lint --disks-layout=<name>.xml
    • an optional (though recommanded) network configuration exists in /var/lib/systemimager/scripts/network-configs/<name>.xml You can validate it using the following command: si_lint --network-config=<name>.xml (Note: the file format is not final yet eventhough it's already near final v1)
    • at least si.config= is set in pxe cmdline and a /var/lib/systemimager/scripts/configs/<name>.conf exists and has $IMAGENAME set or si.image-name= is set in pxe cmdline
    • no firewall blocks rsync and other systemimager ports
  • boot the client using PXE (usually, if PXE boot is not default, pressing F12 at bios boot enables PXE boot). In PXE menu, choose the appropriate entry you've defined. It should load systemimager imager initramfs.
    • steps performed by the imager:
      • parse cmdline parameters (defined in PXE kernel cmdline)
      • runs pre-install scripts if any
      • format disk (and mount partitions to /sysroot)
      • runs main-install if one is defined or if a script name matches hostname
      • download image to disk
      • install any mdraid or/and lvm configs in imaged system
      • configures the client network
      • installs the bootloader
      • runs post-install scripts
      • Unmount /sysroot and its dependancies
      • execute post imaging action (either wait, reboot, shutdown of finish booting if modules installed on client match imager kernel).

Monitoring the deployment

  • si_monitor_tk is deprecated. Now, you must use the web GUI:

    => The clients list is accessible with a web browser pointing to: http://<your server or localhost>/systemimager/. Click on "Deployment Console".

    => Clicking an a client hostname will show the live console: (Page is badly designed and can take a few minutes to render; don't kill it. (rewrite of this page in in the TODO list)

Migrating from previous systemimager versions (versions below 4.9)

  • Changes:

    • Main install script is optional as now the imager is smart enough to initialize drives, lay down the image and configure network and bootloader.
    • Disks layout and network configuration are now xml configuration files and they can be updated without the need to regenerate anything.
    • The imager is build with distro vendor binaries and is based on dracut with a dedicated module. Thus, if a hardware is supported by distro vendor, it's sure that systemimager will support it. This means that "UseYourOwnKernel" while still supported is almost useless.
    • The imager has now a GUI (based on plymouth script module) and is enabled with "splash" cmdline argument.
    • The imager now support more way to fine tune its behavior with config file and many cmdline parameters.
    • The imager now uses download protocoles modules. (rught now, only rsync is working fine; more to come like nfs, torrent, docker?, ...)
    • The imager now supports EFI bootloaders and GPT partitions.

  • Migration steps (assuming /var/lib/systemimager and /tftpboot/pxelinux.cfg are the old tree you had) Let's assume you have an image called my_image.

1/ Migrate autoinstallscript.conf:

  • cp /var/lib/systemimager/images/my_image/etc/systemimager/autoinstallscript.conf /var/lib/systemimager/scripts/disks-layouts/my_image.conf

2/ Update scripts directory structure on the image server:

  • Remove or backup main installscript my_image.master from /var/lib/systemimager/scripts/
  • Move /var/lib/systemimager/pre-install/* to /var/lib/systemimager/scripts/pre-install/ and remove old directory
  • Move /var/lib/systemimager/post-install/* to /var/lib/systemimager/scripts/post-install/ and remove old directory
  • Move all links and master scripts in /var/lib/systemimager/scripts/ to a backup place.
  • if you had specific stuffs in your main install script (master script), then run si_mkautoinstallscript --image my_image then edit /var/lib/systemimager/scripts/main-install/my_image.master and add your specific stuffs.

3/ edit /var/lib/systemimager/scripts/disks-layouts/my_image.conf

  • Add a bootloader section (man systemimager.disks-layout)
  • Check that the file is valid: si_lint --disks-layout=my_image.xml Warning: be careful with units. KiB is power of 2 while kB is power of ten. si_lint will be strict with units using /usr/lib/dracut/modules.d/51systemimager/disks-layout.xsd to validate them. (note that KiB has a capital K while kB is a small k letter in power of ten units). See https://en.wikipedia.org/wiki/Binary_prefix for more information.

4/ optionally create a network configuration for this image:

  • create /var/lib/systemimager/scripts/network-configs/my_image.xml (man systemimager.network-config) example net-config.xml is available in /usr/share/doc/systemimager-doc*/examples/

5/ optionally (recommanded) create an imager configuration file:

  • cp /etc/systemimager/autoinstallconf.template /var/lib/systemimager/scripts/configs/my_image.conf
  • Edit this file and set/uncomment relevant variables (bash syntax). This is a good place to set IMAGENAME , DISKS_LAYOUT , NETWORK_CONFIG and maybe other.

6/ edit /tftpboot/pxelinux.cfg/default to fix your PXE entry.

  • I recommend using si.* cmdline parameters over old DHCP options method that are nevertheless still supported.
  • As the kernel cmdline is limited in size (256 Chars on old distros), the best way to configure the imager is to use si.config=my_image.conf and set other parameters (imagename, disks layout, download protocol, ...) in the configuration file created at step 5.
  • A typical entry could look like:
LABEL my_image
   MENU DEFAULT
   MENU LABEL ^I - Install my_image using CentOS7 imager
   KERNEL CO7-kernel
   APPEND initrd=CO7-initrd.img si.skip-local-cfg=yes si.image-server=10.0.2.2 si.config=my_image.conf acpi=no noapic vga=791 splash quiet
  • All other parameters like IMAGENAME, MONITOR_SERVER, MONITOR_PORT, MONITOR_CONSOLE, DISKS_LAYOUT, NETWORK_CONFIG, ... are set up in /var/lib/systemimager/configs/my_image.conf created at step 5

Keep in mind that mandatory stuffs are:

  • si.image-server: If not specified, it'll default to DHCP server, but this is not recommanded.
  • si.image-name: Imager tries to guess it but it's recommended to specify it. Recommended place to specify it in order: imager configuration file then cmdline.
  • si.disks-layout: Imager can guess it. The file it points to is mandatory as the imager can't figure out how to initialize the disk(s) without it. Recommended place to specify it in order: imager configuration file then cmdline.

7/ Review /var/lib/systemimager/scripts/pre-install and /var/lib/systemimager/scripts/post-install

  • Remove all scripts trying to play with kernel modules except if you know what you're doing
  • Remove all scripts playing with udev except if you know what you're doing.
  • Remove all scripts trying to install a bootloader (except if you're installing an unsupported bootloader)
  • Remove all scripts trying to configure network except for unsupported features (bridges, systemd-networkd hardcoded stuffs, DSL cnx, WiFi, ...)
  • Remove all scripts trying to install systemimager-rebooted-script or equivalent
  • Remove all scripts trying to play with LVM or RAID except if you know what you're doing.

8/ Migrate /var/lib/systemimager/clients.xml to new json format (optional)

cd /tmp
wget https://github.com/finley/SystemImager/blob/SystemImager-NG/utilities/convert_client_xml.sh
chmod +x convert_client_xml.sh
./convert_client_xml.sh
rm -f ./convert_client_xml.sh

=> You should obtain some /var/lib/systemimager/clients<Client_MAC_addr>.json files that are compatible with the WebGUI Deployment Console.

Note: if you don't migrate, the files will be created one by one when a client is imaged.

Note: With this new dracut based imager, the philosophy has greatly changed.

  • pre-install is now almost useless and only needed if you need to do preinstall very specific stuffs like whipe a disk with dd, load a kernel module that has no udev rule, ...
  • master script (main-install) is also most useless except if you want to do specifi stuffs before image is laid down to filesystem. For example you may want to mount a NFS home dir or ???. When master script is ran, the disks is already initialized (partitions exists, filesystems are created, lvm are created and raid is created and all of them are mounted to /sysroot if a <fsinfo> entry exists in disks-layout file.
  • post-install scripts are still useful, but far less than in the past. All network configuration, rebooted-script service installation, infiniband configuration and such are already done by imager. Typically, here, you'll find configuration scripts for NIS, LDAP, sssd, drdb, multipathd, firewall, ...

More

  • recreating a new systemimager boot initrd can be done using si_mkbootpackage (can be useful when a new kernel or new firmwares are made available by distro).

SystemImager.org

SystemImager logo

Clone this wiki locally