If you would like to roll out initial settings with your IGEL OS Creator (OSC) installation, you can do it through:

  • modifying the OSC ISO file
    Use this method to store initial settings and licenses on the ISO.
  • modifying the Master Image
    Use this method if you already have a master image at hand and you want to add initial settings, licenses, ca-certs to it, so that they get rolled out after the first boot.

Modification of an OSC ISO for Rolling out Settings

Overview 

Overview of the process for initial settings and license rollout:

  1. Extract your ISO.

  2. Create initial-settings directory in the extracted ISO.

  3. Copy or create a setup.ini with the settings you want to the initial-settings directory. 

    Do not add passwords.

  4. Copy or create a ca-certs directory with certificates to the initial-settings directory you want to add to the installed system.

  5. Copy or create a wfs-template directory in the initial-settings directory with files and directories you want to add to the /wfs directory of the installed system.

  6. If you have license files, simply copy them to the initial-settings. All *.lic files in the / directory of the first partition will get copied to the /license/dsa/licenses directory. 

    The filesize of the licenses is limited to 1MiB.

  7. Repack the ISO again.

  • You can gzip, bzip2 or xz the setup.ini file; it will get extracted if no setup.ini is present (if setup.ini is also present the packed file will be ignored).

  • You can gzip the license file also.

  • The setup.ini and the *.lic files which are not packed will go through dos2unix to ensure a UNIX file format.

Detailed Description with Examples

You will need xorriso to do the below which is not part of the IGEL OS so you will need to use a other Linux system to do this.


  1. Extract ISO content.

    This can be done with xorriso -osirrox on -indev <iso file> -extract <target dir> <target name>. In the example we use: /isofiles/osc11.05.100.iso for <iso file> , and . as <target dir> , and osc-data as <target name> which leads to following command line:

    xorriso -osirrox on -indev /isofiles/osc11.05.100.iso -extract . osc-data
xorriso 1.4.8 : RockRidge filesystem manipulator, libburnia project.

Copying of file objects from ISO image to disk filesystem is: Enabled
xorriso : NOTE : Loading ISO image tree from LBA 0
xorriso : UPDATE : 414 nodes read in 1 seconds
xorriso : NOTE : Detected El-Torito boot information which currently is set to be discarded
Drive current: -indev '/isofiles/osc11.05.100.iso'
Media current: stdio file, overwriteable
Media status : is written , is appendable
Boot record  : El Torito , MBR isohybrid cyl-align-off GPT
Media summary: 1 session, 1458176 data blocks, 2848m data, 45.4g free
Volume id    : 'IGEL_OSC_TO'
xorriso : UPDATE : 356 files restored ( 777.9m) in 1 seconds , 588.9xD
xorriso : UPDATE : 377 files restored (1641.6m) in 2 seconds , 653.9xD
xorriso : UPDATE : 391 files restored (2578.4m) in 3 seconds , 709.2xD
xorriso : UPDATE : 414 files restored (2846.4m) in 3 seconds = 653.2xD
Extracted from ISO image: file ''='/tmp/osc-data'
    CODE

    The complete ISO will get extracted to the osc-data directory.

  2. Create initial-settings directory in the extracted ISO data.

    Above we extracted the data to /tmp/osc-data , so we need to create the directory in this directory:

    mkdir /tmp/osc-data/initial-settings
    CODE

  3. Copy your files and directories to the initial-settings directory.

    In our example we use /tmp/osc-data/initial-settings as target directory. If, for example, you have the following you want to add to the ISO:

    • a setup.ini,

    • a ca-certs file SSL+VPN+CA.crt,

    • license files 782DAFC836185589DD6212375DC33C22.lic D5F47E9338C3A46A0D0F785B9F6A6926.lic

    • a Wallpaper wallpaper.jpg,

      you can do the following:

      mkdir -p /tmp/osc-data/initial-settings/ca-certs
mkdir -p /tmp/osc-data/initial-settings/wfs-templates
cp setup.ini /tmp/osc-data/initial-settings/
cp 782DAFC836185589DD6212375DC33C22.lic D5F47E9338C3A46A0D0F785B9F6A6926.lic /tmp/osc-data/initial-settings/
cp SSL+VPN+CA.crt /tmp/osc-data/initial-settings/ca-certs/
cp wallpaper.jpg /tmp/osc-data/initial-settings/wfs-templates
      CODE

      The licenses files will get copied to the license partition. The setup.ini and wallpaper.jpg will be copied to /wfs/ and the contents of the ca-certs directory will be copied to /wfs/ca-certs.

  4. Repack the ISO again.

    1. First, check if the original ISO was a legacy version or not.

      For this, execute xorriso -indev <iso file> -find / -name boot 2>&1 and search for the line with Boot record. If there is a GPT in this line, the ISO is not a legacy ISO.

      Example:

      xorriso -indev /isofiles/osc11.05.100.iso -find / -name boot 2>&1 | grep -E "^Boot record.*GPT"
