3. Quick Start¶

This is the document that describes the installation, configuration, and basic usages of Feilong.

3.1. Pre-requirements¶

1. Feilong depends on the under-layer z/VM SMAPI support to manage the z/VM objects. For the Feilong to work normally, the managed z/VM system should be updated to the latest level with APARs listed in the z/VM service Information installed.

Note

please make sure you applied http://www-01.ibm.com/support/docview.wss?uid=isg1VM66120 if z/VM 6.4 is used.

2. Feilong has to be installed inside a Linux running on z/VM. Currently supported distros include the most current supported versions:

SUSE Linux Enterprise Server 15 SP6

Red Hat Enterprise Linux 9.4

Ubuntu 24.04 LTS

From now on, BYOL (Bring Your Own Linux) will be used to represent the Linux on which the Feilong will be run.

For the Feilong to run, the BYOL must have enough free disk space (>100M). And besides that, the following updates need to be made to the BYOL.

3.1.1. Preparation on BYOL¶

Authorize BYOL user for z/VM SMAPI call.

VSMWORK1 AUTHLIST needs to be updated in order to make the BYOL machine be able to issue SMAPI call. Refer to z/VM Systems Management Application Programming for how to make it.

Note

It is recommend to consider increase the SMAPI long call server and DIRMAINT DATAMOVE machine if heavy concurrent workload is going to be run through Feilong. See z/VM Systems Management Application Programming for how to make it.

Update BYOL definition for spawning guests.

Assume BYOL has its definition on z/VM, it needs to have following statement in its User Directory in order to link disk during stage of spawning guests.
```
OPTION LNKNOPAS
```
If under RACF, RACF command need to be executed like below while the BYOL is the name of the virtual machine which is going to run Feilong service.
```
RAC PERMIT BYOL CLASS(VMRDR) ID(VSMWORK1) ACCESS(UPDATE)
```

Note

Please note when under RACF (ESM of z/VM) is used, additional setup for SMAPI is needed to make the BYOL able to work.

See z/VM Systems Management Application Programming for how to make it.

Update BYOL definition about IUCV

Assume BYOL has its definition on z/VM, it needs to have following entry in its User Directory in order to communicate with the managed guests by the IUCV channel
```
IUCV ANY
```
See z/VM Systems Management Application Programming for how to make it.

Enable reader device

In order to get console output of target vm, BYOL’s reader device needs to be enabled to receive console output spool files send from target vm

Use the following command on BYOL itself to achieve that:
```
[root@xxxx ~]# cio_ignore -r 000c
[root@xxxx ~]# chccwdev -e 000c
Setting device 0.0.000c online
Done
```
If something like ‘is already online’ is returned, it means reader already online and feel free to ignore the warning.
Enable punch device

In order to spawn guest, BYOL needs to be able to punch files to spawned guests’ reader, so the punch device on BYOL needs to be enabled.

Use the following command on BYOL itself to achieve that:
```
[root@xxxx ~]# cio_ignore -r 000d
[root@xxxx ~]# chccwdev -e 000d
Setting device 0.0.000d online
Done
```
If something like ‘is already online’ is returned, it means punch already online and feel free to ignore the warning.

Note

Preparation step 2 and step 3 require to logoff then re-logon the BYOL to make the updates become effective.

3.1.2. Installation Requirements¶

The supported Python version includes:

Python 2.7
Python 3+

3.2. Installation using OBS Packages¶

The Open Build Service (OBS) is a generic system to build and distribute binary packages from sources in an automatic, consistent and reproducible way. OBS builds and provides an installable version of the zthin and zvmsdk packages for each of the distributions (RHEL, SLES, Ubuntu).

3.2.1. RPM for RHEL/Alma/Rocky¶

SSH onto the BYOL as root user, and then follow the following steps:

Add the feilong AlmaLinux repository from OBS

# dnf config-manager --add-repo=https://download.opensuse.org/repositories/Virtualization:/feilong/AlmaLinux_9/

