Confidential Computing with SUSE Linux Enterprise Base Container Images Using the IBM Hyper Protect Platform #

You are encouraged to start your journey with Confidential computing with LinuxONE using IBM Cloud Hyper Protect Virtual Servers for Virtual Private Cloud (VPC).

The infrastructure for the trusted execution environment needed for HPVS is already set up and available as an easy-to-use service in IBM Cloud. If you want to use IBM Cloud Hyper Protect Virtual Servers for VPC, then all you need is an IBM Cloud Pay-As-You-Go account.

On-premises confidential computing deployments use IBM Hyper Protect Virtual Servers. This is the same technology used in IBM Cloud Hyper Protect Virtual Servers for VPC, but you will need to prepare the required infrastructure. The following high level infrastructure prerequisites are needed to use IBM Hyper Protect Virtual Servers:

Note

This guide was developed with the noted software versions. You are encouraged to use the latest releases to take advantage of various updates and security patches.

The IBM Hyper Protect Platform architecture is illustrated in this diagram at a high level. On the left are the components that comprise the confidential computing environment in IBM Cloud, on the right are those for on-premises or hosted datacenter scenarios. The architectural similarities facilitate a hybrid deployment model that gives you the flexibility to easily target the location of your workload depending on business requirements.

The components of the IBM Hyper Protect Platform include:

3.1 Workflow #

 

The workflow to prepare, deploy, and manage a confidential container workload in IBM Cloud or on-premises is shown below.

Cloud deployment	On-premises deployment
Prepare for IBM Cloud Hyper Protect Virtual Servers for VPC	Prepare for IBM Hyper Protect Services
Section 4.1.1, “Creating a Virtual Private Cloud (VPC)” Section 4.1.2, “Setting up a logging service for HPVS for VPC provisioning”	Section 4.2.1, “Verifying required hardware and enabling IBM Secure Execution technology” Section 4.2.2, “Installing and configuring an LPAR with KVM included in SLES for IBM Z and LinuxONE” Section 4.2.3, “Enabling Secure Execution capabilities on the KVM host” Section 4.2.4, “Downloading the HPCR image” Section 4.2.5, “Setting up an rsyslog logging service for HPVS log information”

Build, publish, and define a confidential container workload for the IBM Hyper Protect Platform

Section 5.1, “Building a container image” Section 5.2, “Publishing the container image to a registry” Section 5.3, “Defining the contract”

Deploy a confidential container workload using the IBM Hyper Protect Platform
Section 6.1, “Cloud deployment”	Section 6.2, “On-premises deployment”

Manage the confidential container workload after deployment

Section 7.1, “Enabling and verifying attestation”

Before you can deploy your confidential container workloads, you must prepare your environment.

Follow the steps detailed in Section 4.1, “Cloud preparation” or Section 4.2, “On-premises preparation” depending on the infrastructure environment you intend to use.

4.1 Cloud preparation #

 

The IBM Cloud Web Console is used in this guide, but it is also possible to perform the same actions using the IBM Cloud CLI or Terraform.

4.1.1 Creating a Virtual Private Cloud (VPC) #

 

1. Log in to the IBM Cloud Web Console.

2. In the upper right part of the Web console (between Manage and Help), select the correct account from the list.

3. Select Navigation Menu > VPC Infrastructure > VPCs.

4. Select the Region from the list.

5. Click Create.

6. Edit Name in the Details section (for example, vpc-myvpc).

   Do not change default selections for other items.

7. In the Subnets section, click Edit and rename the dynamically named subnets.

   For example, three, regional zones could be named: sn-myvpc-01, sn-myvpc-02, and sn-myvpc-03.

8. Click Create virtual private cloud.

9. Select the Default security group for the newly created VPC.

   1. Select Rules.

   2. Click Create in the Inbound rules section.

   3. Under Create inbound rule:

      1. Set Port min to 8443.

      2. Set Port max to 8443.

      3. Avoid changing any other default settings.

      4. Click Create.

10. Select Network > Floating IPs.

    1. Confirm the correct Region is selected.

    2. Click Reserve.

       1. Confirm the Region.

       2. Click Edit if you want to select a different Zone.

       3. Enter the Floating IP name (for example, myvpc-paynow-floatip).

       4. Click Reserve.

11. Make a note of the location (zone) within the region and the floating IP address that was assigned.

Important

Do not close the browser window or tab.

4.1.2 Setting up a logging service for HPVS for VPC provisioning #

 

