Skip to content

QuickStartGuide

Jump to bottom Edit New page
Olivier LAHAYE edited this page Nov 15, 2019 · 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)
    • Make sure /etc/systemimager/systemimager.json is owned by http (apache).
    • try to access http://<your server or localhost>/systemimager/edit_config.php Edit preferences and save (defaults should be ok).

  • /etc/systemimager/systemimager.conf (soon deprecated by above WebGUI)

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

  • DHCP

    • /usr/sbin/si_mkdhcpserver
      • 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

  • 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 issue the following command: si_prepareclient --server &lt;hostname or ip of your systemimager server&gt; Then, on server do: si_getimage --golden-client &lt;you golden client&gt; --image &lt;image-name&gt; --post-install=directboot => Note than 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 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. Use the web GUI:

    => The clients list is accessible with a web browser pointing http://<your server or localhost>/systemimager/edit_config.php

    => Clicking an a client hostname will show the live console:

    Runs this command from server to see imaging progress and see remotely what the console prints on the client being imaged (requires an X11 display).

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 /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 to old DHCP options method that is 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.

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 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