Disable gpgkeycheck flag

Add the flag gpgkeycheck=0 to the /etc/yum.repos.d/download.opensuse.org_repositories_Virtualization_feilong_AlmaLinux_9_.repo file.
Disable SELinux

Update the config file /etc/selinux/config and set SELINUX=disabled. Make sure you reboot to ensure the changes are reflected and SELinux is disabled.

We are considering writing SELinux policies for Feilong that would enable to not disable SELinux as a whole.
Install the Extra Packages for Enterprise Linux.

Packages in EPEL are dependencies for the feilong packages installation. Make sure you add both the EPEL and the EPEL-Next repos.
Install the zthin and zvmsdk packages
# dnf install zthin zvmsdk
Skip to the SSH key authentication between consumer and BYOL section to continue.

3.2.2. RPM for SLES¶

SSH onto the BYOL as root user, and then follow the following steps:

Register to the SUSE Package Hub using SUSEConnect and refresh the available repos list.
Packages in the PackageHub are dependencies for the feilong package installation
# SUSEConnect --product PackageHub/15.5/s390x

Add the feilong SUSE repository from OBS

# zypper ar https://download.opensuse.org/repositories/Virtualization:/feilong/SLE_15_SP5/ feilong
# zypper refresh

Install the zthin and zvmsdk packages
# zypper in zthin zvmsdk
Skip to the SSH key authentication between consumer and BYOL section to continue.

3.2.3. DEB for Ubuntu¶

SSH onto the BYOL as root user, and then follow the following steps:

Add the feilong Ubuntu repository from OBS

# bash -c "echo 'deb http://download.opensuse.org/repositories/Virtualization:/feilong/xUbuntu_24.04/ /' > /etc/apt/sources.list.d/feilong.list"
# wget http://download.opensuse.org/repositories/Virtualization:/feilong/xUbuntu_24.04/Release.key
# mv Release.key /etc/apt/trusted.gpg.d/feilong.asc

Update the apt repository list
# apt update
Disable SELinux

Update the config file /etc/selinux/config and set SELINUX=disabled. Make sure you reboot to ensure the changes are reflected and SELinux is disabled.

We are considering writing SELinux policies for Feilong that would enable to not disable SELinux as a whole.

Install the zthin and zvmsdk packages
# apt-get install zthin zvmsdk
Skip to the SSH key authentication between consumer and BYOL section to continue.

3.3. Manual Installation¶

3.3.1. z/VM zthin install¶

zthin is a library written in C that works as part of the Feilong. It mainly focuses on socket connection from BYOL to z/VM SMAPI(System Management API). Feilong requires zthin as the backend to communicate with z/VM SMAPI, thus it needs to be installed before installing Feilong.

SSH onto the BYOL as root user, and then follow the following steps:

Clone build project from github

# git clone https://github.com/mfcloud/build-zvmsdk.git
# cd build-zvmsdk

Trigger the build tool

The build tool depends on the following commands: rpmbuild, gcc, so you should make sure these commands are usable on BYOL before running the following build.

For building on RHEL
```
# /usr/bin/bash buildzthinrpm_rhel master
```
For building on SLES
```
# /usr/bin/bash buildzthinrpm_sles master
```
If this build finishes successfully, the resulting rpm package will be generated in the /root/zthin-build/RPMS/s390x/ directory named in the format zthin-version-snapdate.s390x.rpm where version is the zthin version number and date is the build date.

For building on Debian, make sure you have dpkg-dev available.
```
   # /usr/bin/bash buildzthindeb master

If the build finishes successfully, the resulting deb package will be generated
in the /root/build-zvmsdk/feilong directory named in the format
*zthin-version.s390x.deb* where *version* is the zthin version
number and *date* is the build date.
```
Install the rpm or deb generated in last step
```
# rpm -ivh /root/zthin-build/RPMS/s390x/zthin-3.1.0-snap201710300123.s390x.rpm
```
Be sure to replace the zthin-3.1.0-snap201710300123.s390x.rpm with the correct version name.
```
# dpkg -i /root/build-zvmsdk/feilong/zthin-3.1.2.s390x.deb
```
Be sure to replace the zthin-3.1.2.s390x.deb with the correct version name.
Verify zthin can work
```
# /opt/zthin/bin/smcli Image_Query_DM -T opncloud
```
If all things went well, this smcli command should be able to return the directory entry of user OPNCLOUD.