1. In a new browser window or tab, log in to the IBM Cloud Web Console.

2. Select Navigation Menu > Observability > Logging.

3. Click Options > Create.

4. Complete the following in the IBM Log Analysis screen:

   1. In Select a location, select the same region that is used for your VPC.

   2. Under Select a pricing plan, select a plan.

   3. Under Configure your resource, set Service name (for example, IBM Log Analysis).

   4. Click I have read and agree to the following license agreements.

   5. Click Create.

5. Click Open dashboard in the IBM Log Analysis page.

6. Click Install Instructions (the icon is a question mark inside a circle).

7. Select Add Log Sources > Via Syslog side menu, then select rsyslog.

8. Make a note of the following items:

   • The ingestion key in the Your Ingestion key is: field.

   • The host name.

     1. View the /etc/rsyslog.d/22-logdna.conf configuration file.

     2. Find the comment line, '# Send messages to LogDNA over TCP using the template'.

     3. Locate the host name between @@ and :6514.

   1. Close the Add Log Sources window.

Important

Do not close the browser window or tab.

4.2 On-premises preparation #

 

To simplify the preparation, the information and steps provided in following sections are consolidated from multiple documentation sources. Links to the each documentation source is provided.

4.2.1 Verifying required hardware and enabling IBM Secure Execution technology #

 

1. Review the IBM Hyper Protect Virtual Servers 2.1.x Hardware requirements.

2. Confirm that the Feature Code 115 Secure Execution for Linux has been ordered and installed.

3. Use the machine serial number to obtain the host key document from IBM Resource Link.

4. Ensure the host key document is genuine and provided by IBM.

5. Import the host key document to complete the hardware enablement of the IBM Secure Execution technology.

4.2.2 Installing and configuring an LPAR with KVM included in SLES for IBM Z and LinuxONE #

 

Note

This section provides installation configuration and guidance but not a detailed set of steps.

1. Use the recommendation in Additional hardware requirements for the KVM host to define an LPAR.

   The following lsblk output is an example of the disk storage devices, sizes, lvm details, file system types and mount points used to test HPVS 2.1.x.

   NAME                                         SIZE FSTYPE       MOUNTPOINTS
   sde                                          500G mpath_member
   ├─sde1                                       500G LVM2_member
   └─3600507638081855cd80000000000004a          500G
     └─3600507638081855cd80000000000004a-part1  500G LVM2_member
       └─vmsvg-vms                              500G xfs          /var/lib/libvirt/images
   sdj                                          500G mpath_member
   ├─sdj1                                       500G LVM2_member
   └─3600507638081855cd80000000000004a          500G
     └─3600507638081855cd80000000000004a-part1  500G LVM2_member
       └─vmsvg-vms                              500G xfs          /var/lib/libvirt/images
   dasda                                        6.9G
   ├─dasda1                                     102M ext2         /boot/zipl
   └─dasda2                                     6.8G LVM2_member
     └─system-root                             13.6G btrfs        /
   dasdb                                        6.9G
   └─dasdb1                                     6.9G LVM2_member
     └─system-root                             13.6G btrfs        /

   At least one network interface must be defined. The following is the lszdev qeth output showing one OSA network interface has been defined.

   TYPE  ID                          ON   PERS  NAMES
   qeth  0.0.0800:0.0.0801:0.0.0802  yes  yes   eth0

2. Use the Installation on IBM Z and LinuxONE documentation to install the latest version of SUSE Linux Enterprise Server into the LPAR.

   The following is a list of recommended patterns to select during the installation.

   Name          | Summary
   --------------+-----------------------------------
   apparmor      | AppArmor
   base          | Minimal Base System
   enhanced_base | Enhanced Base System
   hwcrypto      | System z HW crypto support
   kvm_server    | KVM Host Server
   kvm_tools     | KVM Virtualization Host and tools
   x11_yast      | YaST User Interfaces
   yast2_basis   | YaST Base Utilities

   1. Register and fully patch the SLES installation.

3. Enable and start the KVM host

   systemctl enable --now libvirtd.service

Important

A networking choice should be considered at this time.

The KVM Host Networking Configuration Choices in the IBM documentation provides a detailed list of networking choices and pros and cons.

• Using a Linux bridge with NAT for KVM guests

• Using a Linux bridge (without NAT) for KVM guests

• Using an Open vSwitch bridge with KVM guests

• Using the MacVTap driver with KVM guests

Confirm prerequisites like OSA interface traffic forwarding are met for your choice of networking.

