This repo contains the kiwi-ng configuration used to create Rockstor 4 'Built on openSUSE' installers. Please see the excellent kiwi ng docs for configuration options.
Pull requests most welcome; especially new target system profiles. Please test your modifications on all affected profiles prior to submission and provide details of how you tested the resulting installer.
Profiles are named after their upstream distribution base, i.e. openSUSE Leap version, and then the intended target system; the two elements separated by a ".".
The "target system" element is either generic, i.e. x86_64 or AArch64, or target system specific, i.e. RaspberryPi4 or ARM64EFI. With the latter ARM64EFI spanning both generic (Arm64) and specific (64 bit EFI).
Our current pre-built installers are built using the following profiles (see: Downloads):
- Leap15.5.x86_64
- Leap15.5.RaspberryPi4 (supports RPi400 also)
- Leap15.5.ARM64EFI (N.B. Full Ten64 compatibility awaiting mcbridematt repo update)
If you would like to add a specific target system installer profile, please take a look at the examples referenced in the second link above.
The rockstor.kiwi file itself also contains comments with links to example configs used during its development.
We can make no promises for the 'supported' status of any additional profiles but 'The Rockstor Project' will endeavour to make available the more popular resulting installers.
This installer requires a recent Raspberry OS initiated firmware updates to be booted from a USB device. However, regular microSD card boot should work out-of-the-box without a more modern firmware in the Pi4.
Prior to Tumbleweed dropping some Python 2 libraries this profile was functional. We used this target to inform our developmental direction and as a more leading-edge installer option. We are preserving this profile for when our in-process Python 2 to 3 move is complete. Note however that it is not currently maintained. Please contribute to this profile if you are interested as we would very much like to again be available in the Tumbleweeds.
- ARM64EFI
We are very excited to welcome contributions for the innovative Traverse Ten64 AArch64 platform. Traverse technologies are an important contributor to the rockstor-core code base and have been instrumental in achieving our initial AArch64 aims. The resulting installer is intended to support 64-bit ARM systems that implement the Embedded Boot or Server boot standard. Note that additional drives may be required for your specific hardware, if so consider Installing the Stable Kernel Backport. Also see the following subsection for enabling these same repositories/facilities within the resulting installer itself.
Please see the overview section of the kiwi-ng docs for the canonical System Requirements for building the installer: e.g., 15 GB free space, Python version, etc.
Given our image target OS is exclusively 'Built on openSUSE', a vanilla openSUSE Leap 15.5 install is recommended if not using the kiwi-ng boxbuild method. But if the newer kiwi-ng boxbuild method in "Building on any linux host... " is used, any relatively modern linux system can be used to build the installer.
In order to build the installer you need a local copy of the rockstor-installer GitHub repository. This README.md file is part of that repository. To get this copy you simply need to 'git clone' that repository to your local openSUSE instance:
zypper in git
git clone https://github.com/rockstor/rockstor-installer.git
cd rockstor-installer/The above commands install the 'git' program, and use it to 'clone' (read copy locally) the GitHub repo, before setting your working directory to be inside this local copy. Now you just need the kiwi-ng program this config requires to make the final installer.
Kiwi now has support for using KVM virtual machines to build in an isolated environments, regardless of the linux host.
With the release of version 10.x of kiwi ng the minimum required python version is now 3.9 or higher. On any linux platform with KVM virtualization enabled,
and the corresponding python3 version, you can use an isolated python virtual environment to build the installer without modifying your host OS,
or needing to manually set up an openSUSE virtual machine (see below for this alternative).
This boxbuild approach does have some overheads compared to building on a baremetal installation, but on reasonably powerful hardware it can still take less than twenty minutes.
By default, the kiwi-boxed-plugin will reserve 8GB of memory, and 4 CPU cores.
This can be modified with --box-memory=<vm>G --box-smp-cpus=<number>, e.g., --box-memory 4G --box-smp-cpus=2.
On machines with low RAM, building with as low as 1GB has been tested successfully.
Assigning too much RAM will crash your host, so be sure to set a safe amount smaller than your current available host ram.
Arguments before the -- are passed to boxbuild, and after are passed to the kiwi-ng build itself.
Note on using a host OS within a Virtual Machine:
If using a Linux OS in a Virtual Machine, any shared folders from the host are not properly recognized by the KVM/QEMU that is generated by kiwi-ng's boxbuild approach.
This can lead to chroot errors and terminate the installer generation.
The recommendation in this case is to clone the installer git directly into the VM directory and edit the relevant files (e.g., rockstor.kiwi) before executing the box build; or edit them outside of the VM and transfer them back into the VM's installer directory using a shared folder.
At the end of installer creation the .iso file must then be copied from within the VM directory back onto the VM's host for further use.
Note on pip usage:
Some distros might still have a split between Python 2.x/3.x usage of pip (i.e. pip3 vs. pip), or an existing system that is being used had both installed over time. If that is the case, one wants to ensure that the 3.x version is used, by explicitly declaring pip3 in the below command line.
Otherwise, this can lead to execution errors down the line.
python3 -m venv kiwi-envNote on virtual environment with a specific python3 version:
In case multiple python3 versions are installed (e.g., 3.11 was added to enable the usage of kiwi), the venv should be created using the specific version. Otherwise, the kiwi and box-plugin versions will revert to a lower version than 10x.
Therefore, unless the higher python3 version has been set up to be the default version, the virtual environment should be created (using the example of version 3.11):
python3.11 -m venv kiwi-envIf the system/distro has dropped python 2.x support, or if it is not installed on the system that is used for the build:
./kiwi-env/bin/pip install kiwi kiwi-boxed-pluginOr go with the explicit version 3.x of pip:
./kiwi-env/bin/pip3 install kiwi kiwi-boxed-pluginThe rest remains the same (make sure to consider the memory and CPU defaults mentioned above)
./kiwi-env/bin/kiwi-ng --profile=Leap15.5.x86_64 --type oem \
system boxbuild --box leap -- --description ./ --target-dir ./imagesThis was the preferred method before the above kiwi-ng boxbuild capability existed.
For an openSUSE Leap 15.5 OS from kiwi-ng's doc Installation section we have:
Any x86_64 machine, although keep in mind that building the ISO installer is computationally expensive, so systems with a decent-sized CPU/RAM combination released in the last 5-7 years is recommended.
The openSUSE host version should ideally be at least the version of the target profile. Since Leap 15.5 ships with a python 3.6x it is necessary
to install a higher python version (e.g., 3.11):
sudo zypper in python311then add the required repository and install kiwi and the additional requirements as shown below:
sudo zypper addrepo http://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder/openSUSE_Leap_15.5/ appliance-builder
sudo zypper install python3-kiwi btrfsprogs gfxboot qemu-tools gptfdisk e2fsprogs squashfs xorriso dosfstoolsSee HCL:Raspberry Pi4. Install, for example, an appliance JeOS Leap 15.5 image as the host OS. Enabling USB boot on older Pi4 systems will allow for the use of, for example, an SSD as the system drive which will massively speed up installer building. USB booting on the Pi4 may require a bootloader update via a fully updated Raspberry OS.
Pi4 EEPROM/bootloader version "Jun 15 2020" or later will be required for USB boot regardless of any installer /EFI file changes.
(Leap 15.3 and higher has moved to mixed X86_64/aarch64 repos). Since Leap 15.5 ships with a python 3.6x it is necessary
to install a higher python version (e.g., 3.11):
sudo zypper in python311then add the required repository and install kiwi and the additional requirements as shown below:
sudo zypper addrepo https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder/openSUSE_Leap_15.5/ appliance-builder
sudo zypper install python3-kiwi btrfsprogs qemu-tools gptfdisk e2fsprogs squashfs xorriso dosfstoolsNo edit is required if you wish to use the generic installer filename and default rockstor package version (recommended). To change these defaults edit all lines directly preceded by <!--Change to ... as per the ... details given. Our release infrastructure performs these same edits to set official installer filenames and rockstor package versions.
To enable the use of 'Stable Kernel Backport' and 'filesystems' repositories within our rockstor.kiwi config uncomment the
corresponding repositories already put into the file. For more information about using the most recent kernels
see Installing the Stable Kernel Backport for more information.
If you want to enable LUKS encryption of the Root disk (where Rockstor is installed), uncomment the relevant parameters
that are available in the Leap15.5.x86_64 profile which are preceded by relevant comments. This will enable luks2 encryption
and utilize PBKDF2, as grub does not yet support the more recent argon2id algorithm.
N.B.: The luksformat parameter's preceding hyphens have to be escaped so they can be held as as a comment. When adding more non-commented
parameters, the required double-hyphens can be inserted without escaping them to their Unicode character codes.
Executed, as the root user, in the directory containing this repository's rockstor.kiwi file.
kiwi-ng --profile=Leap15.5.x86_64 --type oem system build --description ./ --target-dir /home/kiwi-images/Executed, as the root user, in the directory containing this repository's rockstor.kiwi file.
N.B. RPi400 built-in keyboard is known not to work with this profile.
kiwi-ng --profile=Leap15.5.RaspberryPi4 --type oem system build --description ./ --target-dir /home/kiwi-images/With the above suggested kiwi-ng commands the resulting installers will be found in /home/kiwi-images/ on the kiwi-ng host systems.
- For the x86_64 profiles the resulting installer is an ISO image intended for image transfer to an installer only device. Use the file ending in ".iso".
- For the RaspberryPi4 profile the resulting installer is an uncompressed raw disk image intended for image transfer to the target system disk directly. Use the file ending in ".raw".
The resulting installs will grow on first boot to the size of their host devices. All partitioning is fully automatic.
Please see Rockstor’s “Built on openSUSE” installer HowTo for a user guide.
Our friendly forum is a good place to ask question regarding this HowTo. If you enable some of the above described enhancements (like backported kernel, LUKS, or add other options yourself) please point those out when reporting any problems. Please be patient however, as our support is predominantly community based and the above procedure is not that well known by our community members. If you find an issue with this procedure and its associated kiwi-ng config, please consider creating and issue and submitting a pull request with any fixes or improvements you consequently discover or invent.
'The Rockstor Project' is a community endeavour and depends on update channel subscriptions and contributions for its continued open source development.