If this command failed, you need to check the following items:
- The BYOL user is successfully authorized to issue SMAPI call.
- The SMAPI server on this z/VM host is working normally.
- The zthin rpm is installed without any error.
Optionally, Consider to add /opt/zthin/bin/ into $PATH so you can use smcli command directly.

3.3.2. z/VM SDK install¶

z/VM SDK is the upper transition layer of Feilong. It implements the supported SDK APIs by communicating with the zthin backend.

Install z/VM sdk
Please ensure to update your setuptools to the latest version before doing this step, the following installation step would rely on it to automatically install the depended python packages.
# git clone https://github.com/mfcloud/build-zvmsdk.git # cd build-zvmsdk
Trigger the build tool

The build tool depends on the following commands: rpmbuild, gcc, so you should make sure these commands are usable on BYOL before running the following build.

For building on RHEL
```
# /usr/bin/bash buildzvmdsdkrpm_rhel master
```
For building on SLES
```
# /usr/bin/bash buildzvmsdkrpm_sles master
```
If this build finishes successfully, the resulting rpm package will be generated in the /root/zvmsdk-build/RPMS/s390x/ directory named in the format zvmsdk-version-snapdate.s390x.rpm where version is the zvmsdk version number and date is the build date.

For building on Debian, make sure you have dpkg-dev available.
```
# /usr/bin/bash buildzvmsdkdeb master
```
If the build finishes successfully, the resulting deb package will be generated in the /root/build-zvmsdk/ directory named in the format zvmsdk-version.s390x.deb where version is the zthin version number and date is the build date.
Install the rpm or deb generated in last step
```
# rpm -ivh /root/zvmsdk/RPMS/s390x/zvmsdk-1.4.0-snap201710300123.s390x.rpm
```
Be sure to replace the zvmsdk-1.4.0-snap201710300123.s390x.rpm with the correct version name.
```
# dpkg -i /root/build-zvmsdk/feilong/zvmsdk-1.4.0.s390x.deb
```
Be sure to replace the zvmsdk-1.4.0.s390x.deb with the correct version name.

3.3.3. Upgrade z/VM SDK¶

If the z/VM SDK was installed via python setup.py install, you can fetch and checkout to new version, then upgrade it by issue python setup.py install again.

Note

If you upgrade from a version equal or lower than 1.6.2 to 1.6.3 or newer version, you have to add two new columns - wwpn_npiv and wwpn_phy into fcp table in sdk_fcp database with type `varchar(16)`, which is located at /var/lib/zvmsdk/databases/sdk_fcp.sqlite, for example, by sqlite3 command: ALTER TABLE fcp ADD COLUMN wwpn_npiv varchar(16) and ALTER TABLE fcp ADD COLUMN wwpn_phy varchar(16)

3.4. Configuration Sample¶

After z/VM SDK is installed, a file named ‘zvmsdk.conf.sample’ is generated under the /etc/zvmsdk/ folder. It contains all the supported configurations for z/VM SDK. You can refer to it to create your own configuration file which should be named as zvmsdk.conf.

Here’s a sample configuration in which several options marked as ‘required’ should be customized according to your environment.

[database]
dir=/var/lib/zvmsdk/databases/

[image]
sdk_image_repository=/var/lib/zvmsdk/images

[logging]
log_level=INFO
log_dir=/var/log/zvmsdk/

[network]
# IP address of the Linux machine which is running SDK on.
# This config option is required
my_ip=127.0.0.1