This getting started guide will use the MacVTap driver in Bridge mode with the eth0 interface. No prerequisites are required using MacVTap but it is important to review the MacVTap isolation / limitations section.

An external DHCP server is required to provide networking information for the VMs using MacVTAP.

4.2.3 Enabling Secure Execution capabilities on the KVM host #

 

1. Enable IBM Secure Execution

   1. Append prot_virt=1 to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub.

      The following is an example of the GRUB_CMDLINE_LINUX_DEFAULT line with prot_virt=1 appended.

      GRUB_CMDLINE_LINUX_DEFAULT="hvc_iucv=8 TERM=dumb mitigations=auto security=apparmor cio_ignore=all,!ipldev,!condev prot_virt=1"

   2. Recreate grub.cfg.

      grub2-mkconfig -o /boot/grub2/grub.cfg

   3. Reboot.

2. Verify IBM Secure Execution is enabled with virt-host-validate.

   Verify the line has PASS in the output.

     QEMU: Checking for secure guest support                                    : PASS

4.2.4 Downloading the HPCR image #

 

1. Make a directory on the KVM host to store the HPCR image.

   mkdir /opt/hpvs-hpcr

2. Download the latest version of the HPCR image from IBM Passport Advantage to the directory created in the previous step.

   

   Note

   Verify if an IBM HPCR fix pack is available from IBM Fix Central.

3. Verify the integrity and decompress the download following steps 5 - 6 of the procedure.

4. Make a note of location and file name of qcow2 HPCR image. For example, ibm-hyper-protect-container-runtime-23.3.0.qcow2 is the file name which is located in the /opt/hpvs-hpcr/IBM-HPVS-OnPrem-v2.1.4-EN-Trial/images.

4.2.5 Setting up an rsyslog logging service for HPVS log information #

 

With the release of SLES 15 SP5, Minimal VM images for IBM Z and LinuxONE systems can be downloaded from suse.com. Two KVM qcow2 image file options are available - kvm and Cloud. The file name of the qcow2 image files will include either kvm or Cloud for differentiation.

• The kvm image file will prompt during firstboot for information to customize items like host name and networking information.

• The Cloud image file uses cloud-init to customize the host name and networking information.

You can choose to manually install SLES with the installation media or use a pre-built SLES image file from SUSE.

Note

This guide will provide the steps to use the Cloud image to deploy an rsyslog kvm virtual machine on the same KVM host where the confidential computing workload will be run.

1. Make a directory to store the disk image and other files for the rsyslog VM.

   mkdir /var/lib/libvirt/images/rsyslog

2. Download the SLES 15 SP5 Minimal VM Cloud qcow2 image file at suse.com. Place the file in the /var/lib/libvirt/images/rsyslog directory. Name the file rsyslog.qcow2.

3. Create the following required cloud-init files.

   1. vi /var/lib/libvirt/images/rsyslog/meta-data

      local-hostname: rsyslog

   2. vi /var/lib/libvirt/images/rsyslog/user-data

      #cloud-config
      ssh_authorized_keys:
        - <public ssh key 1>
        - <public ssh key 2>

      ⇒ where <public ssh key 1> and if needed <public ssh key 2> will be added to the authorized_keys file for the sles user.
      

      

      Note

      This configuration requires an external DHCP server to provide the static networking information to the rsyslog server based on MAC address. Additional cloud examples for networking and other configurations can be found at the following resources:

      • cloud-init configuration examples

      • Configuration with cloud-init

      • Cloud config examples

4. Generate a MAC address for the rsyslog VM.

   1. Create the /root/bin/macgen.py python script.

      #!/usr/bin/python3
      # macgen.py script to generate a MAC address for guests on KVM
      
      import random
      
      def randomMAC():
          mac = [ 0x52, 0x54, 0x00,
          random.randint(0x00, 0x7f),
          random.randint(0x00, 0xff),
          random.randint(0x00, 0xff) ]
          return ':'.join(map(lambda x: "%02x" % x, mac))
      
      print(randomMAC())

   2. Make the macgen.py script executable.

      chmod +x /root/bin/macgen.py

   3. Run macgen.py and note the output. Here is an example when run.

      # macgen.py
      52:54:00:5b:15:df

5. Use the generated MAC address to define a host entry with a static IP address in your DHCP server.