Boot record  : El Torito , MBR isohybrid cyl-align-off GPT
      CODE

    2. Repack the non-legacy ISO with xorriso and with these additional parameters:

      xorriso -as mkisofs -rock -omit-version-number -disable-deep-relocation -volid IGEL_OSC_TO -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat -no-emul-boot -boot-load-size 4 -boot-info-table -eltorito-alt-boot -e igel_efi.img -no-emul-boot -isohybrid-mbr "<extracted iso dir>/boot/isolinux/isohdpfx.bin" -isohybrid-gpt-basdat -o "<target iso file>" "<extracted iso dir>".

      Example:

      xorriso -as mkisofs -rock -omit-version-number -disable-deep-relocation -volid IGEL_OSC_TO -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat -no-emul-boot -boot-load-size 4 -boot-info-table -eltorito-alt-boot -e igel_efi.img -no-emul-boot -isohybrid-mbr "/tmp/osc-data/boot/isolinux/isohdpfx.bin" -isohybrid-gpt-basdat -o "osc11.05.100.iso" "/tmp/osc-data"
xorriso 1.4.8 : RockRidge filesystem manipulator, libburnia project.

Drive current: -outdev 'stdio:osc11.05.100.iso'
Media current: stdio file, overwriteable
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 43.7g free
Added to ISO image: directory '/'='/tmp/osc-data'
xorriso : UPDATE : 414 files added in 1 seconds
xorriso : UPDATE : 414 files added in 1 seconds
xorriso : NOTE : Copying to System Area: 432 bytes from file '/tmp/osc-data/boot/isolinux/isohdpfx.bin'
xorriso : WARNING : Boot image load size exceeds 65535 blocks of 512 bytes. Will record 0 in El Torito to extend ESP to end-of-medium.
libisofs: NOTE : Automatically adjusted MBR geometry to 1024/178/32
libisofs: NOTE : Aligned image size to cylinder size by 432 blocks
xorriso : UPDATE :  2.19% done
xorriso : UPDATE :  29.31% done
xorriso : UPDATE :  60.27% done, estimate finish Wed Feb 24 12:50:05 2021
xorriso : UPDATE :  91.42% done
ISO image produced: 1458176 sectors
Written to medium : 1458176 sectors at LBA 0
Writing to 'stdio:osc11.05.100.iso' completed successfully.
      CODE

    3. Repack the legacy ISO with xorriso and with these additional parameters:

      xorriso -as mkisofs -rock -omit-version-number -disable-deep-relocation -volid IGEL_OSC_TO -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat -no-emul-boot -boot-load-size 4 -boot-info-table -no-emul-boot -isohybrid-mbr "<extracted iso dir>/boot/isolinux/isohdpfx.bin" -isohybrid-gpt-basdat -o "<target iso file>" "<extracted iso dir>".

      Example:

      xorriso -as mkisofs -rock -omit-version-number -disable-deep-relocation -volid IGEL_OSC_TO -b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat -no-emul-boot -boot-load-size 4 -boot-info-table -no-emul-boot -isohybrid-mbr "/tmp/osc-data/boot/isolinux/isohdpfx.bin" -isohybrid-gpt-basdat -o "osc11.05.100.iso" "/tmp/osc-data"
xorriso 1.4.8 : RockRidge filesystem manipulator, libburnia project.

Drive current: -outdev 'stdio:osc11.05.100.iso'
Media current: stdio file, overwriteable
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 43.7g free
Added to ISO image: directory '/'='/tmp/osc-data'
xorriso : UPDATE : 414 files added in 1 seconds
xorriso : UPDATE : 414 files added in 1 seconds
xorriso : NOTE : Copying to System Area: 432 bytes from file '/tmp/osc-data/boot/isolinux/isohdpfx.bin'
libisofs: NOTE : Automatically adjusted MBR geometry to 1024/178/32
libisofs: NOTE : Aligned image size to cylinder size by 432 blocks
xorriso : UPDATE :  2.19% done
xorriso : UPDATE :  29.31% done
xorriso : UPDATE :  60.27% done, estimate finish Wed Feb 24 12:50:05 2021
xorriso : UPDATE :  91.42% done
ISO image produced: 1458176 sectors
Written to medium : 1458176 sectors at LBA 0
Writing to 'stdio:osc11.05.100.iso' completed successfully.
      CODE