[sdkserver]
bind_addr=127.0.0.1
bind_port=2000
max_worker_count=64

[wsgi]
auth=none

[zvm]
# zVM disk pool and type for root/ephemeral disks.
# This config option is required
disk_pool=ECKD:eckdpool

# PROFILE name to use when creating a z/VM guest.
# This config option is required
user_profile=osdflt

# The default maximum number of virtual processers the user can define.
user_default_max_cpu=32

# The default maximum size of memory the user can define.
user_default_max_memory=64G

For the details of all configuration options, please refer to Configuration Options.

3.5. Setup for z/VM SDK Daemon¶

The Feilong is designed to be run inside a daemon. The daemon server is bond to the configured socket for receiving requests and then call the requested SDK API.

The daemon server would be run with user ‘zvmsdk’ and group ‘zvmsdk’, the following user and folder setup should be made on BYOL for the z/VM SDK daemon to run.

Create ‘zvmsdk’ user and group
```
# useradd -d /var/lib/zvmsdk/ -m -U -p PASSWORD zvmsdk
```
Replace the PASSWORD with your own password for the new created user.
Configure sudo access for ‘zvmsdk’ user (optional)

If Feilong is installed from source code python setup.py install or from package install such as deb or rpm, then you can skip this step as it’s already done during install stage.

The z/VM SDK Daemon relies on some privileged commands for the management of the z/VM host, so you need to grant the ‘zvmsdk’ user to run following commands with sudo without password:
- /usr/sbin/vmcp
- /opt/zthin/bin/smcli
- /usr/sbin/chccwdev
- /usr/sbin/cio_ignore
- /usr/sbin/fdasd
- /usr/sbin/fdisk
- /usr/sbin/vmur
- /usr/bin/mount
- /usr/bin/umount
- /usr/sbin/mkfs
- /usr/sbin/mkfs.xfs
- /usr/sbin/dasdfmt
- /opt/zthin/bin/unpackdiskimage
- /opt/zthin/bin/creatediskimage
- /opt/zthin/bin/linkdiskandbringonline
- /opt/zthin/bin/offlinediskanddetach
A sample is given in the following block, copy the content to /etc/sudoers.d/sudoers-zvmsdk:
```
# cat /etc/sudoers.d/sudoers-zvmsdk
zvmsdk ALL = (ALL) NOPASSWD:/usr/sbin/vmcp, /opt/zthin/bin/smcli, /usr/sbin/chccwdev, /usr/sbin/cio_ignore, /usr/sbin/fdasd, /usr/sbin/fdisk, /usr/sbin/vmur, /usr/bin/mount, /usr/bin/umount, /usr/sbin/mkfs, /usr/sbin/mkfs.xfs, /usr/sbin/dasdfmt, /opt/zthin/bin/unpackdiskimage, /opt/zthin/bin/creatediskimage, /opt/zthin/bin/linkdiskandbringonline, /opt/zthin/bin/offlinediskanddetach
```

Setup home directory

# mkdir -p /var/lib/zvmsdk
# chown -R zvmsdk:zvmsdk /var/lib/zvmsdk
# chmod -R 755 /var/lib/zvmsdk

Setup log directory

The folder to which the z/VM SDK log would be written to can be configured with the ‘log_dir’ option in ‘default’ section. By default, the log folder is ‘/var/log/zvmsdk’. If you have customized the ‘log_dir’ value, you need to change the folder in following commands accordingly.
```
# mkdir -p /var/log/zvmsdk
# chown -R zvmsdk:zvmsdk /var/log/zvmsdk
# chmod -R 755 /var/log/zvmsdk
```
Setup configuration directory
```
# mkdir -p /etc/zvmsdk
# chown -R zvmsdk:zvmsdk /etc/zvmsdk
# chmod -R 755 /etc/zvmsdk
# ls -l /etc/zvmsdk
```
A file named zvmsdk.conf should be found under /etc/zvmsdk folder and contains at least all the required options before the z/VM SDK daemon can be started.