6. Define and start the rsyslog VM with the following command.

   virt-install \
   --name=rsyslog \
   --osinfo sle15sp5 \
   --memory=2048 \
   --vcpus=2 \
   --clock offset=utc \
   --events on_poweroff=destroy,on_reboot=restart,on_crash=destroy \
   --disk /var/lib/libvirt/images/rsyslog/rsyslog.qcow2,\
   driver.iommu=on,target.bus=virtio,boot.order=1 \
   --network type=direct,source=eth0,source.mode=bridge,model.type=virtio,\
   driver.name=vhost,mac.address=<macaddress> \
   --console pty,target.type=sclp,target.port=0 \
   --audio id=1,type=none \
   --memballoon none \
   --panic s390 \
   --cloud-init user-data=/var/lib/libvirt/images/rsyslog/user-data,\
   meta-data=/var/lib/libvirt/images/rsyslog/meta-data

   ⇒ where <macaddress> was noted above.

   The VM console will be displayed and the VM will boot. The VM IP address is properly configured when the IP address is displayed next to eth0. For example:

   Welcome to SUSE Linux Enterprise Server 15 SP5  (s390x) - Kernel 5.14.21-150500.53.2-default (ttysclp0).
   
   eth0: 10.161.159.11 fe80::5054:ff:feb6:ad3e
   
   
   rsyslog login:

   

   Note

   Press Ctrl + ] keys to disconnect from the VM console.

7. Log in to the VM via SSH as the sles user from another system using the private portion of the SSH key defined above.

8. Register and fully patch SLES.

   1. Reboot if necessary.

9. Install the rsyslog packages.

   zypper in rsyslog rsyslog-module-gtls

10. Generate self-signed certificates for encrypted communication from the HPCR instance to the rsyslog server.

    1. mkdir /certs && cd /certs to create and change into the directory.

    2. Create the following OpenSSL configuration files.

       /certs/ca.cnf

       [ req ]
       default_bits = 2048
       default_md = sha256
       prompt = no
       encrypt_key = no
       distinguished_name = dn
       
       [ dn ]
       C = US
       O = rsyslog CA
       CN = ca.rsyslog

       /certs/rsyslog.cnf

       [ req ]
       default_bits = 2048
       default_md = sha256
       prompt = no
       encrypt_key = no
       distinguished_name = dn
       
       [ server ]
       subjectAltName = IP:<ip address>
       extendedKeyUsage = serverAuth
       
       [ dn ]
       CN = <ip address>

       ⇒ where <ip address> is the IP address of the rsyslog VM.

       /certs/slebci-paynow-website.cnf

       [ req ]
       default_bits = 2048
       default_md = sha256
       prompt = no
       encrypt_key = no
       distinguished_name = dn
       
       [ server ]
       subjectAltName = IP:<ip address>
       extendedKeyUsage = serverAuth
       
       [ dn ]
       CN = <ip address>

       ⇒ where <ip address> is the IP address of the HPCR VM that will run the PayNow Web site application.

    3. Generate the key, certificate signing request and certificate for the certificate authority.

       openssl genrsa -out ca-key.pem 4096
       openssl req -config ca.cnf -key ca-key.pem -new -out ca-request.pem
       openssl x509 -signkey ca-key.pem -in ca-request.pem -req -days 3650 \
       -out ca-cert.pem

    4. Generate the key, certificate signing request and CA signed certificate for the rsyslog server.

       openssl genrsa -out rsyslog-key.pem 4096
       openssl req -config rsyslog.cnf -key rsyslog-key.pem -new \
       -out rsyslog-request.pem
       openssl x509 -req -in rsyslog-request.pem -days 1000 -CA ca-cert.pem \
       -CAkey ca-key.pem -CAcreateserial -extfile rsyslog.cnf -extensions server \
       -out rsyslog-cert.pem

    5. Generate the key, certificate signing request and CA signed certificate for the HPCR VM that will run the PayNow Web site.

       openssl genrsa -out slebci-paynow-website-key.pem 4096
       openssl req -config slebci-paynow-website.cnf \
       -key slebci-paynow-website-key.pem -new -out slebci-paynow-website-request.pem
       openssl x509 -req -in slebci-paynow-website-request.pem -days 1000 \
       -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \
       -out slebci-paynow-website-cert.pem

