This document represents the current and pending state of our move to openSUSE as our linux distro base for Rockstor and is not an endorsement of it’s use or support status but is simply intended to share the progress and development made to date. It is intended as a developers document so any changes made should be in accordance with keeping this text up to date with the current code state, including in this case pending pr’s.
If you wish to comment on our openSUSE move in general, as opposed to the specifics of what is actually in play currently: please consider contributing to the following forum thread: Rebasing on to openSUSE? which also details some prior committed changes relevant to this move. Comments and edits here are welcomed in the context of code or development contributions only as it is intended as a current state of play doc.
In the interests of aiding those willing to assist with this move the following are the current steps required for building Rockstor on an openSUSE base. Currently this means both openSUSE Leap 15.1 and 15.2 (Tumbleweed has now dropped some of our python2 library requirements). It is hoped that the Rockstor code, in time, can adapt to a transition of it’s base from one to the other and back again as this should provide for much greater flexibility. The current in code (master branch) basis for ‘sensing’ our base linux distro / version is to use the ‘python-distro’ (now missing in Tumbleweed) package: introduces as a dependency in the following pr pertaining to git tag 3.9.2-45:
https://github.com/rockstor/rockstor-core/pull/1990
which basically adds the python distro library / package.
In the above pr this was used to inform the required docker start procedure which differs between all 3 of our current distros of interest at that time: CentOS (legacy but current stable channel release rpms) openSUSE Leap 15.1 and Tumbleweed (NG or Next Generation Rockstor base).
openSUSE install requirements
Our current target distro is Leap 15.2, the following is expected of a development environment for contributing to Rockstor when based on openSUSE which is at roughly beta stage. Note that all current Rockstor code contributors are testing all pr’s on Leap 15.2 only as we near our target feature parity with our now legacy CentOS stable channel offering.
CentOS development considerations have now been deprecated.
Installer options
- Use at least a 20 GB system disk, this auto enabled boot to snapshot functionality.
- Server (non transactional) for the time being at least.
- Default partitioning (which is btrfs root as per Rockstor’s expectation)
- Skip user creation (then only root password to enter and leaves all additional users as Rockstor managed)
- “Firewall will be disabled” (see Note 1 below)
- “SSH service will be enabled” (default in Leap 15.1 on server install, and in Tumbleweeds)
-
“SSH port will be open” (Leap 15.1 default)N.B. This option disappears when Firewall is disabled - “Using NetworkManager”’ via “Switch to NetworkManager” link, if presented (Thanks to @Flox for spotting this one).
Note 1: re ssh and firewalld defaults change in Leap 15.1, see:
Note2: re firewalld enablement status see: subsequent changes in:
[openSUSE] remove firewalld associated code #2024
enable firewall by default in server install profiles #166
Open suse 15 1 #167
Apply all upstream updates
If Leap
zypper update --no-recommends
If Tumbleweed (if the missing python2 libraries re-appear or are contributed)
Or an RC release of Leap or Jump in the future.
zypper dup --no-recommends
Stop and Disable AppArmor
Thanks to forum members and rockstor contributors @Flox @def_monk. As with our legacy CentOS based builds, which required SELinux to be deactivated, our openSUSE compatibility, currently at least, requires that AppArmor be deactivated:
systemctl stop apparmor
systemctl disable apparmor
There is every hope that in the future we properly register all our ‘actions’ with AppArmor to ensure we are doing only what we are intending to do. But for the time being in these earlier releases we initially side step AppArmor compliance until we have the development resources to focus properly on this important element. If you have expertise/interest in AppArmor then do feel free to step up to this task as it would be great to get this effort underway as soon as possible. But for the existing team it is a stretch goal to be addressed post feature parity, or near enough, with our CentOS Stable channel builds.
A reboot is advised at this point to ensure all updated binaries are ‘in play’ and that AppArmor is also fully disabled.
Switch to Network Manager from wicked (if not already selected during install)
Rockstor is heavily invested in Network manager and so we switch to this for network configuration (thanks to @luke for simpler instructions)
zypper install --no-recommends NetworkManager
systemctl disable wicked
systemctl enable NetworkManager
systemctl start NetworkManager
The ‘nmcli’ command should now work to display network settings.
Disable IPv6 at the kernel level
Thanks to @tyukh for highlighting this requirement. As Rockstor’s Web-UI is ipv4 only we need to disable all ipv6 system wide. The most reliable method appears to be a grub config edit to enforce a kernel boot command line option.
The following sed (Stream EDitor) adds “ipv6.disable=1” to the normally empty GRUB_CMDLINE_LINUX option found in /etc/default/grub
sed -i -e 's/GRUB_CMDLINE_LINUX=\"\"/GRUB_CMDLINE_LINUX=\"ipv6\.disable=1\"/g' /etc/default/grub
After this edit, or it’s equivalent, it is necessary to run the following:
grub2-mkconfig -o /boot/grub2/grub.cfg
And to then reboot so that ipv6 is fully disabled.
Please see @tyukh’s GitHub issue for some background on this options requirement:
https://github.com/rockstor/rockstor-core/issues/2139
If in the future Rockstor’s Web-UI network facility is extended to be able to configure ipv6 we can revisit this system wide restriction.
To ‘undo’ IPv6 disable at the kernel level
In later development (around 4.0.7-0 to 4.0.8-0) we are testing re-enabling IPv6.
To ‘undo’ the above sed command, or to re-enable IPv6 on a resulting install from our rockstor-installer prior to the following issues resolution:
https://github.com/rockstor/rockstor-installer/issues/74
execute the following:
sed -i 's/ipv6\.disable=1[ ]*//g' /etc/default/grub
grub2-mkconfig -o /boot/grub2/grub.cfg
and then reboot.
Add ‘shells’ OBS repo
As from source tag 3.9.2-55 (though for about a day before this also) we have a shellinabox dependency. This, along with code changes, fixes a prior feature parity issue where the Web-UI embedded shell was non functional in our ‘Built on openSUSE’ effort. As shellinabox is not provided by the default openSUSE repos (our CentOS build used epel for this) the following repo addition is required: Show shells - openSUSE Build Service
Leap15.1: (now deprecated as a Rockstor 4 target distro)
zypper --non-interactive addrepo --refresh -p105 http://download.opensuse.org/repositories/shells/openSUSE_Leap_15.1/ shells
zypper --non-interactive --gpg-auto-import-keys refresh
Leap15.2:
zypper --non-interactive addrepo --refresh -p105 http://download.opensuse.org/repositories/shells/openSUSE_Leap_15.2/ shells
zypper --non-interactive --gpg-auto-import-keys refresh
Tumbleweed:
zypper --non-interactive addrepo --refresh -p105 http://download.opensuse.org/repositories/shells/openSUSE_Tumbleweed/ shells
zypper --non-interactive --gpg-auto-import-keys refresh
AArch64 experiments (tested as working for Leap 15.2)
zypper --non-interactive addrepo --refresh -p105 https://download.opensuse.org/repositories/shells/openSUSE_Factory_ARM/ shells
zypper --non-interactive --gpg-auto-import-keys refresh
If your intention is to test our Testing Channel rpms then you can return to those instructions:
Packages for Building Rockstor from source
zypper --non-interactive install samba docker nut nginx nfs-kernel-server at gcc python-devel gcc-c++ postgresql10-devel postgresql10-server libblkid-devel dnf-yum dnf-plugins-core python2-distro python3-distro firewalld python2-setuptools python2-requests python2-chardet python-xml cryptsetup
Thanks to @Psykar for the ‘firewalld’ prompt: Leap 15.1 (currently beta) dropped this package on default server installs. See the following consequent issue: [openSUSE] remove firewalld associated code.
Amendment re no firewalld package by default, could pertain to Minimal System Install: see 15.1 (beta) release notes Minimal System Installation
such as may be found in docker images, or JeOS.
Thanks to @Flox for the prompt re specifying postgresql10 versions, which in Tumbleweed pull in the 11 variants and thus give us the required alternatives to ‘fix’ no pg_config: see next section.
Select Postgesql 10 variant (Tumbleweed only currently)
At least for now we are sticking with version 10 as we have already moved from 9.x in our CentOS build. In recent versions of Tumbleweed there is an auto setting in play (the usual default) for version 11 but this fails to establish an ‘in path’ pg_config. To resolve this we select 10 and this then provides our required in path pg_config:
alternatives --config postgresql
There are 2 choices for the alternative postgresql (providing /usr/lib/postgresql).
Selection Path Priority Status
------------------------------------------------------------
* 0 /usr/lib/postgresql11 110 auto mode
1 /usr/lib/postgresql10 100 manual mode
2 /usr/lib/postgresql11 110 manual mode
Press <enter> to keep the current choice[*], or type selection number: 1
update-alternatives: using /usr/lib/postgresql10 to provide /usr/lib/postgresql (postgresql) in manual mode
and as we selected 1 → manual for 10, we should now have:
alternatives --config postgresql
There are 2 choices for the alternative postgresql (providing /usr/lib/postgresql).
Selection Path Priority Status
------------------------------------------------------------
0 /usr/lib/postgresql11 110 auto mode
* 1 /usr/lib/postgresql10 100 manual mode
2 /usr/lib/postgresql11 110 manual mode
Press <enter> to keep the current choice[*], or type selection number:
Thanks to @jcdick1 for helping to highlight this recent Tumbleweed issue re postgresql and no in path pg_config: see: Build instructions - #6 by jcdick1
Building from source
Build as usual, but not in /opt/rockstor as this is reserved for rpm installs which can, as long as this directory is not used, supplant an existing source install. Note however that this source-to-rpm move is necessarily treated as a new install and all prior configuration will be wiped. Any available rpm version is always considered an ‘upgrade’ and offered as such to any source install. This provides a welcome convenience for single issue contributors and further aids in development by allowing source installs to transition to rpm based ones via the usual Web-UI rockstor update mechanism.
See our regular Developers subsection in our Contributing to Rockstor - Overview official docs.
General Advise
In many cases is it advisable to peruse any pending pull requests/issues as they may pertain to ongoing work re Rockstor development, especially with regard to building from source or openSUSE related issues / development and remember that reviews are always welcome and will assist in this openSUSE move as all code is reviewed prior to merge and all rockstor-core code is merged by project lead @phillxnet .
OpenSUSE related issues of note:
https://github.com/rockstor/rockstor-core/issues/2032
Current Known issues
Each of the issues listed here should, in time, link to their own GitHub issues. Please keep each issue as specific as possible and where it pertains to an openSUSE base only then it is proposed that we name each such issue beginning with an NG (Next Generation) and further clarify this fact in the issues text. I will soon create an example issue and update this doc accordingly.
Please view the following list as a TODO: for all prospective code contributors. Normal collaboration methodology stands: i.e. if the issue is not created then create it if you have sufficient knowledge to reproduce the issue and have done so on the target platforms; Leap 15.1 and Tumbleweed. Also note that it is frustrating and disheartening to duplicate each others efforts so if you end up working on an issue please ensure that you state this in the relevant GitHub issue first. That way others looking to such issues will know that they are a work in progress.
N.B. @Flox has current un-submitted/uncommitted code relating to Rock-on / docker improvements.
Our current focus is to achieve feature parity, or near enough, between our to-be-legacy CentOS and our in-testing “Build on openSUSE” variants.
TODO (non exhaustive):
- SAMBA authentication fails: See above more recent section on disabling AppArmor (resolution provided by @Flox and @def_monk)
When last tested on Tumbleweed there was an authentication issue with SMB shares when setup by Rockstor.
Missing GitHub issue link.
- YAST compatibility:
In the process of investigating the SAMBA issue above it was found that our config file ‘tag’ is not in compliance with that of yast’s tags and so once yast has been used to configure samba the smb.conf file is incompatible with Rockstor as yast ‘comments’ our ‘comment line’ tags. This should be a simple matter of changing Rockstor’s written tag to comply with what yast will accept as a commnet, but we have to maintain what we look for tag wise so that we pick up on prior Rockstor configurations. Hopefully we can propagate this yast compatibility across all services that Rockstor configures but each must be considered and GitHub issued separately so as not to grow this issue to something unmanageable and cumbersome.See issue #2035 for another example of a potential clash between YAST/sysconfig and Rockstor’s direct editing of config files.
(Missing individual GitHut issue links in this section)
- smartctl.conf file location
It seems we need to adapt to an issue re the location or lack of ‘/etc/smartmontools/smartd.conf’. Reproducer: System → Services - S.M.A.R.T (spanner icon) → Submit button
GitHub issue link.
Again all of the above need GitHub issues first, detailing their exact reproducer and any other pertinent details, ie log entries at the time of the issue occurring, exact distro base / version etc.
What is working
Quite a lot actually
- Replication has been successfully tested in both directions between our current legacy CentOS install (stable channel) and I think (from memory here as it was a while ago) both openSUSE variants. And as our full cycle replication system exercises almost all subvol mechanisms within Rockstor, plus a few special ones of it’s own, this bodes well for basic Pool (btrfs volume), share, snapshot, and clone (btrfs subvols) functions.
- Rock-ons / docker functionality (see above 3.9.2-45 git tag reference re distro based docker auto config). Th Rock-ons functionality was later broken by upstream docker changes re config priorities/sources but @Flox has now submitted a number of merged pr and so we have returned to a functional docker/Rock-ons situation.
Plans
As we are now approaching feature parity, but not there just yet, our current code is now being released in an openSUSE only testing channel. And as of 3.9.2-51 it is expected that these testing channel updates should be able to self update via the Rockstor Web-UI. This update capability includes non rockstor package updates but does not extend to auto-updates as of yet. These rpms are now available for both Leap15.1 and Tumbleweed. The initial distro aware code for this was merged in the following pr:
https://github.com/rockstor/rockstor-core/pull/1992
And once we are sure we have a working upgrade cycle, including db migrations etc (which shouldn’t be affected by this move anyway) we can move to establishing our new openSUSE based installer, coming soon as of the end of Dec 2019.
This doc’s initial author (@phillxnet) favours providing an image based installer such as can be created by openSUSE’s Next gen KIWI:
see:
https://opensource.suse.com/kiwi/building.html#supported-distributions
and:
https://opensource.suse.com/kiwi/building/build_oem_disk.html
quoting from this we have:
“CD/DVD Deployment
Boot the OEM installation image and let KIWI’s OEM installer deploy the OEM disk image from CD/DVD or USB stick onto the target disk
“
This has only had cursory research / investigation to date and represents the end goal of our transition. First we must transition all our current CentOS function to the openSUSE variants.
We now have a closed beta release of a working image based installer but have yet to contact the openSUSE board to double check that we have conformed to their ‘marks’ guidelines prior to our distributing it. We would also like for this new installer to carry our feature parity variant of our installer, which as as yet not where we are at. Upon achieving feature parity with our current CentOS based offering our focus will move to finalising the arrangements / tweaks such that we are clear to start releasing our new ISO installer. Currently our closed tests for this next generation Rockstor 4 installer are using the current testing channel rpms for openSUSE Leap 15.2 with all of the above customisation in place.
Testing
Note that @phillxnet would also like to see 100% functional test coverage using openSUSE’s openQA. As this is a tall order any assistance with this would also be appreciated. This tool is used extensively in openSUSE and consequently SUSE (SLES) releases and is slowly being adopted peace meal by many of the other major linux distros. In the mean time we have to perform manual functional testing and use the existing unit tests for osi and btrfs and the now neglected API tests.
osi unit tests
Can be run in a dev environment via:
cd <root dir of rockstor ie /opt/rockstor-dev>
./bin/test --settings=test-settings -v 3 -p test_osi*
btrfs unit tests
Here we are referencing Rockstor’s own btrfs interaction unit tests, not btrfs’s own unit tests.
Can be run in a dev environment via:
cd <root dir of rockstor ie /opt/rockstor-dev>
./bin/test --settings=test-settings -v 3 -p test_btrfs*
API based tests
We also have extensive but now rather neglected API tests. These API based tests last received attention in the following pr:
https://github.com/rockstor/rockstor-core/pull/2153
As per the above pull request the API tests, along with all the above osi/btrfs tests, can be run via:
cd <root dir of rockstor ie /opt/rockstor-dev>
./bin/test -v 2 -p test_*
With the current per distro summary as follows:
CentOS based (git tag 3.9.2-57)
Ran 203 tests in 31.826s
OK
Leap15.1 (git tag 4.0.1-0)
Ran 205 tests in 33.700s
FAILED (failures=10, errors=5)
Leap15.2 (git tag 4.0.1-0)
Ran 205 tests in 33.464s
FAILED (failures=10, errors=5)
Leap15.2 AArch64 (git tag 4.0.1-0)
Ran 205 tests in 67.288s
FAILED (failures=6, errors=4)
Tumbleweed (now missing some Python 2 libs)
Ran 203 tests in 30.041s
FAILED (failures=7, errors=1)
Please note that these tests are in need or attention and as a result should not be run on installs that have access to ‘real’ data. If you have an interest or experience in this area you are more than welcome to chip in with a view to producing improvement pull requests. There are still many API tests remarked out due to the tested code having changed significantly. Shame though that it is, it is where we find ourselves and unit test writing / maintenance is not everybody’s ‘cup of tea’, and is in itself a skill. If this interests you then it can be a good way to learn a piece of codes functions/capabilities, in abstraction, prior to extending/modifying them and, if done right, provides a safety net to ensure proposed changes introduce the minimum breakage.
All our osi and btrfs unit tests are current and all currently pass: but we could do with better coverage.
Thanks for any help you can provide with Rockstor’s development. Our core code (rockstor-core) is under a GNU license along with a variety of opensource licences that pertain to our various js libraries (rockstor-jslibs). And our docs (rockstor-doc) are under CC BY-SA. We run a subscription model for the Stable channel rpm releases to help maintain the project financially and accept donations via the Web-UI.