3.6. SSH key authentication between consumer and BYOL server¶

For image import/export function, BYOL’s running user(eg zvmsdk) needs to be authorized by the user of the consumer (eg nova-compute) if they are not in same host. For example, if you want to import/export image from/to nova compute server，please make ensure you can ssh nova@nova-compute-ip without password from zvmsdk user on BYOL server. Refer to the following steps to configure it:

Logon to the nova-compute server and change the nova user’s right to be able to log in, and make sure port 22 is open.

ssh root@nova-compute-ip
usermod -s /bin/bash nova

where: nova-compute-ip: is the IP address of the nova compute node.

Change to nova user and inject the zvmsdk server’s public key into it.

su - nova
scp zvmsdk@zvmsdk-ip:/var/lib/zvmsdk/.ssh/id_rsa.pub $HOME mkdir -p $HOME/.ssh
mv $HOME/id_rsa.pub $HOME/.ssh/authorized_keys

where: zvmsdk: is the user on the BYOL server that runs the z/VM SDK. zvmsdk-ip: is the IP address of the BYOL server Note: If the $HOME/.ssh/authorized_keys file already exists, you just need to append the BYOL’s public key to it.

Ensure that the file mode under the $HOME/.ssh folder is 644.

chmod -R 644 $HOME/.ssh/*

Issue the following command to determine if SELinux is enabled on the system.

getenforce

If SELinux is enabled then set SELinux contexts on the nova home directory.

su -
chcon -R -t ssh_home_t nova_home

where: nova_home：is the home directory for the nova user on the nova compute server. You can obtain nova_home by issuing: echo ~nova

NOTE: If the host key of nova-compute server changed, please run the following command on zvmsdk server to clean the cached host key of nova-compute server from zvmsdk server’s known_hosts file

ssh-keygen -R nova-compute-ip

3.7. Start z/VM SDK Daemon¶

Configure the sdkserver service to start automatically at boot by command: .. code-block:: text

# systemctl enable sdkserver

The z/VM SDK Daemon can be started via the following command:

# systemctl start sdkserver

And make sure the sdkserver service status is ‘active (running)’ as following:

# systemctl status sdkserver
● sdkserver.service - zVM SDK API server
   Loaded: loaded (/usr/lib/systemd/system/sdkserver.service; disabled; vendor preset: disabled)
   Active: active (running) since Mon 2017-11-20 00:47:18 EST; 3s ago
 Main PID: 5779 (sdkserver)
   CGroup: /system.slice/sdkserver.service
           └─5779 /usr/bin/python /usr/bin/sdkserver

Nov 20 00:47:18 0822rhel7 systemd[1]: Started zVM SDK API server.
Nov 20 00:47:18 0822rhel7 systemd[1]: Starting zVM SDK API server...
Nov 20 00:47:18 0822rhel7 sdkserver[5779]: INFO: [MainThread] SDK server now listening

3.8. Verification¶

You can verify that the process is listenning on the configured port. For example:

# netstat -anp | grep 2000
tcp        0      0 127.0.0.1:2000          0.0.0.0:*               LISTEN      56434/python

3. Quick Start¶

3.1. Pre-requirements¶

3.1.1. Preparation on BYOL¶

3.1.2. Installation Requirements¶

3.2. Installation using OBS Packages¶

3.2.1. RPM for RHEL/Alma/Rocky¶

3.2.2. RPM for SLES¶

3.2.3. DEB for Ubuntu¶

3.3. Manual Installation¶

3.3.1. z/VM zthin install¶

3.3.2. z/VM SDK install¶

3.3.3. Upgrade z/VM SDK¶

3.4. Configuration Sample¶

3.5. Setup for z/VM SDK Daemon¶

3.6. SSH key authentication between consumer and BYOL server¶

3.7. Start z/VM SDK Daemon¶

3.8. Verification¶

Table of Contents

Previous topic

Next topic

This Page