11. Create the rsyslog configuration to capture the logging information from the HPCR VM that will run the PayNow Web site.

    vi /etc/rsyslog.d/server.conf

    # output to journal
    module(load="omjournal")
    template(name="journal" type="list") {
    # can add other metadata here
    property(outname="PRIORITY" name="pri")
    property(outname="SYSLOG_FACILITY" name="syslogfacility")
    property(outname="SYSLOG_IDENTIFIER" name="app-name")
    property(outname="HOSTNAME" name="hostname")
    property(outname="MESSAGE"  name="msg")
    }
    
    ruleset(name="journal-output") {
    # action(type="omjournal" template="journal")
    action(type="omfile" dirCreateMode="0766" FileCreateMode="0644" File="/var/log/hpcr.log")
    }
    
    # make gtls driver the default and set certificate files
    $DefaultNetstreamDriver "gtls"
    $DefaultNetstreamDriverCAFile /certs/ca-cert.pem
    $DefaultNetstreamDriverCertFile /certs/rsyslog-cert.pem
    $DefaultNetstreamDriverKeyFile /certs/rsyslog-key.pem
    
    # load TCP listener
    module(
    load="imtcp"
    StreamDriver.Name="gtls"
    StreamDriver.Mode="1"
    StreamDriver.Authmode="x509/certvalid"
    )
    
    # start up listener at port 6514
    input(
    type="imtcp"
    port="6514"
    ruleset="journal-output"
    )

    ⇒ where logging information will be written to /var/log/hpcr.log. Comment out this line and uncomment the line above to write log information to the journal.

12. Enable, start and verify that the rsyslog service is running.

    systemctl enable --now rsyslog
    systemctl status rsyslog

In this section you prepare a workload container image, publish the container image to a registry, and define the IBM Hyper Protect Services contract that will be used during deployment. The steps in this section are the same for cloud and on-premises deployments.

You will use the PayNow Node.js application, which has been already built on a SLE BCI container image and published to a container registry. The steps are also available if you want to build the PayNow Node.js application on a SLE BCI container.

See confidential computing in action. In this demonstration, the PayNow Node.js application shows a financial transaction running without confidential computing and with confidential computing.

5.3 Defining the contract #

 

A contract is a required definition of the workload configuration in YAML format.

1. Create a directory and Docker Compose file on a local system.

   mkdir slebci-paynow-website
   cd slebci-paynow-website
   vi docker-compose.yml

   Update the digest of the latest image in the following example if using the pre-built PayNow Node.js application container image.

   services:
     paynow:
       image: ghcr.io/mfriesenegger/slebci-paynow-website@sha256:ecb229f68aef81ca4a2b7b5a9eb192081fa2a170e44d9e5a28180bb12682ce5d
       ports:
         - "8080:8080"
         - "8443:8443"

   

   Important

   Verify the SHA256 digest of the prebuilt image.

   Or use the following if the PayNow Node.js application container image was built by you and published in your GitHub Container registry.

   services:
     paynow:
       image: ghcr.io/<github user>/slebci-paynow-website@<sha256 digest>
       ports:
         - "8080:8080"
         - "8443:8443"

   

   Note

   Replace <github user> with your personal GitHub user name.

   Replace <github digest> with the digest information for the in published in your GitHub Container registry.

2. Create a base64 encoded TAR archive .

   tar -czvf - docker-compose.yml | base64 -w0 > docker-compose.b64

3. Create the contract file.

   vi slebci-paynow-website-contract.yml

   1. Add the logging configuration to the contract.

      Use the following Section 4.1.2, “Setting up a logging service for HPVS for VPC provisioning” for IBM Cloud.

      env: |
        type: env
        logging:
          logDNA:
            hostname: <hostname>
            port: 6514
            ingestionKey: <ingestionKey>

      ⇒ where <hostname> and <ingestionKey> were noted earlier.

      Use the following Section 4.2.5, “Setting up an rsyslog logging service for HPVS log information” for on-premises deployments.

      env: |
        type: env
        logging:
          syslog:
            hostname: <ip address>
            port: 6514
            server: <ca-cert>
            cert: <client certificate>
            key: <client private key>

      ⇒ where <ip address> is the IP address of the rsyslog server.

      ⇒ where the output of the following command executed on the rsyslog server replaces each item.

      <ca-cert>

      IFS=$'\n'; echo -n \"; for line in $(cat /certs/ca-cert.pem);\
       do echo -n $line"\n"; done; echo \"

      <client certificate>

      IFS=$'\n'; echo -n \"; for line in $(cat\
       /certs/slebci-paynow-website-cert.pem); do echo -n $line"\n"; done; echo \"

      <client private key>

      IFS=$'\n'; echo -n \"; for line in $(cat\
       /certs/slebci-paynow-website-key.pem); do echo -n $line"\n"; done; echo \"

      

      Note

      The certificate and key output generated by the commands above will be copied and pasted as a single line for each item.

   2. Add the workload configuration to the contract.

      Use the following if using the pre-built PayNow Node.js application container image.

      workload: |
        type: workload
        compose:
          archive: <archive>

      ⇒ where <archive> was created in the Create a base64 encoded TAR archive [base64-encoded-archive] step.

      Or use the following if the PayNow Node.js application container image was built by you and published in your GitHub Container registry.

      workload: |
        type: workload
        auths:
          ghcr.io:
            username: <github user>
            password: <github token>
        compose:
          archive: <archive>

      ⇒ where <github user> and <github token> are for your personal GitHub account.

      ⇒ where <archive> was created in the Create a base64 encoded TAR archive [base64-encoded-archive] step.