Modification of a Master Image for Rolling out Settings after First Boot

Overview

  1. Check if the first partition is a VFAT marked partition and make sure that there are 4 partitions present.

    Only the Master Images with 4 partitions support the rollout of initial settings.

  2. Format the first partition with VFAT.

  3. Mount the first partition.

  4. Copy or create a setup.ini with the settings you want to the mounted partition.

    Do not add passwords.

  5. Copy or create a ca-certs directory with certificates to the mounted partition you want to add to the master image.

  6. Copy or create a wfs-template directory on the mounted partition with files and directories you want to add to the /wfs directory of the installed system.

    Only possible with OS version 11.05.100 and newer.

  7. If you have license files, copy them to the first partition. All *.lic files in the / directory of the first partition will get copied to the /license/dsa/licenses directory. 

    The filesize of the licenses is limited to 1MiB.
  8. Umount the first partition.


  • You can gzip, bzip2 or xz the setup.ini file; it will get extracted if no setup.ini is present (if setup.ini is also present the packed file will be ignored).

  • You can gzip the license file also

  • The setup.ini and the *.lic files which are not packed will go through dos2unix to ensure a UNIX file format

Detailed Description with Examples

The easiest way is to write the master image to a device and do the changes on the device directly. Keep in mind if you boot once from the device this will not be a master image anymore.
Be very careful with choosing the correct <device> in the example steps below as this can harm your running system.


  1. Check if the device contains 4 partitions and the first is usable for initial settings rollout.

    For example, use fdisk -l <device> to check the partitions from an IGEL system. If <device> is replaced with /dev/sda then the output should look like the below, which means, there are 4 partitions present and the first one is a FAT32 so this Master Image is capable of rolling out initial settings.

    fdisk -l /dev/sda
Disk /dev/sda: 4 GiB, 4294967296 bytes, 8388608 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x144ad2c2

Device     Boot  Start     End Sectors Size Id Type
/dev/sda1         2048   22527   20480  10M  b W95 FAT32
/dev/sda2  *     22528   83967   61440  30M ef EFI (FAT-12/16/32)
/dev/sda3        83968  145407   61440  30M ef EFI (FAT-12/16/32)
/dev/sda4       145408 8382463 8237056   4G 83 Linux
    CODE

  2. Try to mount the first partition.

    For example, with mount <device>1 <target dir> from an IGEL system. If <device> is replaced with /dev/sda and <target dir> with /mnt (you must create the empty directory with mkdir -p /mnt first) then there should be no error message.

    If there is an error message like below, then the first partition is not formatted or it is not the correct one.

    mount /dev/sda1 /mnt
mount: /mnt: wrong fs type, bad option, bad superblock on /dev/sda1, missing codepage or helper program, or other error.
    CODE

    In case of an error message:

    1. Check the fdisk output again.

    2. If the mount failed but fdisk output shows 4 partitions and the first is marked as FAT32, format the first partition as VFAT with mkfs.vfat <device>1 from an IGEL system. If <device> is replaced with /dev/sda this should look like:

      mkfs.vfat /dev/sda1
mkfs.fat 4.1 (2017-01-24)
      CODE

    3. If there are no error messages the partition should now be mountable, so call mount <device>1 <target dir> again. If <device> is replaced with /dev/sda and <target dir> with /mnt you should get no error or warning message at all:

      mount /dev/sda1 /mnt
      CODE


  3. Copy your files and directories to the <target> directory.

    In this case <target> will be replaced with /mnt.
    If, for example, you have the following you want to add to the master image:

    • a setup.ini,

    • a ca-certs file SSL+VPN+CA.crt,

    • license files 782DAFC836185589DD6212375DC33C22.lic D5F47E9338C3A46A0D0F785B9F6A6926.lic,

    • and a wallpaper wallpaper.jpg,

      you can do the following:

      mkdir -p /mnt/ca-certs
mkdir -p /mnt/wfs-templates
cp setup.ini /mnt/
cp 782DAFC836185589DD6212375DC33C22.lic D5F47E9338C3A46A0D0F785B9F6A6926.lic /mnt/
cp SSL+VPN+CA.crt /mnt/ca-certs/
cp wallpaper.jpg /mnt/wfs-templates
      CODE


      As a result, the licenses files will get copied to the license partition. The setup.ini and wallpaper.jpg will be copied to /wfs/ and the contents of the ca-certs directory will be copied to /wfs/ca-certs.


  4. Umount everything again with umount <target dir>.

    Example:

    umount /mnt
    CODE


    There should be no error message after executing the command.