An example contract using the IBM Cloud logging service with the pre-built image is shown below.

Note

The base64 data for the archive item is truncated.

env: |
  type: env
  logging:
    logDNA:
      hostname: syslog-a.ca-tor.logging.cloud.ibm.com
      port: 6514
      ingestionKey: e2db535664e682b59101b742d59234da
workload: |
  type: workload
  compose:
    archive: H4sIAAAAAAAAA+3UzW7bMAwHcJ/zFELucahP2gYG7LjjXkG2mNRoXQdWtrZvP6XBsCyHboeuW7H/

An example contract using the rsyslog logging service with the pre-built image is shown below.

Note

The certificate and key data for the rsyslog logging service is truncated.

The base64 data for the archive item is truncated.

env: |
  type: env
  logging:
    syslog:
      hostname: 10.161.159.11
      port: 6514
      server: "-----BEGIN CERTIFICATE-----\nMIIE9TCCAt0CFGXTURlEXHPvfkrSMq6u8Okeo3NrMA0GC...0qex34LGN3kYw==\n-----END CERTIFICATE-----\n"
      cert: "-----BEGIN CERTIFICATE-----\nMIIE3jCCAsYCFBYlycZ0oZP8fenP3RSx7/PJDkjcMA0GCSq...M0yk3XJgr\nB5w=\n-----END CERTIFICATE-----\n"
      key: "-----BEGIN RSA PRIVATE KEY-----\nMIIJKgIBAAKCAgEA1bSLJYv93O9nMUZOB4Qo79N9vrZE...4WUbz3Fyw==\n-----END RSA PRIVATE KEY-----\n"
workload: |
  type: workload
  compose:
    archive: H4sIAAAAAAAAA+3UzW7bMAwHcJ/zFELucahP2gYG7LjjXkG2mNRoXQdWtrZvP6XBsCyHboeuW7H/

The deployment steps differ, depending on whether you are deploying to cloud or to your on-premises environment. Proceed to either Section 6.1, “Cloud deployment” or Section 6.2, “On-premises deployment”.

This section focuses on steps in the Section 3.1, “Workflow” that introduce additional ways to interact with the confidential containized workload.

Containerized confidential computing enables you to protect your workload data no matter where it is running. This guide featured the PayNow Web site application. It was built on SUSE Linux Enterprise Base Container Images and you securely deployed it on the IBM Hyper Protect Platform, either in the cloud or on-premises.

Continue your learning journey with the following additional resources:

Copyright © 2006–2024 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled "GNU Free Documentation License".

SUSE, the SUSE logo and YaST are registered trademarks of SUSE LLC in the United States and other countries. For SUSE trademarks, see https://www.suse.com/company/legal/.

Linux is a registered trademark of Linus Torvalds. All other names or trademarks mentioned in this document may be trademarks or registered trademarks of their respective owners.

Documents published as part of the series SUSE Technical Reference Documentation have been contributed voluntarily by SUSE employees and third parties. They are meant to serve as examples of how particular actions can be performed. They have been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. SUSE cannot verify that actions described in these documents do what is claimed or whether actions described have unintended consequences. SUSE LLC, its affiliates, the authors, and the translators may not be held liable for possible errors or the consequences thereof.

Copyright © 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—​for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Copyright (c) YEAR YOUR NAME.
   Permission is granted to copy, distribute and/or modify this document
   under the terms of the GNU Free Documentation License, Version 1.2
   or any later version published by the Free Software Foundation;
   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   A copy of the license is included in the section entitled “GNU
   Free Documentation License”.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “ with…​Texts.” line with this:

with the Invariant Sections being LIST THEIR TITLES, with the
   Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.