SUSE Lifecycle Management Server 1.3

SUSE Lifecycle Management Server Manual

Publication Date 07 Aug 2013

AuthorsTomáš Bažant

Copyright © 2006–2013 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.

For SUSE or Novell trademarks, see the Novell Trademark and Service Mark list http://www.novell.com/company/legal/trademarks/tmlist.html. All other third party trademarks are the property of their respective owners. A trademark symbol (®, ™ etc.) denotes a SUSE or Novell trademark; an asterisk (*) denotes a third party trademark.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, SUSE LINUX Products GmbH, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.


Contents

1. About this Guide
1.1. Overview
1.2. Feedback
1.3. Documentation Conventions
2. Installation and Deployment
2.1. System Requirements
2.2. Upgrade from SLMS 1.2
2.3. Upgrade with Add-On Media
2.4. Online Migration
2.5. Installing SLMS as an Add-On During the Initial SLE Installation
2.6. Installation as an Add-On On Top of an Already Installed System
2.7. Deploying SLMS as an Appliance
3. Server Configuration with WebYaST
3.1. WebYaST and IPv6
3.2. Starting WebYaST
3.3. All-In-One Server Setup
3.4. Setup with Two Servers
3.5. Setting Database Credentials
3.6. Setting the GPG Key to Sign Update Repositories
3.7. Setting and Testing SUSE Studio Credentials
3.8. Adding the First Administrator Account for the Web Interface
3.9. Configuring Remote PostgreSQL Server
3.10. Configuring Proxies
4. Maintenance Workflow
4.1. Scenarios Overview
4.2. Testing Update Repository
4.3. How to Test a New Patch
5. Appliances, Mirroring, and Creating Updates
5.1. Disconnected Setup
5.2. Appliance Adaptation
5.3. How to Mirror Update Repositories
6. Web-based User Interface
6.1. General Information
6.2. Managing User Accounts
6.3. Managing Appliances
6.4. Update Repositories
6.5. Manually Handled Packages
6.6. Overlay Files
6.7. Managing Customer Accounts
6.8. Managing Subscriptions
6.9. Customer Center
7. Data Backup and Database Maintenance
7.1. Database and Storage
7.2. SLMS Data
7.3. Database Maintenance
8. Command Line Scripts
8.1. slms commands
8.2. slms-admin-ui-user
8.3. migrate_postgresql_database
8.4. rcslms
9. Configuration Files
9.1. /etc/slms.conf
9.2. /etc/slms-secrets.conf
9.3. /etc/slms-cc.conf
10. Questions and Answers
10.1. Something went wrong. Where are the log files?
10.2. Hard disk out of space on the SLMS server. How can I free some space?
10.3. Update tool reports repository metadata problem. What does that mean?
10.4. Why is not a SUSE Studio appliance visible in SLMS after synchronization?
10.5. I plan to replace one SUSE Studio instance with another. Is it OK?
10.6. I cannot log in to SLMS. What is the problem?
10.7. How do I add/replace an old SSL certificate with a new one?
10.8. How do I adapt an appliance using command line?
10.9. How do I publish an update patch using command line?
A. SSL Certificates
A.1. Self-signed SSL Certificates
A.2. CA SSL Certificates
A.3. How to Install SSL Certificate on the SLMS Server
A.4. How to Add SSL Certificate to an Appliance
A.5. How to Copy the SSL Certificate to the Client Appliance
B. GNU Licenses
B.1. GNU Free Documentation License
Index

List of Figures

2.1. Package Installation
2.2. Software Pattern Selection (text mode)
2.3. License Agreement and List of Languages
2.4. Administrator Settings Dialog
2.5. Network Dialog
2.6. Registration Dialog
3.1. WebYaST Control Panel
3.2. General Settings Tab of SLMS WebYaST Plug-in
3.3. Database Tab of SLMS WebYaST Plug-in
3.4. SUSE Studio Tab of SLMS WebYaST Plug-in
3.5. Proxy Configuration in YaST
6.1. SLMS Web User Interface
6.2. Studio Details
6.3. Warning Messages
6.4. Adding New User Account
6.5. Appliance Details
6.6. Update Patch Awaiting QA Approval
6.7. Update Repository Details
6.8. Additional Packages
6.9. Overlay Files
6.10. Customers Screen
6.11. Subscriptions Screen
6.12. Subscription Properties
6.13. Registrations
6.14. Node Download Statistics
6.15. List of Subscriptions in the Customer Center
6.16. List of Nodes in Customer Center

List of Examples

6.1. Using Custom CSS File

Chapter 1. About this Guide

SUSE Lifecycle Management Server is a server tool for Original Equipment Manufacturer (OEM) Partners. It delivers updates for their appliances based on SUSE Linux Enterprise 11 products. It also provides basic interfaces for managing customers' data and their subscriptions.

This manual introduces the SUSE Lifecycle Management Server installation and configuration process, as well as procedures for regular administration tasks both with the command line scripts and the Web user interface.

1.1. Overview

The manual is divided into the following chapters:

Chapter 2: Installation and Deployment

This chapter introduces the installation process. You can install the SUSE Lifecycle Management Server add-on together with your base system during the installation process, on top of an already installed base system, or deploy it as an appliance. The chapter also describes how to upgrade from version 1.2.

Chapter 3: Server Configuration with WebYaST

This chapter introduces the WebYaST SLMS plug-in. With the plug-in, you can configure all SLMS Server options, such as registration URL, database and mirroring credentials, and whether to activate or deactivate the SLMS service.

Chapter 4: Maintenance Workflow

This chapter helps you understand how SUSE Lifecycle Management Server works. It describes supported scenarios, workflow for managing update repositories, and procedures for testing new update patches.

Chapter 5: Appliances, Mirroring, and Creating Updates

This chapter describes how to mirror update repositories, and create testing and production update repositories. It also describes appliance adaptation and disconnected setup in a more detailed way.

Chapter 6: Web-based User Interface

This chapter introduces the process of configuring and managing SUSE Lifecycle Management Server with an intuitive Web-based user interface.

Chapter 7: Data Backup and Database Maintenance

This chapter describes directories and files where SLMS stores its critical data which need to be regularly backed up. It also describes how to run database maintenance.

Chapter 8: Command Line Scripts

This chapter introduces important command line scripts to manage SUSE Lifecycle Management Server.

Chapter 9: Configuration Files

This chapter describes SLMS configuration files.

Chapter 10: Questions and Answers

This chapter answers a number of frequent questions to help you solve specific tasks.

Many chapters in this manual contain links to additional documentation resources. These include additional documentation that is available on the system as well as documentation available on the Internet.

For an overview of the documentation available for your product and the latest documentation updates, refer to http://www.suse.com/documentation.

1.2. Feedback

Several feedback channels are available:

Bugs and Enhancement Requests

For services and support options available for your product, refer to http://www.suse.com/support/.

To report bugs for a product component, log into the Novell Customer Center from http://www.suse.com/support/ and select My Support+Service Request.

User Comments

We want to hear your comments about and suggestions for this manual and the other documentation included with this product. Use the User Comments feature at the bottom of each page in the online documentation or go to http://www.suse.com/documentation/feedback.html and enter your comments there.

Mail

For feedback on the documentation of this product, you can also send a mail to doc-team@suse.de. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

1.3. Documentation Conventions

The following typographical conventions are used in this manual:

  • /etc/passwd: directory names and filenames

  • placeholder: replace placeholder with the actual value

  • PATH: the environment variable PATH

  • ls, --help: commands, options, and parameters

  • user: users or groups

  • Alt, Alt+F1: a key to press or a key combination; keys are shown in uppercase as on a keyboard

  • File, File+Save As: menu items, buttons

  • This paragraph is only relevant for the specified architectures. The arrows mark the beginning and the end of the text block.

  • Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.

Chapter 2. Installation and Deployment

SUSE Lifecycle Management Server (SLMS) is distributed either as an appliance, or as an add-on product for the SUSE Linux Enterprise Server 11 system. You can choose to install the SLMS add-on together with your base system during the initial installation process, or you can install the SLMS add-on on top of an already-installed base system at any later time.

[Warning]slms User Used by the System

During Add-On installation, you may be prompted to create a user account. Do not choose slms as the username because such user is already reserved by the SLMS system and its creation will lead to a conflict.

2.1. System Requirements

2.1.1. Minimal System Requirements

To install and run SLMS, you need to have a system with the following minimal system requirements:

  • 1 GB of RAM

  • 20 GB of free hard disk space

  • Network interface

2.1.2. Recommended System Requirements

To ensure optimal performance of SLMS, we recommend the following system requirements:

  • At least 2 GB of RAM

  • 100 GB of free hard disk space

  • Network interface

2.1.3. Supported Processor Platforms

The operation of SLMS is supported on the x86_64 CPU architecture only.

2.1.4. SLMS and IPv6

IPv6 is the internet protocol of the future. It is meant to replace the current IPv4, while bringing several important advantages, such as expansion of the address space and improved high-speed data transmission. The changed format of the network addresses in IPv6 is not seamlessly supported by all network programs (see Section 3.1, “WebYaST and IPv6” for WebYaST issues). Therefore you need to be careful and double check if the hostname specified in the following places is correct and identical:

  • The file /etc/hosts on the appliance must contain a line with the full domain name of the server and the related IPv6 address, such as

    2001:db8::b         <slms_server_hostname>
  • The file /etc/suseRegister.conf on the appliance must contain the same hostname in the following line:

    url = https://<slms_server_hostname>/center/regsvc
  • In the /etc/slms.conf file (see Section 9.1, “/etc/slms.conf”) on the SLMS server, specify the hostname for the following option:

    redirector_url = https://<slms_server_hostname>
  • After you deliver the SLMS server SSL certificate to the appliance (see Appendix A, SSL Certificates, check if the output of the following command contains the same hostname as in the previous examples:

    openssl x509 -text -in /etc/slms.d/certs/servercert.pem

2.1.5. Supported Server Scenarios

We currently support two server setups:

All-in-one server setup

All SLMS services are installed and run on a single server. This setup is typical if you are not particularly concerned about performance or security issues. In this setup, the registration server and the customer center are accessible on port 443 (HTTPS), while the administration part itself runs on port 4849.

To use this setup, select both SLMS Management Server and SLMS Customer Service installation patterns during the SLMS installation (see Section 2.6, “Installation as an Add-On On Top of an Already Installed System”).

External / internal server setup

Use this setup if you need to access the management application from within one (typically internal) network, while you want the customers to access appliance updates and the customer center in another (external) network environment. This solution is generally more secure. In this setup, all services (customer center, registration server, and administration) are accessible on ports 443 of the related hosts.

To use this setup you must install SLMS on all the deployed servers. Select the SLMS Management Server installation pattern for the internal server deployment while the SLMS Customer Service installation pattern for the machine serving appliance updates.

2.2. Upgrade from SLMS 1.2

If you have already been running SLMS version 1.2, you can upgrade to version 1.3. There are two supported methods: upgrade with add-on media, or online migration. Read on and choose the right upgrade method for your site.

[Important]PostgreSQL version 8

After the upgrade to SLMS 1.3, your site will still be running PostgreSQL 8, although version 9 is already available. You should update your SLMS database to PostgreSQL 9 immediately after the SLMS upgrade. Follow these steps:

  1. Make sure there is enough free disk space under /var/lib/pgsql/ before you start the migration. The migrate_postgresql_database script dumps the current database content to a text file, creates a new PostgreSQL version 9 database, and reloads the dump back there. So there needs to be enough space for the old PostgreSQL 8 database files + the dump file + the newly imported version 9 database at one point in time.

  2. If you run two-server scenario, shut the external server down first. Otherwise changes done during the migration, such as a new client registration, may get lost.

  3. On the (internal) SLMS server, run the migrate_postgresql_database script as root. See Section 8.3, “migrate_postgresql_database” for more information on the script.

  4. For two-server scenario, start the external server again. After it is up, check whether the site behaves as expected.

2.2.1. Before the Upgrade

There are several important points you have to focus on before you start the migration process. They are valid regardless of what upgrade method you prefer.

  • Make sure that the SLMS instance has access to nu.novell.com in order to download all required packages. You may also use a local instance of the Subscription Management Tool (SMT) instead. In this case, make sure that SMT has mirrored the SLMS 1.3 repositories as well as latest updates from SLMS 1.2.

  • When using SUSE Studio Onsite, you have to upgrade it on the same occasion as SLMS itself.

  • After your instance of SUSE Studio is upgraded, all the appliances need to be SLMS-enabled in SUSE Studio - at least set the SLMS registration URL. SSL certificates and GPG keys are not required unless the appliances will be rebuilt in SUSE Studio.

    [Note]

    Before the appliances are SLMS-enabled in SUSE Studio, they will not be visible in SLMS even after refreshing the Appliances page of SLMS.

  • After you enable the appliance in SUSE Studio for SLMS and refresh appliances in SLMS, you can normally manage it with the Web interface as you did the previous version.

  • SLMS 1.2 runs on SUSE Linux Enterprise Server 11 SP1. We encourage you to upgrade the base system to SP2 together with the upgrade to SLMS 1.3.

[Important]

You are strongly advised to backup your SLMS data before starting the migration. Otherwise, you will not be able to restore your data in case of upgrade failure. For more information, see Chapter 7, Data Backup and Database Maintenance.

2.3. Upgrade with Add-On Media

If you have already been running SLMS version 1.2, it is possible to upgrade the product to version 1.3 while preserving all SLMS data from the previous version. The database content will be migrated to the newer version once the upgraded product services start. Several conditions, however, must be met before the upgrade may begin:

  • All released update patches of your base SLES 11 SP1 system must be applied prior to SLMS upgrade.

  • Your SLMS 1.2 installation must be installed, configured and able to run. It does not have to be running during the upgrade process.

  • The SLMS package itself must be updated to the latest version.

  • The system must have an active Internet connection available.

  • You must obtain the SLMS 1.3 Add-on CD / image.

[Important]

You are strongly advised to backup your SLMS data before starting the upgrade. Otherwise, you will not be able to restore your data in case of upgrade failure. For more information, see Chapter 7, Data Backup and Database Maintenance.

The upgrade procedure is almost identical with the standard SLMS add-on installation (Section 2.6, “Installation as an Add-On On Top of an Already Installed System”). The only difference is that the pattern selection step is skipped and the existing SLMS setup (all-in-one or two-server) is used for the upgrade.

2.3.1. After the Migration

After the upgrade with the add-on media is finished, SLMS is upgraded to its initial release version. Because update patches to SLMS and the base SLE system are being released continuously, you are advised to apply possible update patches to the freshly upgraded site immediately after the upgrade. For this purpose, use you favorite tooling — zypper, YaST, or WebYaST.

2.4. Online Migration

Apart from upgrading SLMS version 1.2 by means of an Add-on disc, it is also possible to do an online migration. This method saves your time otherwise spent on downloading the Add-on media.

2.4.1. Performing the Online Migration

There are two ways to perform the online migration from SLMS 1.2 to SLMS 1.3. For those who prefer using YaST during the migration process, there is the YaST migration tool called wagon. Those who prefer not to install additional software (especially if SLMS 1.2 was deployed as an appliance), there is a zypper — a command line tool which you can use in a script to automate the whole migration process.

For more general details about online migration, refer to SUSE Linux Enterprise Server 11 documentation http://www.suse.com/documentation/sles11/.

2.4.1.1. Upgrade with Wagon

To migrate SLMS 1.2 to SLMS 1.3 with Wagon:

  1. Make sure that you have installed all available patches. Without the recent update of the SLMS 1.2 product definition, the upgrade via Wagon will fail. Run (possibly repeatedly) zypper patch or use the usual update tooling (YaST, WebYaST) to install all pending patches.

  2. Install wagon and one of the graphical user interfaces for YaST (Ncurses, QT, GTK). For Ncurses, use zypper in yast2-wagon yast2-ncurses, for example. This will include all package dependencies as well.

  3. Run Wagon (yast2 wagon) and follow the migration workflow. You will receive the installation repository for SLMS 1.2 from Novell Customer Center, so there is no need to manually point to it. For more details, refer to SUSE Linux Enterprise Server 11 documentation http://www.suse.com/documentation/sles11/.

  4. After the upgrade finishes, restart SLMS with rcslms restart, or using YaST or WebYaST. You can reboot the whole machine alternatively.

2.4.1.2. Migration with zypper

Migration with zypper requires more manual steps, but does not require you to install additional software, and can therefore keep the SLMS image smaller in size.

To perform migration with zypper:

  1. Make sure you have installed all available patches. Run (possibly repeatedly) zypper patch to install all pending patches.

  2. Install the migration product. Run zypper in sle-slms-1_3-migration.

  3. Register the migration product via suse_register. After the successful registration, you will see the SLMS 1.3-Pool repository enabled (run zypper lr to verify that).

  4. Perform the upgrade itself with zypper dup. Depending on the software you have installed, you may need to resolve dependency conflicts. After the upgrade, zypper products should not report the migration product or SLMS 1.2 installed any more.

  5. Register SLMS 1.3 via suse_register. After the registration, the SLMS 1.2 repositories will be disabled. This applies only to the repositories added from Novell Customer Center. Therefore you may need to disable or remove, for example, the repository that you made the installation from.

  6. After the upgrade finishes, restart SLMS with rcslms restart, or using YaST or WebYaST. You can reboot the whole machine alternatively.

2.5. Installing SLMS as an Add-On During the Initial SLE Installation

To install the SLMS add-on product during the initial SUSE Linux Enterprise Server installation process, include the add-on media in the System Analysis step during installation:

  1. Start the SUSE Linux Enterprise Server 11 installation as usual. For more information, see the SUSE Linux Enterprise Server Deployment Guide, available at .

  2. In the System Analysis step, check the Include Add-On Products from Separate Media option in the Installation Mode dialog to include the SLMS add-on product. Then click Next.

  3. In the next dialog, click Add and select CD as the source type if you are installing from CD. If you are using a different installation source, such as NFS or HTTP, choose the appropriate source type. Click Next.

  4. If you are installing from a CD, insert the SLMS add-on product CD. If you are installing from network, provide the necessary source URL. Click Continue.

  5. Confirm the SLMS license agreement and click Next.

  6. During the installation, a SLMS Software Patterns Selection window appears. Make sure that the following installation patterns are selected: SLMS: Management Server and SLMS: Customer Service according to the server setup you need to deploy (see Section 2.1.5, “Supported Server Scenarios”.

    Figure 2.1. Package Installation

    Package Installation

  7. Click Next to confirm the pattern selection, then Accept to install the packages.

  8. After the package installation is finished, you need to configure the SLMS server with the WebYaST plug-in. For more information, see Chapter 3, Server Configuration with WebYaST.

2.6. Installation as an Add-On On Top of an Already Installed System

To install SLMS on top of an already installed base system, follow these steps:

  1. Start YaST and select Software+Add-On Products, or enter yast2 add-on in the command line as root. A window with the list of all already installed add-on products appears. To install SLMS, click Add.

  2. If you are installing SLMS from a CD, select CD as the source type. If you are installing from a different source, such as NFS or HTTP, choose the appropriate source type. Click Next.

  3. If you are installing from a CD, insert the SLMS add-on product CD. If you are installing from a different source, provide the necessary source. Click Continue.

  4. Confirm the SLMS license agreement and click Next.

  5. The SLMS Software Pattern Selection window appears. Make sure that SLMS: Management Server and SLMS: Customer Service installation patterns are checked according to the server setup you need to deploy (see Section 2.1.5, “Supported Server Scenarios”.

    Figure 2.2. Software Pattern Selection (text mode)

    Software Pattern Selection (text mode)

  6. Click Next to confirm the pattern selection, then Accept to install the packages.

    The SLMS product installation starts, showing the list of already installed packages and the overall installation progress.

  7. SLMS appears in the list of installed add-on products. Click Accept to install all SLMS packages.

  8. After the package installation is finished, you need to configure the SLMS server with the WebYaST module. For more information, see Chapter 3, Server Configuration with WebYaST.

2.7. Deploying SLMS as an Appliance

Apart from installing SLMS as an add-on, it is also possible to deploy it as an appliance. The main advantage is that you can skip the installation procedure and start with the SLMS configuration after booting the appliance. This deployment is mainly intended for virtualization purposes, which helps you run more virtual machines on one physical hardware. There are several virtualization solutions, such as Xen, KVM, VMware, or VirtualBox. For more information, see the related Web pages.

The SLMS appliance is shipped as an ISO 9660 image suitable for booting from (virtual) CD drive. To run the appliance, you need to connect this image in the virtual CD drive and set up and connect at least one hard drive in your virtual machine. All data on that drive will be destroyed and used by SLMS.

To run SLMS as an appliance, follow these steps:

  1. Create and configure a new virtual machine.

  2. Create at least one virtual hard drive and connect it to the virtual machine.

  3. Connect the SLMS appliance ISO image to the machine's virtual CD drive.

  4. Start the virtual machine. It must boot from the CD drive containing the SLMS appliance ISO image. If not, check the boot order in the virtual machine's BIOS setup.

  5. Select Install/Restore SLE-11-SP2-SLMS-1.3 from the boot menu and press Enter.

  6. Select Yes to destroy all the data on the connected hard drive (like /dev/sda). Installation of the appliance on the hard drive will start. After the appliance is installed, it will boot and start the required WebYaST services.

  7. Point your Web browser to https://<appliance_ip_address>:4984 to get to the WebYaST login screen appears. Now you are ready to configure your SLMS appliance. You can change the language of the WebYaST user interface - just click the language icon on the top right and choose from the list of supported languages.

    Figure 2.3. License Agreement and List of Languages

    License Agreement and List of Languages

[Important]Securing SLMS Deployment

The SLMS appliance uses default administrator credentials (see below), which creates a security hole for an intruder to log in and compromise the system. After you boot the appliance for the first time, run the following WebYaST configuration and change the administrator password as soon as possible. If you still need a more secure deployment, install SLMS as an add-on (see Section 2.6, “Installation as an Add-On On Top of an Already Installed System”).

Procedure 2.1. First-Boot SLMS Configuration

  1. In the Web browser, enter root as a username and linux as a password on the login screen.

  2. Agree with the license and click Next.

  3. On the Administrator Settings screen, enter and confirm new password for the root user. Optionally, you can specify an e-mail address to which the system mail will be forwarded.

    Figure 2.4. Administrator Settings Dialog

    Administrator Settings Dialog

    Click Next to proceed.

  4. On the Network screen, click configure next to the network interface you want to administer, and fill in the detailed information about the appliance host network settings, such as IP address, hostname, domain, or name servers. If you choose Automatic, these values will be obtained from a DHCP server.

    Figure 2.5. Network Dialog

    Network Dialog

    Click Next.

  5. On the Registration screen, enter your E-mail, name of the installed system, and registration codes for SLES. Click Details to enter more detailed information like the type of platform and processor on the server and your time zone.

    Figure 2.6. Registration Dialog

    Registration Dialog

    Click Next to register your product.

  6. If the registration was successful, you will be presented with the list of enabled package repositories, and the WebYaST Updates module will be run. It checks if your system packages are updated to their latest versions. If not, we recommend running the update on your system.

After you finish the setup, the WebYaST SLMS Configuration module is started. There you can set detailed information about the newly installed SLMS server. For more information, see Chapter 3, Server Configuration with WebYaST.

Chapter 3. Server Configuration with WebYaST

WebYaST is a Web-based remote console for controlling appliances based on SUSE® Linux Enterprise. See http://www.suse.com/documentation/webyast/ for more information on WebYaST. You can use the WebYaST SLMS plug-in for both initial and general SLMS Server configuration. The module enables and disables the SLMS service, sets registration options and database and mirroring credentials.

[Tip]Customizing WebYaST

You can modify the way WebYaST looks. This is useful mainly for the vendors who wish to re-paint the application to obey required corporate identity. More information on customizing the WebYaST appearance is available in the WebYaST Vendor Guide, http://www.suse.com/documentation/webyast/book_webyast_vendor/data/cha_webyast_brand_interf.html.

3.1. WebYaST and IPv6

There are several requirements you need to fulfill to successfully use IPv6 with SLMS and WebYaST. The general ones are mentioned in Section 2.1.4, “SLMS and IPv6”, while those related to WebYaST are listed in the following.

3.1.1. Web Server Configuration

WebYaST uses the nginx Web server to deliver pages with configuration forms to clients.

To be able to use WebYaST over an IPv6 connection, you must modify the nginx configuration files. Open /etc/webyast/nginx.conf in your favorite text editor and replace the line containing

listen 4984

with

listen [::]:4984

After you have modified the configuration file, restart the WebYaST service.

rcwebyast restart

Now you can access WebYaST via IPv6 URLs like http://[2001:db8::1]:4984/.

3.1.2. Hostname Entries in WebYaST

The format of IPv6 addresses differs from the IPv4 one - to access the WebYaST plug-in through IPv6, the internet address you need to enter in your Web browser will look similar to https://[2001:db8::1]:4984/.

To enter an IPv6 address into any hostname-related text entry in the WebYaST interface, such as registration host or database server host, you have to surround it with square brackets [2001:db8::1].

3.2. Starting WebYaST

  1. In order to configure your SLMS installation, the WebYaST start-up service rcwebyast must be running. In case you have deployed SLMS as an appliance, the service is already running. Otherwise, check its status with

    rcwebyast status

    If the service is not running, start it with

    rcwebyast start

    as root on the command line.

  2. If you plan to manage SLMS with WebYaST remotely, make sure to open TCP port 4984 in the Computer+WebYaST+Security and Users+Firewall dialog of the firewall. Allow the service called WebYaST UI.

  3. Run your favorite Web browser and point it to https://hostname:4984, where hostname is the hostname of the server running the WebYaST application (supply localhost if you are connecting locally).

  4. Log in as root.

    [Note]

    In the WebYaST control panel there are several icons representing different plug-ins. This manual only deals with the SLMS WebYaST plug-in. For more information on other WebYaST plug-ins, see the WebYaST User Guide at http://www.suse.com/documentation/webyast/.

    Figure 3.1. WebYaST Control Panel

    WebYaST Control Panel

  5. Click the SLMS Configuration icon in the WebYaST control panel. This opens the SLMS configuration plug-in. Depending on the server deployment scenario, you can continue with either Section 3.3, “All-In-One Server Setup” or Section 3.4, “Setup with Two Servers”.

3.3. All-In-One Server Setup

This scenario means that all SLMS services will be running on one physical machine. Therefore, you have to configure all the SLMS WebYaST plug-in options for the same machine.

[Warning]How to Limit the Network Access to SLMS Servers

To increase the security level of your SLMS Web administration server, only internal clients should be allowed to access it. The registration service must still be accessible over the Internet.

To limit the access, log in to the SLMS Web administration server with SSH, become root, and edit /etc/apache2/conf.d/slms_admin_interface.conf or /etc/apache2/conf.d/slms_external_interface.conf depending on whether you want to restrict the access to the Web administration or the external server. The related file must contain the following directives:

# Allow from all
Deny from all
Allow from 127.0.0.1/24
Allow from ::1
Allow from <localnet> 

Where <localnet> is the specification of your internal network space, such as slms.com or 192.168.2. Then restart the Apache service with rcapache2 restart.

To configure SLMS with the WebYaST plug-in, follow these steps:

  1. In the General settings tab, enable both the internal and the external service. If you want your customers to use the customer center (see Section 6.9, “Customer Center”), check Enable SLMS Customer Center as well.

  2. If the firewall on your system is enabled, check Open Port in Firewall to allow the network communication between the clients and the server.

  3. In the same tab, specify the external server hostname. This is the URL of the external server which holds the registration service if enabled. For the all-in-one setup, the external and internal servers are identical.

  4. Specify the vendor name. It is displayed in the SLMS application header.

    Figure 3.2. General Settings Tab of SLMS WebYaST Plug-in

    General Settings Tab of SLMS WebYaST Plug-in

  5. In the Database tab, specify the server database credentials. For more information, see Section 3.5, “Setting Database Credentials”.

  6. In the Updates tab, import an existing GPG signing key or create a new one. For more information, see Section 3.6, “Setting the GPG Key to Sign Update Repositories”.

  7. In the SUSE Studio tab set and test the SUSE Studio credentials. For more information, see Section 3.7, “Setting and Testing SUSE Studio Credentials”.

  8. In the SLMS Customer Center tab set the header that will be displayed on the Customer Center page. For more information, see Section 6.9, “Customer Center”.

  9. Click Finish to save the changes. All entered values will be saved in a relevant configuration files. See Chapter 9, Configuration Files for more information on SLMS configuration files.

    [Important]First Administrator Account for Web Interface

    If you have not created the first administrator account for the Web user interface yet, you will be asked to create it. Without this account, you cannot log in to the SLMS Web-based application. For more information, see Section 3.8, “Adding the First Administrator Account for the Web Interface”.

3.4. Setup with Two Servers

As mentioned in Chapter 2, Installation and Deployment, you can install (see Section 2.1.5, “Supported Server Scenarios”), set up and use SLMS on two servers instead of the all-in-one solution. In such case, one server is internal, and the other is external.

[Tip]Customer Center and Setup with Two Servers

To use the customer center (see Section 6.9, “Customer Center”) in a scenario with two servers, you need to manually modify the configuration file /etc/slms-secrets.conf on the external server, so that the rest_auth_site_key option has the same value as the internal one. Otherwise you will not be able to log in to the SLMS customer center.

For correct operation, a two-server scenario requires the following workflow:

  1. Configure the internal server as described in Section 3.4.1, “Internal Server”

  2. Configure the database engine to accept remote connections. See Section 3.9, “Configuring Remote PostgreSQL Server” for more information.

  3. Restart the SLMS service with rcslms restart.

  4. Configure the external server as described in Section 3.4.2, “External Server”.

[Important]Shared Storage Space

In a two-server setup, both the internal and the external server need to share storage space for the mirrored update packages. You can use NFS, rsync, or other tools that provide data sharing or synchronization.

3.4.1. Internal Server

The internal server includes the SLMS administration service, database, and tools for synchronization with SUSE Studio. To configure the internal server, follow these steps:

  1. In the General settings tab, enable the internal SLMS service and leave the external one unchecked.

  2. If the firewall on your system is enabled, check Open Port in Firewall to ensure network communication between the clients and the server.

  3. In the same tab, specify the external server hostname. This is the URL of the external server which holds the registration service if enabled.

  4. Specify the vendor name. It is displayed in the SLMS application header.

  5. In the Database tab, specify the server database credentials. For more information, see Section 3.5, “Setting Database Credentials” and Section 3.9, “Configuring Remote PostgreSQL Server”.

  6. In the Updates tab, import the GPG signing key or create a new one. For more information, see Section 3.6, “Setting the GPG Key to Sign Update Repositories”.

  7. In the SUSE Studio tab, set and test the SUSE Studio credentials. For more information, see Section 3.7, “Setting and Testing SUSE Studio Credentials”.

  8. Click Finish to save the changes.

3.4.2. External Server

The external server includes the customer center, client registration, and redirection services, as well as providing updates to the appliance. To configure the external server, follow these steps:

  1. In the General settings tab, uncheck the internal SLMS services and enable the external one. If you want your customers to use the customer center, check Enable SLMS Customer Center as well.

  2. If the firewall on your system is enabled, check Open Port in Firewall to ensure network communication between the clients and the server.

  3. In the Database tab, specify the server database credentials. For more information, see Section 3.5, “Setting Database Credentials”.

  4. In the SLMS Customer Center tab, set the header that will be displayed on the Customer Center page. For more information, see Section 6.9, “Customer Center”.

  5. Click Finish to save the changes.

  6. Make sure your SLMS server installation contains a valid SSL certificate and distribute its public part to the client appliance. Otherwise the appliance will not be able to register with the SLMS server. For more information, see Appendix A, SSL Certificates.

[Important]

After the SLMS configuration is saved and finished, you must manually change the database settings on the external server. For more information, see Section 3.9, “Configuring Remote PostgreSQL Server”.

3.5. Setting Database Credentials

When configuring a setup with two servers, the database server runs on the internal server. Therefore it is enough to enter localhost as the database server hostname on the internal server. However, you have to specify the full internal server hostname while configuring the database credentials on the external server.

[Note]

In principle, the database can run on a standalone server, different from the internal and external one. In this case you have to provide the standalone database server hostname and credentials when configuring the database on both internal and external SLMS server. Please note that this scenario is not supported.

To specify the server database credentials, follow these steps:

  1. Open your browser and point it to the WebYaST URL (see Section 3.2, “Starting WebYaST”). Log in as root and click the SLMS Configuration icon.

  2. In the Database tab, specify the hostname of the database server and its port.

  3. Specify the database server username and password. Confirm the password to make sure you entered it correctly.

  4. Click Save to save and apply your changes to the SLMS server configuration.

Figure 3.3. Database Tab of SLMS WebYaST Plug-in

Database Tab of SLMS WebYaST Plug-in

3.6. Setting the GPG Key to Sign Update Repositories

Update repositories must be signed with a GPG key before you can deliver the updates to customers. You can do this in the SLMS WebYaST plug-in. Follow these steps:i

Procedure 3.1. Setting the GPG Information with WebYaST

  1. Open your browser and point it to the WebYaST URL (see Section 3.2, “Starting WebYaST”). Log in as root and click the SLMS Configuration icon.

  2. Click the Updates tab and select the required GPG key from the GPG signing key dropdown list.

    If the list of GPG keys is empty, you can either create one or import it from a file.

    To create a new GPG key, click Create New Key and enter the following information:

    • Type of key

    • Length of the key

    • Expiration time of the key

    • Your real name and surname

    • Your e-mail address

    • Any comment on the key

    • Passphrase for the key

    Click Create Key to generate the key.

    To import an existing GPG key from a file on the file system, follow these steps:

    1. Click Import From File.

    2. In the Import GPG key from a file dialog, click Choose File and point to a GPG key on your file system.

    3. Click Import Key to import the key to SLMS.

3.7. Setting and Testing SUSE Studio Credentials

SLMS can work with appliances coming from multiple sources. One of them is SUSE Studio. If you plan to utilize such appliances, make sure that Connect to a SUSE Studio server is checked and follow the next procedure. If your appliances come from a different source—such as manual KIWI setup (see Section 5.1, “Disconnected Setup”)—leave the checkbox unchecked and skip this section.

To specify SUSE Studio credentials, follow these steps:

  1. If you do not have your SUSE Studio API key yet, visit the SUSE Studio home page at https://susestudio.com/ to obtain it. For more information, see Section 5.3.1, “How to Access SUSE Studio API”.

  2. Open your browser and point it to the WebYaST URL (see Section 3.2, “Starting WebYaST”). Log in as root and click the SLMS Configuration icon.

  3. In the SUSE Studio tab, specify your SUSE Studio user login and authentication key.

    If you want to use a different SUSE Studio URL than the default https://susestudio.com, change the protocol (http:// or https://) and enter your own SUSE Studio URL.

    [Important]SLMS and SUSE Studio Onsite

    If your SUSE Studio Onsite uses HTTPS protocol with a self-signed SSL certificate (see Section A.1, “Self-signed SSL Certificates”), you first need to import the SSL certificate into the SLMS internal server to ensure working communication between the two environments. Run the following commands as root on the internal server:

    1. Define the hostname and port number of the SUSE Studio Onsite that uses the self-signed SSL certificate, and the location where to store it:

      SERVER_NAME="studio.example.org"
      SERVER_PORT="443"
      CERT_FILE="/etc/ssl/certs/Studio_server_${SERVER_NAME}.pem"
    2. Run the download_certificate.sh helper script in the /usr/share/slms/internal/bin directory.

      cd /usr/share/slms/internal/bin
      ./download_certificate.sh ${CERT_FILE} ${SERVER_NAME} ${SERVER_PORT}
    3. Add the downloaded certificate to the list of known certificates.

      c_rehash | grep ${SERVER_NAME}
    4. Check that the certificate has been imported and works well.

      curl -vv https://${SERVER_NAME}:${SERVER_PORT}
    5. If the previous command results in an error, you can usually get some explanation with the following command:

      curl -vv --insecure https://${SERVER_NAME}:${SERVER_PORT}
  4. Click Test to check the credentials. If the test succeeds, a green message appears next to Test result: success. If the test fails, check the provided credentials and try again.

  5. Click Save to save and apply your changes to the SLMS server configuration.

    Figure 3.4. SUSE Studio Tab of SLMS WebYaST Plug-in

    SUSE Studio Tab of SLMS WebYaST Plug-in

3.8. Adding the First Administrator Account for the Web Interface

Before you can log in to the SLMS Web-based application (see Chapter 6, Web-based User Interface), you need to set up at least one administrator account. Setting up an administrator account can be accomplished with the SLMS WebYaST plug-in during SLMS configuration, or manually on the command line. For more information on how to add an administrator account with a command line tool, see Section 8.1, “slms commands”.

Procedure 3.2. Creating the First Administrator Account with WebYaST

If there is no administrator account for the Web interface after you clicked Save in WebYaST to save the changes, you will be asked to create one:

  1. Enter the administrator's real name, e-mail, and password. Type the password once more to ensure they are identical.

  2. Click Save to create the account.

[Important]

The first administrator has by default CRM API access disabled. If you need to enable it, you have to edit the user in the SLMS Web interface. For more information, see Section 6.2.3, “How to Change User Accounts”.

3.9. Configuring Remote PostgreSQL Server

In two-server scenario (or if the PostgreSQL database runs on a separate host), you need to manually configure the machine where the database runs (such as the internal server).

  1. In the /var/lib/pgsql/data/pg_hba.conf file, add this line

    host    slms        postgres    slms_server_ip/32    md5

    as the first not commented line of the file.

  2. In the /var/lib/pgsql/data/postgresql.conf file, change this line

    #listen_addresses = 'localhost'

    to

    listen_addresses = '*'
  3. Restart the database by entering rcslms restart in the command line.

  4. Open the PostgreSQL port in the firewall. The default value is 5432 and it is defined in /var/lib/pgsql/data/postgresql.conf.

[Tip]PostgreSQL Secure Communication

The security policy in your environment may require encrypted database communication in two-server setup. PostgreSQL, the database engine used in SLMS, offers data encryption at several levels. This topic, however, is beyond the scope of this manual. For more information, see the current PostgreSQL documentation

3.10. Configuring Proxies

Sometimes the SLMS server cannot directly access relevant remote services, such as Novell Customer Center, SMT or SUSE Studio. This typically happens if vendors or customers use HTTP proxies within their network environment as part of their security policy. This problem can be solved by setting proxy access on the SLMS server.

To set up a proxy on the server, follow these steps:

  1. Open the YaST Proxy Configuration module. Either enter yast2 proxy in the command line as root, or choose Network Services+Proxy from the YaST Control Center.

  2. Check Enable Proxy and fill in the URL for the protocols for which you need to use the proxy.

    [Note]Proxy Authentication Credentials

    The YaST Proxy Configuration module also contains text fields where you can enter the username and password needed for proxy authentication. Unfortunately, this does not work for the SLMS proxy authentication, because the YaST module automatically inserts entered credentials into /root/.curlrc, while the SLMS server runs as slms and therefore needs them in ~slms/.curlrc.

  3. Save your settings with Finish.

  4. If the proxy requires authentication, you need to change the .curlrc file in the slms user home directory. Add the line containing

    --proxy-user "username:password"

Figure 3.5. Proxy Configuration in YaST

Proxy Configuration in YaST

Chapter 4. Maintenance Workflow

It is very important to keep the appliance software up-to-date, especially if you sell SUSE Linux Enterprise 11 based appliances to your customers. Package updates keep the appliance secure and equipped with the latest software features available. SLMS helps you check which software package updates are available for your appliance, creates testing update repositories from these packages, and makes them available to your customers in the production environment.

4.1. Scenarios Overview

The main output of SLMS are updates for deployed appliances. Maintaining update repositories for your customers is a complex task. In order to describe which SLMS administration tasks we support and recommend, and which procedures you have to go through to create valid update repositories, we created supported scenarios. These scenarios, as well as scenarios we do not recommend, are described in the following section.

4.1.1. Supported Scenarios

First, you need to distribute the initial version of your appliance to your customers. Then you can deliver the following appliance modifications via update repositories:

  • You can provide version upgrades of the appliance packages, including official SUSE Linux Enterprise updates.

  • You can add new packages and repositories to the appliance. You can do this only by means of new dependencies in the packages that already exist on the published appliance. For more information, see Section 6.5, “Manually Handled Packages”.

  • You can downgrade an appliance's package to a specific version. Prior to this, you have to view the list of packages in SUSE Studio and mark the specific version of the relevant package. For more information on resolving the package in SLMS, see Section 6.5, “Manually Handled Packages”.

  • You can run custom scripts in a post-transaction hook (after the whole patch is installed). Scripts are executed by bash as root.

  • You can deploy additional files to the appliance that do not belong to any installed RPM packages. SLMS checks for changes in these overlay files and allows to deploy them to client machines without any special handling. For more information on overlay files, see Section 6.6, “Overlay Files”.

  • You can create high priority patches, that are installed before any other patches. It is normally used for updating the tooling affecting software installation, such as zypper, libzyp, rpm and so on.

4.1.2. Unsupported Scenarios

No other operations than the ones described formerly are allowed on appliance packages, and especially not the following one:

  • removing appliance packages

4.2. Testing Update Repository

4.2.1. Preliminary Tasks

The following conditions must be fulfilled before you start to create the environment for testing an update patch.

4.2.2. Testing Environment

Before you deliver package updates to your customers, create a testing update repository and test the new patch on your testing client machine. A recommended workflow for preparing a testing environment follows:

  1. Check that the appliance whose update patch you want to test has a current build.

  2. Create a custom testing update repository for the appliance if it does not exist yet. For more information, see Section 6.4.3, “How to Add a Custom Testing Repository”.

  3. For this testing update repository, create (but do not approve or publish) a new patch. For more information, see Section 6.4.1, “How to Create an Update Patch”.

  4. Create a testing customer. For more information, see Section 6.7.1, “How to Add New Customers”. Remember to click the Testing tab of the Your Customers page to view the list of your testing customers.

  5. Create a testing subscription for the testing user. Select the appliance whose patch you are just testing when creating the subscription. For more information, see Section 6.8.1, “How to Create New Subscriptions”. Remember to click the Testing tab of the Subscriptions page to view the list of your testing subscriptions.

  6. Edit the testing subscription you just created, and assign the testing update repository to it. For more information, see Section 6.8.6, “How to Assign a Special Update Repository to Subscriptions”.

  7. The subscriptions list shows a registration key of your testing subscription. Use this key to register the appliance with the SLMS server. For more information, see Section 6.8.1, “How to Create New Subscriptions”. Your appliance will receive updates from the testing update patch.

[Important]Data Backup

SLMS works with a lot of sensitive and important information. This information is stored in a database or in files on the server file system. You are strongly advised to back up your data on a regular schedule as it is not possible to restore all data. For more information, see Chapter 7, Data Backup and Database Maintenance.

4.3. How to Test a New Patch

In general, there are three areas you need to test:

  1. Practicability of the update

  2. Expected benefit

  3. Regressions

4.3.1. Preliminary Checks

Before you proceed through the different test areas, make sure the testing client machine is in a good and supported state and fulfills the following requirements:

  • All previously released updates have been applied. Some of them may require a reboot to become effective.

  • The RPM database is consistent. You can check that with the rpm -Va --nofiles command.

  • The components that are planned to be updated by the update are basically functional before the update.

4.3.2. Practicability of the Update

Maintenance updates are shipped via patch files. These are control files that indicate which RPM packages need to be upgraded and the reason for the upgrade (such as security, recommended, or optional).

There are several tools available to apply patch files. Depending on the kind of appliance, you can choose from several options:

  • Use the YaST module: Enter yast2 online_update on the command line as root, or start YaST Control Center and click Software+Online Update.

  • Use zypper. Run zypper install -t patch on the command line as root.

  • On GNOME desktops you can use the GNOME update applet /usr/bin/gpk-update-viewer.

  • On KDE desktops, you can use the KDE update applet /usr/bin/kupdateapplet.

To do a more specific testing, select only the required updates.

After you applied the test update, check whether all listed RPM packages were upgraded: Enter rpm -qa --last on the command line as root. Then check if the RPM database is still consistent: Enter rpm -Va --nofiles on the command line as root.

4.3.3. Expected Benefit

While the test update is running, you get details about the reason for the update. Updates fix defects and security holes, or implement new features.

Make sure that the update brings the expected benefit before passing it on to your customers.

[Note]SUSE Linux Enterprise 11 Based Updates

Updates shipped by SUSE for SUSE Linux Enterprise Server 11 and SUSE Linux Enterprise Desktop 11 already passed this kind of testing.

4.3.4. Regressions

Regression is the term for a software defect that was introduced by an update. When updating production systems take extra care to not break the required functionality of the appliance. Updates shipped by Novell for SUSE Linux Enterprise Server 11 and SUSE Linux Enterprise Desktop 11 already were tested, but you are advised to extend the testing with respect to your customer's special production environment.

Chapter 5. Appliances, Mirroring, and Creating Updates

In order to deliver appliances to the customers, it is essential to prepare update repositories. This will ensure that the customers' systems are secured and updated with the latest software updates.

This chapter is rather technical and describes a number of tasks, such as how to check whether an appliance is SLMS-ready, how to build appliances locally with KIWI, what happens during the appliance adaptation, how to administer SLMS in the command line, or how to deal with SSL certificates. Sections introduced here are not necessarily mutually related.

If you do not need more in-depth information about creating updates and want to use the SLMS Web administration, you can safely skip this chapter and go straight to Chapter 6, Web-based User Interface.

[Important]root privileges

SLMS commands can be run either by the user root or slms. You may find the slms user useful if you do not want to log in as root over the network. In that case you need to modify /etc/passwd and add a valid shell to slms. Then change its password to be able to access the account.

5.1. Disconnected Setup

There are SLMS environments where the customer prefers building appliances locally with KIWI rather than having to depend on SUSE Studio online services. Such setups offer more flexibility and control over KIWI options, which helps the customer to fine-tune the final build of an appliance. Many customers may also have a good knowledge of KIWI from previous experience and feel more comfortable when manually adjusting its configuration file. This section introduces information that will help you adjust the SLMS environment for building appliance builds locally.

[Tip]SLMS Add-On and KIWI Appliances

If your SLMS instance was installed or upgraded as an Add-On (see Chapter 2, Installation and Deployment) and you prefer deploying KIWI appliances, you may need to manually install the qemu RPM package, and one or more of the following

  • kiwi-desc-isoboot

  • kiwi-desc-vmxboot

  • kiwi-desc-netboot

  • kiwi-desc-oemboot

depending on the target build format you need.

Procedure 5.1. Building Appliances Locally with KIWI

  1. Prepare the KIWI configuration for the appliance you want to build locally. You either have it from the previous work on the appliance, or, if the appliance is accessible on SUSE Studio, you can download it from there (go to the Build tab and click Download appliance source).

  2. Copy and/or unpack the KIWI configuration tarball in the directory /var/lib/slms/kiwi on the SLMS server. Do the following for SUSE Studio export.

    cp SLES_11_SP2_JeOS.x86_64-3.kiwi_src.tar.gz /var/lib/slms/kiwi/
    cd /var/lib/slms/kiwi/
    tar xvzf SLES_11_SP2_JeOS.x86_64-3.kiwi_src.tar.gz

    A new directory tree is created under /var/lib/slms/kiwi/.

    ls -l /var/lib/slms/kiwi/
    drwxr-xr-x 4 root root 4096 Oct 3 12:56 SLES_11_SP2_JeOS.x86_64-3.kiwi_src
  3. Change the directory permissions recursively so that the Web-application can access it.

    chown -R slms:www SLES_11_SP2_JeOS.x86_64-3.kiwi_src
  4. Open the config.xml file related to your appliance in your favorite text editor. Check whether the paths to (update) software repositories for your appliance are correct and update them if not.

  5. Switch to SLMS Web application (see Chapter 6, Web-based User Interface for more information), go to the Appliances page, and refresh the list of available appliances with the Refresh Appliances button. Your newly added appliance should appear in the list of Available appliances.

  6. Go to the appliance's General Settings page by clicking the appliance's title, and choose its CPU architecture. This information is needed as SLMS needs to know for which architecture to build the appliance. Confirm with Set Architecture and refresh with Refresh. The appliance's status will change to Needs adaptation. Click Adapt and wait till the adaptation process finishes.

  7. Switch back to a terminal connected to the SLMS server, change to your appliance directory and build it with KIWI. In case of SUSE Studio, you can run the ./create_appliance.sh helper script to build the appliance. After the build is finished, you can normally manage the appliance with the SLMS Web application, the same as appliances created in SUSE Studio.

    [Important]

    Always rebuild the appliance after the adaptation step before delivering it to your customers.

5.1.1. Cloning KIWI Appliances

KIWI appliances are cloned simply by copying their directories/files. There are two important points to focus on:

  • Each time you clone an appliance, edit config.xml and remove the ID of the appliance. It must stay unique as it identifies the appliance and its deployments.

  • If the cloned appliance is already adapted, you need to manually undo the changes caused by adaptation: remove the slms_rpms directory, the overlay archive, and paths to its occurrences in config.xml.

5.2. Appliance Adaptation

SUSE Linux Enterprise-based appliances normally are registered with Novell Customer Center, and then receive standard updates. You need to change the appliance if you want it to receive updates from SLMS instead.

The adaptation differs depending on whether you create and configure the appliance in SUSE Studio and use it online from there, or whether you manually supply the KIWI configuration (see Section 5.1, “Disconnected Setup”) and let SLMS use it locally.

[Important]How to Find Out Whether an Appliance is SLMS-Ready

An appliance adapted by SLMS contains several modified files. To find out whether an appliance is SLMS-ready, check the /etc/suseRegister.conf file for the url_parameter. It should match your SLMS external server URL.

5.2.1. Appliance Adaptation in SUSE Studio

SUSE Studio is a Web environment where you can create, configure, and build your appliances. SUSE Studio can now adapt your appliance so that it receives updates from the SLMS server instead of the default update service.

  1. Log in to SUSE Studio, choose the appliance you need to adapt, and click its Update tab.

  2. Check Update appliance using SUSE Lifecycle Management Server.

  3. In the Vendor name and Server hostname fields, enter the same values you entered when configuring the SLMS server. Note that Server hostname has to match the External server setting (see Section 3.4.2, “External Server”). For more information, see Section 3.3, “All-In-One Server Setup” or Section 3.4.1, “Internal Server”, depending on the server scenario you use.

    [Tip]

    All of the information that you need to fill in SUSE Studio is available on the Studio Details page in the SLMS Web user interface. For more information, see Studio Details

  4. Enter the path to the SLMS server's HTTPS certificate (optional). This is useful if your server does not use a certificate signed by a well-known authority, such as in case of a self-signed certificate—it simplifies the communication between the appliance and the SLMS server. For more information on SSL certificates, see Appendix A, SSL Certificates.

    [Note]SSL Certificate and Setup with Two Servers

    For deployments with two servers, you need to supply the SSL certificate of the external server here.

  5. Choose one of the loaded GPG keys to sign the update patches (optional). If there are none in the list, click the GPG keys icon at the top and add a new key (string or from a file). If no GPG key is added here, then the appliance will not recognize the GPG key during the packages update process. As a result, the update process may fail as the appliance will require manual confirmation of the key, and the SLMS product file (see Section 5.2.3.3, “SLMS product file”) will not refer to a valid GPG key ID.

    [Tip]How to Export a GPG Key

    To export a GPG key on the SLMS server, you first need to find its ID. As root, run the following command:

    su slms -s /bin/sh -c 'gpg -k'

    and check the output for the ID (the second column). In case only one GPG key is present, you do not have to supply its gpg_key_id in the following command to export it:

    su slms -s /bin/sh -c 'gpg --export --armor gpg_key_id'

    It will print the public GPG key on the screen and you can copy and paste it as a string to the SUSE Studio text area.

5.2.2. Local Appliance Adaptation

If you prefer supplying your appliance's KIWI configuration locally on the SLMS server (see Section 5.1, “Disconnected Setup”), you need to adapt the appliance in the SLMS Web interface (see Section 6.3.2, “How to Modify Appliances to Receive Updates from SLMS” for more information).

5.2.3. What Happens during the Adaptation Process

No matter whether the adaptation process is handled by SUSE Studio or the SLMS server locally, the changes to the appliance are identical. The following sections describe in detail what happens to the appliance during the adaptation process.

5.2.3.1. Configuration Files Tarball

Configuration files that need to be updated or added to the appliance during its adaptation are stored in a tarball (compressed archive of files) and added to the appliance as an overlay file. The SLMS configuration plug-in tracks whether the current version of the tarball was created by the plug-in itself or by the user. If the user changes any SLMS configuration that influences the tarball's contents, the plug-in will either regenerate the tarball (if the current one was created by the plug-in itself), or display a warning about the tarball being out-of-sync. The tarball is called slms_overlay_files.tar.bz2 and contains the following files:

  • /etc/suseRegister.conf

  • /etc/products.d/slms.prod

  • /etc/ssl/serts/servercert.pem

Find more detailed information about these files in the following sections.

5.2.3.2. /etc/suseRegister.conf

The suseRegister package must be installed on the appliance prior to this change. A check is made and the package is installed if it is not found.

The file /etc/suseRegister.conf must contain the registration URL of the vendor's SLMS.

The line containing

url = https://secure-www.novell.com/center/regsvc

is replaced with

url = https://slms.vendordomain.top/center/regsvc

5.2.3.3. SLMS product file

The file /etc/products.d/slms.prod is added to the appliance. It causes SLMS to pass the appliance name to the SLMS server during registration, which in return provides the correct update channels.

5.2.3.4. SSL Certificates (Optional)

If you intend to use a self-signed SSL certificate on the SLMS server for communication over the HTTPS protocol, you need to add its public part to the appliance. Without a valid SSL connection, the suse_register command fails and the appliance will not be able to register itself against the SLMS server. The certificate resides in /etc/ssl/serts/servercert.pem on the server.

For more information on SSL certificates, see Appendix A, SSL Certificates.

5.2.3.5. SLMS Update Package

The initial version of the slms-update package is added to the appliance. Its update requires additional appliance specific update package that delivers dependent manually handled packages and overlay files. The package is identical for all appliances based on the same system, and is provided from a special directory.

5.2.3.6. Import GPG Key into the Appliance (Optional)

The vendors need to import their GPG key into the appliance in order to prevent the customer from being asked to trust the key. If a customer buys and uses software from a vendor, they are supposed to trust the vendor. If the GPG key is not specified, the initial packages and patches will be unsigned.

5.3. How to Mirror Update Repositories

To avoid huge per-machine downloads and to save network traffic, SLMS mirrors the needed update repositories locally. It does so either from SUSE Studio, or from repositories defined in the KIWI configuration, depending on the type of the appliance.

5.3.1. How to Access SUSE Studio API

In order to provide updates for your SUSE Studio appliances, SLMS has to communicate with SUSE Studio to get important information. Before SLMS can access it, you need to provide the appliance with your SUSE Studio user login and authentication key.

The following procedure shows how to get the credentials from SUSE Studio and save them to the SLMS configuration file.

  1. Open SUSE Studio https://susestudio.com in your Web browser and log in.

    [Note]SLMS and SUSE Studio Onsite

    SUSE Studio Onsite does not use the HTTPS protocol by default. If your SLMS server needs to communicate with SUSE Studio Onsite, you have to change the SUSE Studio URL accordingly.

  2. Point your Web browser to the SUSE Studio public API page

    https://susestudio.com/user/account#/api_hooks.

    Your Username and API key appear on the page.

  3. To re-generate the API key, click the Generate a new API key button.

  4. Fill the username and the API key into the SUSE Studio tab of the WebYaST SLMS plug-in, or append this information directly to the user and apikey options in the /etc/slms-secrets.conf file. For more information, see [SUSEStudio] Section of /etc/slms-secrets.conf.

Now SLMS will be able to communicate with the SUSE Studio API.

5.3.2. How Update Repositories Are Synchronized

The /etc/slms.d/novell.com-slms file contains a cron job that regularly checks for updates, and synchronizes all required data locally. It is configured to run on a daily basis so that the SLMS server has up-to-date information about appliance packages and update repositories.

The cron job runs the slms appliance --sync command which does the appliance data synchronization. See --sync for more information.

5.3.3. Offline Appliance Update

Sometimes - for security or other reasons - you may need to update an appliance which has no network access to the SLMS server. In that case you must generate an ISO image of the update repository on the SLMS, distribute it to the customer, and then apply the update patch on the client appliance.

To update the appliance offline, follow these steps:

  1. Open your favorite terminal application and change to the directory with the update repository you are going to apply:

    cd /path/to/the/update/repo

    You can find the path to the update repository on the Web interface page with details about the relevant update repository. The line starts with the Location: phrase. For more information, see Section 6.4.5, “How to View Update Repository Details”.

  2. Create an ISO image of the update repository on the SLMS server:

     
    mkisofs -A  "<appliance_name> Patch CD Version <version>" \
    -gid 0 -uid 0 -joliet-long -R -iso-level 4 \
    -o "<appliance_name>PatchCDVersion<version>.iso" .
    
  3. Deliver the created ISO image of the update repository to your customer.

  4. Load the ISO image on the client appliance with:

    yast2 wagon PatchCD

    Choose Local ISO Image as the source of the updates, and proceed with the upgrade.

Chapter 6. Web-based User Interface

Besides command-line scripts, SLMS installation includes a Web-based user interface. You can manage all important SLMS administration tasks while working in a friendly and intuitive environment.

6.1. General Information

This section describes how to start the Web-based application, and introduces a brief description of its interface.

6.1.1. Supported Web Browsers

Currently Mozilla Firefox 10 or greater, and Microsoft Internet Explorer 9 or greater are the supported Web browsers to run the SLMS Web-based interface.

6.1.2. How to Start the SLMS Web-based Application

You can access the SLMS administration user interface either by clicking the SLMS Web Interface icon in the WebYaST control panel, or by manually typing the server address into your browser's location bar. In the latter case, direct the browser to https://<internal_slms_server>/admin. Note that in the all-in-one server setup, both external and internal services run on the same machine.

You will be presented with a login screen. If you are the first administrator to access SLMS, enter the e-mail and password you entered while adding the first administrator account (see Section 3.8, “Adding the First Administrator Account for the Web Interface”). Otherwise enter the credentials you were given by the system administrator.

Click Log In and start administering SLMS.

6.1.3. General Description of the Interface

The application window is horizontally divided into two main parts: the navigation pane and the content pane.

Figure 6.1. SLMS Web User Interface

SLMS Web User Interface

6.1.3.1. Navigation Pane

The navigation pane is located in the upper part of the application window and contains two sets of controls. In its upper right corner, there are several links having a general purpose and are not related to managing appliances:

Log Out

Ends the current session and logs you out of the SLMS Web application. The login screen reappears and you need to enter your credentials to log in to the application again.

Help

Opens this SLMS manual.

Users

Opens the Current Users window, where you can manage SLMS user accounts. For more information, see Section 6.2, “Managing User Accounts”.

Link with your username

Opens the Changing Your Settings window, where you can change your password, time zone, and CRM API access information.

Studio Details

Opens a page with information that you should fill into a relevant form in SUSE Studio, such as the vendor name, external server hostname, download link to an SSL certificate, and GPG key and ID.

Figure 6.2. Studio Details

Studio Details

If problems arise during the SLMS operation, a small link on the right side of the navigation pane appears informing you about the number of system warnings. After you click on it, you can see detailed information about the problems found.

Figure 6.3. Warning Messages

Warning Messages

In the center lower part of the navigation pane, there are two tabs between which you can switch to change the content pane.

The Appliances tab lists all your KIWI and SUSE Studio appliances available under your user account. This is the default view after you log in to the application. From here you can access information about a specific appliance, change some of its settings, manage its updates and view a list of related registrations. For more information, see Section 6.3, “Managing Appliances”.

The Customers tab shows a list of your customers. You can filter the list of customers with the live search text entry above the list table header. By typing limiting characters, the list shows only the customers whose description matches your typed phrase. According to your user permissions, there are up to three tabs which divide the customers into groups of Active, Inactive, or Testing ones. You can manage customer accounts, and visit the Subscription screen listing all the subscriptions of a customer, and also related Registrations. For more information, see Section 6.7, “Managing Customer Accounts”.

6.1.3.2. Content Pane

The content pane displays lists of items related to which tab is currently active in the navigation pane. It can, for example, list your appliances, update repositories, valid customers or customer subscriptions.

These lists contain several control widgets for refreshing the view, adding new items, editing existing items as well as links to more specific content, such as a list of subscriptions related to one particular appliance.

6.2. Managing User Accounts

You need to have a user account to be able to log in to the SLMS Web-based application. The first administrator account is created during the initial configuration process. You can create subsequent user accounts after you log in to the application with the first account's credentials.

[Tip]CRM API - How to Automate SLMS Tasks

SLMS provides an API (Application Programming Interface) that allows to access SLMS functionality without using the Web interface. It is called CRM API (Customer Relationship Management, see http://en.wikipedia.org/wiki/Customer_relationship_management for more details), and you can use it to automate common SLMS tasks, such as managing user accounts or customer subscriptions. You can find more information how to use it at https://slms_host_name/admin/crm_api/index.html, where slms_host_name is the host name of your SLMS server installation.

6.2.1. User Roles

The process of creating and managing appliances, their update repositories, and related customer subscriptions can be an exhausting task for one administrator. That is why we introduced user roles. They encourage you to work in a team where users with different roles and permissions can focus on narrowed space in the whole process. It also improves the security level while managing the updates.

Different users of SLMS Web application can have different roles - one may do basic tasks on appliances, while the other is allowed to manage testing of the updates.

SLMS supports four basic user roles which provide the users with distinct permissions. A user can be assigned a combination of these roles, which helps you fine tune their access rights even more.

Depending on the user permissions, the application user interface may vary. Only those items, options, and screens, to which the current user is given permissions, are visible or accessible. The rest is hidden or disabled to the user.

SLMS offers the following user roles:

Administrator

This is the most powerful role which requires the highest responsibility of the user. All application screens and options are accessible, from managing appliances to publishing updates and administering customer subscription. Only a user with this role can add new user accounts.

Developer

This role is mainly intended for users who take care of appliances and update repositories. Developers typically create and manage appliances in SUSE Studio, synchronize the list of appliances from there in SLMS and do basic tasks on them, manage update repositories and testing subscriptions.

Quality Assurance

This role is mainly intended for users who are in charge of verifying, approving and publishing update repositories. Such users can manage update repositories and testing subscriptions, but can neither modify the state of appliances, nor affect the options on the Customers screen.

Support

Users with this role usually communicate with customers and manage their subscriptions. They can neither manage appliances, nor update repositories.

6.2.2. How to Add User Accounts

To add a new user account, follow these steps:

  1. Log in to the application as an administrator.

  2. Click Users in the top right of the navigation pane.

  3. Click Add New User.

  4. In the Adding New User dialog, enter the following information:

    • Fill the new user's name, e-mail address, password, and time zone. Retype the password to make sure it has no mistakes.

    • Assign relevant roles to the user by selecting them in the list. For more information, see Section 6.2.1, “User Roles”,

    • Select, if Customer relationship management (CRM) API should be enabled for the user. If so, you will be presented with access credentials which you can re-generate. For more information on CRM, see http://en.wikipedia.org/wiki/Customer_relationship_management.

    • Finally, enter your current administrator password.

    Figure 6.4. Adding New User Account

    Adding New User Account

  5. Click OK to create the account.

[Important]

You must assign at least one role to the newly created user, otherwise SLMS will refuse to add them.

6.2.3. How to Change User Accounts

To edit an existing user account, follow these steps:

  1. Log in as an administrator.

  2. Click Users in the top right of the navigation pane.

  3. From the list of user accounts, choose the one you need to change and click its name.

  4. Modify the item. If you need to change the account's password, type it twice to confirm it.

  5. Click OK to confirm the changes.

6.2.4. How to Delete User Accounts

To delete a user account, follow these steps:

  1. Log in as an administrator.

  2. Click Users in the top right of the navigation pane.

  3. From the list of user accounts, choose the one you want to delete and click the Delete link.

  4. In the pop-up dialog, enter your current administrator password and click Delete to confirm your intention. The account will be deleted from the application.

6.3. Managing Appliances

SLMS is a server that provides updates for your appliances. First, you need to configure your appliances. Supported are SUSE Studio appliances and local KIWI appliances (see Section 5.1, “Disconnected Setup”). After you refresh the list of appliances in SLMS, and optionally enable and adapt each appliance, you can generate their update repositories.

Click the Appliances tab to view the list of appliances available to SLMS. You can see the name, current status and available build targets of each listed appliance.

The list is divided into three parts:

Enabled Appliances

Lists all supported appliances which were enabled but not necessarily adapted yet (valid for KIWI appliances).

Available Appliances

Lists all KIWI appliances that are not yet enabled.

Unsupported Appliances

Lists all KIWI appliances that are detected as not supported by SLMS.

[Warning]Supported Appliances

Only appliances based on SUSE Linux Enterprise 11 SP 1, 11 SP2, and 11 SP3 are supported in SLMS. Appliances based on different distributions (like openSUSE) or different SUSE Linux Enterprise versions will not work with SLMS.

To refresh the list, click the Refresh Appliances button. This is useful if you added or deleted appliances. This operation may take a while.

[Note]

Besides refreshing the list and status of your appliances, the Refresh Appliances button also starts mirroring the appliances' update repositories. This can take a very long time, depending on the number of RPM packages which need to be downloaded.

An appliance can have the following status:

Not supported

The appliance exists but it is not supported by SLMS.

No build available

The appliance is supported by SLMS, but no image has been built yet.

Broken

This usually happens when a package selection conflict occurs, or when there is a broken build of the appliance.

Needs sync

The appliance is not properly synchronized. This can have several reasons - such as network problems during the synchronization or maintenance outage of SUSE Studio. To solve the problem, try to refresh the appliance.

Not enabled

The appliance exists but SLMS will not manage update repositories for it. You have to enable the appliance first. For more information, see Section 6.3.1, “How to Enable and Disable Appliances in SLMS”.

Needs adaptation

The appliance is already enabled but you have to modify it so it receives updates from SLMS. For more information, see Section 6.3.2, “How to Modify Appliances to Receive Updates from SLMS”.

New build is running

The appliance is in the process of being adapted.

Ready

The appliance is enabled and ready for SLMS. You can create update repositories for it.

6.3.1. How to Enable and Disable Appliances in SLMS

[Note]

Since SLMS 1.3, all SUSE Studio appliances are already enabled in SUSE Studio. Therefore the following information is valid for KIWI appliances only.

You have to enable an appliance before you can create its update repositories. To enable an appliance, follow these steps:

  1. Click the Appliances tab. A list of all your available appliances appears.

  2. Select the appliance you want to enable, and click its name.

  3. On the General Settings screen, select the matching appliance architecture—as SLMS supports only one architecture per appliance (32-bit or 64-bit x86 or System z)—and confirm with Set Architecture. The appliance will be automatically enabled after setting its architecture.

    If the appliance was already enabled or disabled and you want to change its state, then in the line starting with Enabled: either click Enable to enable it, or Disable to disable it.

    Figure 6.5. Appliance Details

    Appliance Details

[Warning]Disabled Appliances

If you disable a managed appliance, all its subscriptions and related nodes will not be able to receive maintenance updates anymore.

6.3.2. How to Modify Appliances to Receive Updates from SLMS

You have to modify (adapt) an appliance before it can receive updates from SLMS instead of standard updates. While SUSE Studio appliances are adapted in SUSE Studio, you need to adapt KIWI appliances manually in SLMS. The process is in detail described in Section 5.2, “Appliance Adaptation”.

[Note]

Since SLMS 1.3, all SUSE Studio appliances are already adapted in SUSE Studio. Therefore the following information is valid for KIWI appliances only.

[Note]

You can only adapt the appliances which have been already enabled. See Section 6.3.1, “How to Enable and Disable Appliances in SLMS” for more information on how to enable an appliance.

To adapt an appliance, follow these steps:

  1. Click the Appliances tab. A list of all your SUSE Studio appliances appears.

  2. Select the appliance you need to adapt and click its name.

  3. A General Settings screen with appliance details appears. Click the green Adapt button. The appliance will be adapted.

6.3.3. How to Change the Registration Key Status

Normally, an appliance needs a registration key to be allowed to get updates from SLMS. This is optional and you can enable or disable this feature.

To change the appliance registration key status, follow these steps:

  1. Click the Appliances tab. A list of all your SUSE Studio appliances appears.

  2. Select the appliance whose registration key you need to change and click its name.

  3. A General Settings screen with the appliance details appears. In the line starting with Registration Key: click the Change link to enable or disable the requirement.

  4. Confirm your decision with OK. The registration key requirement status will be changed.

6.4. Update Repositories

Update repositories contain package updates that together form patches. Your customers can easily update their installed systems through the update patches. Basically, there are two types of update repositories: production update repositories and testing update repositories. By default, one production and one testing update repository is available for each adapted appliance. These two repositories cannot be deleted.

production update repository

This update repository is created automatically and always present for each enabled appliance. It normally provides standard update patches. Each appliance can only have one production repository.

testing update repositories

There is always one testing update repository available, but you can create as many custom testing update repositories as you need. You can use them for testing purposes or for delivering temporary patches.

[Important]Appliances Without Update Repositories

If your appliance contains only pool repositories (repositories with no updated packages), you will not receive package updates through SLMS. If you want your appliance to be updated, add relevant update repository to the appliance and click Refresh Appliances on the Appliances screen. You do not need to rebuild the appliance.

6.4.1. How to Create an Update Patch

You have to generate an update patch in a testing update repository before you can deliver updates in the production one. This process is called staging. It helps you verify that the appliance works well after the new patch was applied.

To generate a testing update patch for an appliance, follow these steps:

  1. Click the Appliance tab to view a list of your appliances.

  2. Select the appliance whose update repository you want to manage and click the corresponding Updates link.

    The Online Update Repositories screen appears. It lists all existing update repositories together with additional information about each repository, such as its name, status and possibly date and time of the last update patch generation.

  3. Click the Testing Update Repository link. The Online Update Repositoriy screen appears with details about the update repository. Click the Create new patch.

  4. Enter the name of the current update, select its severity (recommended or security update), write a short summary and a description of its characteristics.

  5. If this patch should be installed before any other update patches, check High Priority. This is useful for updates of the tools that manage software installation. For more information, see software_management_packages .

    [Tip]

    If you create a new high priority patch that depends on a package with a normal priority—such as automake, it cannot be installed because its dependency is not found in the update repository. The solution here is to create a normal priority patch after the high priority one that includes all the required packages. Then the zypper patch command will see even the high priority patch, and will install it first with all its dependencies. The standard patches will be installed afterwards.

  6. If you need to run a specific script after the update patch is installed, paste it to the Script text area. The script is not validated, so it is up to you to test it, and ensure it works correctly.

    [Note]

    Because you cannot predict which version of the update patch the customers install, the script is saved from the current to the next patch version. This way you can apply old workarounds even though the customer installs newer version of the patch. Only if you are certain that all the client appliances are up-to-date, you can remove the old workarounds (if any). Please note that the same script will probably be run several times, make sure that it will always have the same result as being run only once.

    Click Create.

    A new testing update patch is then generated. After the patch generation finishes, the line with the repository status will read ... awaiting QA approval. Now you can test the new patch on a testing client machine. For more information, see Section 4.3, “How to Test a New Patch”.

    After the newly created testing patch was thoroughly tested, typically by Quality Assurance (QA) staff, move it to the production environment:

    Figure 6.6. Update Patch Awaiting QA Approval

    Update Patch Awaiting QA Approval

  7. Click Approve if the patch test results were satisfactory and you decided to move it into a production environment, or click Reject if you are not satisfied with the test results.

    The patch status now reads New patch approved by QA: Publish or Reject.

  8. Click Publish to move the update patch to a production update repository. It will now become available to your customers.

6.4.2. How to Remove an Update Patch

Sometimes you may find an update patch broken even after you published it to the clients in an update repository. For this purpose, we introduced a patch removal feature, that lets you remove an update patch from both testing and production repositories.

To remove an update patch, follow these steps:

  1. Click the Appliance tab to view a list of your appliances.

  2. Select the appliance whose update repository you want to remove, and click the corresponding Updates link.

    The Online Update Repositories screen appears. It lists all existing update repositories together with additional information about each repository, such as its name, status and possibly date and time of the last update patch generation.

  3. Click the title of the update repository whose update patch you want to remove. On the Online Update Repository page, find the update patch under the Released patches heading.

  4. Click the related red cross sign in the Remove Patch column, and confirm with OK. The update patch will be removed.

6.4.3. How to Add a Custom Testing Repository

Besides the two default update repositories, you can create several custom testing ones. You can use them for testing or other specific purposes. To add a custom testing repository, follow these steps:

  1. Click the Appliances tab, select the appliance and click Updates on the top.

    [Important]Updates Link Disabled

    If the Updates link is disabled for your appliance, the appliance is probably not enabled yet. You have to enable it to be able to create and manage its update repositories. For more information, see Section 6.3.1, “How to Enable and Disable Appliances in SLMS”.

  2. Click Create New Custom Update Repositoriy and enter its name.

  3. Click Create to create the new custom update repository.

6.4.4. How to Delete Custom Testing Repositories

To delete a custom testing repository, follow these steps:

  1. Click the Appliances tab, select the appliance and click Updates on the top.

  2. Select the custom testing repository you want to delete and click the corresponding Delete link.

  3. Confirm your decision with OK. The custom testing repository is now removed from SLMS.

6.4.5. How to View Update Repository Details

To view detailed information about an update repository - both production and testing - follow these steps:

  1. Click the Appliances tab, select the appliance, and click Updates on the top.

  2. Select the update repository whose details you want to view, and click its name.

    The screen shows detailed information about the repository and the related subscription and registration information.

    If there are updates available for this update repository, you can see their number in the line starting with Updates status. Clicking the small icon with a magnifier opens the Available Updates dialog window listing the name, version, and architecture for all available updates.

    In the lower part of the screen, there is a list of already published patches. Each row belongs to one published patch. Apart from the patch name and summary, you can see the number of packages that the corresponding patch includes.

    Figure 6.7. Update Repository Details

    Update Repository Details

6.5. Manually Handled Packages

Sometimes you may need to change the set of packages that appear in the update patch. For example, you may want to offer a package with a lower version number than the one suggested by the latest update patch, or you want to add a package or a repository to an already adapted appliance. There are two types of additional packages:

  • Packages which were added to the appliance after it was adapted.

  • Packages whose version you want to keep without being upgraded (sometimes called downgraded packages).

A list of additional packages appears after you click the Additional Packages button on the Appliance screen.

Figure 6.8. Additional Packages

Additional Packages

Each row belongs to one package. It shows the reason why this additional package is included, the package name, version, status, and action you can perform on the package. You can either Include the relevant package in the update patch, or Exclude it. You can also remove it from the SLMS database by clicking the Delete link.

You can perform different actions between individual update patches - you can exclude a package from one patch, and include the same in the next one.

[Important]

If you exclude a package from an update patch, then the clients that have not installed the package before will not be offered it for installation any more. However, the clients that have already installed the package before can—after the new patch is applied—remove the related dependency manually.

Procedure 6.1. The workflow to manage additional packages

  1. Create a testing update repository for the appliance to which the additional packages relate.

  2. On the Additional Packages page perform the required manual changes to the packages.

    If you include the added package, its latest version will appear in the next update patch. If you exclude it, its latest version will not be included.

    If you include the downgraded package, it will keep its old version and will not be upgraded. If you exclude it, it will be upgraded to the latest version.

  3. Click the Set Status of Packages button. Changes made to the additional packages are saved to the local database.

  4. After a client appliance asks for an update patch, all the performed changes will be part of the new patch.

    [Important]

    If you included a downgraded package in the update patch, there may arise a dependency problem after trying to update the client appliance with zypper up. The user has to solve the problem manually by choosing one of the presented solutions.

6.6. Overlay Files

After you add overlay files to your appliance (for example in SUSE Studio), and refresh the appliance information in SLMS, you can view a list of these files and either include them in the update patch, or ignore them:

  1. Click Appliances, select the appliance whose overlay files you need to manage, and click its title.

  2. Click Refresh if you recently added overlay files. Information about the appliance gets updated.

  3. Click Overlay Files to view the list of overlay files. Each row represents one file.

    Figure 6.9. Overlay Files

    Overlay Files

  4. In the Status column, check either Include or Exclude for each overlay file. By default, all newly detected files are included.

  5. After you either include or exclude every listed file, click the Set Status of Files button to save your decision to the database.

6.7. Managing Customer Accounts

For appliances that require registration keys, you need to add the customers in the SLMS database. Otherwise it is not possible to provide them with update patches.

[Tip]

In specific cases—such as deployment in internal networks—where your appliance does not require a registration key, you do not need to create any customers/subscriptions to be able to receive update patches.

Click the Customers tab to view the list of existing customers. All the customers are divided into three types: Active, Inactive, or Testing ones. You may or may not see all these three tabs, depending on your user role. The list shows each customer's unique id and a short description.

6.7.1. How to Add New Customers

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Click the Create new customer link.

  3. In the New Customer screen, fill the customer's unique ID, mirroring credentials (should be pre-filled), short description of the customer, the customer type (public or testing), and the customer status (active or inactive).

    In the Customer Center Access section, check if access to the customer center should be enabled, and enter relevant login credentials. For more information, see Section 6.9, “Customer Center”.

    [Important]Customer's Unique ID

    If you have a separate database of your customers, type their unique ID into the Unique ID field. It is a link between your existing customer database and the SLMS one which you can use later on.

  4. Click Create to create the new customer.

Figure 6.10. Customers Screen

Customers Screen

6.7.2. How to Modify Existing Customers

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose details you want to edit and click their unique ID link.

  3. In the Edit Customer screen change the relevant information.

  4. Click Update to save the changes.

6.8. Managing Subscriptions

Once you created customers (see Section 6.7, “Managing Customer Accounts”) for appliances that require registration keys, it is time to create related subscriptions.

Click the Customers tab, select the customer whose subscription you want to create, and click their unique ID link.

Click the Subscriptions link on the top. The Subscriptions page opens. It lists all existing subscriptions related to each appliance. Depending on your user role, the list is divided into Active, Inactive, or Testing subscriptions. The list also contains the following additional information:

  • Name of the appliance to which the subscription is related

  • Registration key for the customer

  • Start and end date of the subscription's validity period

  • Number of subscription nodes (the number of hosts using the same registration code)

Figure 6.11. Subscriptions Screen

Subscriptions Screen

[Important]How to Export Subscriptions

You can export the information about all your customer subscriptions. On the Your Customers page, click the Export Subscriptions button to download a CSV-formatted text file which contains the subscription information. However, only those subscriptions are exported which relate to appliances supported by SLMS, which are not deleted or disabled.

6.8.1. How to Create New Subscriptions

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to add and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Click the Create new subscription link.

  5. In the New Subscription screen, uncheck the Unlimited check-boxes if you need to enter particular information for the subscription's start and end date, and node count.

  6. From the Appliance drop-down list, choose the appliance for which you create the subscription.

  7. From the Type dropdown list, select if the subscription is either public or testing.

  8. Click Create to save the entered information and create the subscription.

    [Important]

    For each subscription, a unique registration key is generated. Use this key as part of the suse_register command on the appliance to register the appliance at the SLMS server. Use the following syntax:

    suse_register -a appliance-regcode=registration_key

6.8.2. How to Modify Existing Subscriptions

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to modify and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription you want to modify and click its Edit button.

  5. In the Edit Subscription screen, change the relevant information.

    Here, you can also change the registration code of the subscription. Just click Generate New and it gets regenerated automatically.

  6. Click Update to save the changes.

6.8.3. How to Disable and Re-enable Existing Subscriptions

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to disable and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription you want to disable and click its Edit button.

  5. In the line starting with Valid:, click the Invalidate link. The validity status changes to No.

    If the subscription is already disabled, you can enable it by clicking the Validate link.

  6. Click Update to save the changes.

6.8.4. How to Delete Existing Subscriptions

[Note]

You have to disable a subscription first before you can delete it. For more information, see Section 6.8.3, “How to Disable and Re-enable Existing Subscriptions” .

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to delete and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Click the Inactive tab to view the list of previously disabled subscriptions.

  5. Select the subscription you want to delete and click the Edit button.

  6. In the Edit Subscription screen, click Remove to delete the subscription. Confirm your decision with OK.

Figure 6.12. Subscription Properties

Subscription Properties

6.8.5. How to Generate a New Registration Key for Subscriptions

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription key you want to change and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription whose key you want to change and click its Edit button.

  5. In the line starting with Registration Code, click the Generate New link. The key will be regenerated.

  6. Click Update to save the changes.

6.8.6. How to Assign a Special Update Repository to Subscriptions

By default, SLMS provides a main update repository to a customer through a subscription. However, you can change this behavior by assigning one of the appliance's custom update repositories to the particular subscription:

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want modify and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription you need to assign the custom update repository to and click the corresponding Edit button.

  5. In the line starting with Update Repositories, click the Assign link.

  6. In the Assign Update Repositories pop-up window, select the update repository you want to provide for at least one target of the relevant appliance that this subscription applies to.

  7. Click OK to confirm your selection.

  8. Click Update to save the changes.

6.8.7. How to View Lists of Registrations and Node Statistics

When adding a new subscription (see Section 6.8.1, “How to Create New Subscriptions”), you can specify how many nodes will be using the subscription. Basically, the node count parameter defines how many hosts will be using the same registration.

To see a list of all nodes related to a particular subscription, follow these steps:

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to deal with and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription whose registrations you want to view and click the corresponding Registrations link.

    Figure 6.13. Registrations

    Registrations

The Registrations screen opens, listing all registrations of the relevant subscriptions. The list is organized in a table where each registration occupies one row. It shows the registered node ID number, the appliance to which this registration relates, and the provided update repository.

[Tip]How to Delete a Registration

There is no option to delete or disable a registered node through the SLMS Web Interface. You can, however, accomplish this with the slms node command line script. For more information, see Section 8.1.7, “slms node”.

To view brief download statistics of all or a particular node, click the chart picture in the top left of the screen. You will see a chart showing the downloaded kB for the selected node (or all nodes together if no particular node is specified) for the specified period of time in the past.

Figure 6.14. Node Download Statistics

Node Download Statistics

6.8.8. How to Assign a Custom Update Repository to Nodes

By default, a node is provided with the default update repository of the subscription it belongs to. You can change this behavior by assigning one of the related appliance's custom update repositories to a particular node:

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to deal with and click their unique ID link.

  3. Click the Subscriptions link on the top. The Subscriptions screen opens listing all active subscriptions related to the customer you selected before.

  4. Select the subscription whose registrations you want to view and click the corresponding Registrations link.

  5. Select the node to which you want to assign a custom update repository and click the Assign link in its Update Repository column.

  6. From the displayed drop-down list, select the update repository you want to provide for that node.

  7. Click OK to confirm your selection.

6.8.9. How to Delete Registrations

Once a registration becomes invalid or you need to free a slot in the subscriptions with a limited number of nodes reserved, you can delete the existing registration. Follow these steps:

  1. Click the Customers tab. The Customers screen appears listing all your existing customers.

  2. Select the customer whose subscription you want to deal with and click their unique ID link.

  3. Click Registrations in the upper menu. A list of all registrations related to the customer appears.

  4. Find the registration you want to delete and click the Delete link on the right.

  5. Click OK to confirm your choice.

6.9. Customer Center

SLMS customer center provides the customers with a read-only access to useful data related to their subscriptions. The customer center was introduced in SLMS version 1.2.

6.9.1. How to Access Customer Center

Before you can access the customer center, several conditions must be met:

Depending on the server scenario used (see Section 2.1.5, “Supported Server Scenarios”), point your browser to https://<external_slms_server>. Note that in the all-in-one server setup, both external and internal services run on the same machine.

You will be presented with a login screen. Here you need to enter your customer e-mail and password, the same which you entered when creating your customer account by the SLMS administrator (see Section 6.7.1, “How to Add New Customers”). Click Login.

6.9.2. Customer Center Interface

You can customize the SLMS customer center interface by changing graphical objects or by modifying cascading style sheets.

6.9.2.1. Replacing Graphics and Style Sheets

All graphic elements of the customer center interface such as images, icons, JavaScript files and cascading style sheets (CSS) are stored in the following public directory:

/usr/share/slms/external/public/

This public directory contains the vendor subdirectory, which is used as an alternative location for vendor-specific images, icons, and style sheets. You can replace any file in the public directory by adding a file with the same relative path into the vendor subdirectory. If a file exists in this alternative location, SLMS uses that file instead of its default equivalent.

Example 6.1. Using Custom CSS File

To override the SLMS stylesheets defined in /usr/share/slms/external/public/stylesheets/application-user.css, add a replacement file in /usr/share/slms/external/public/vendor/stylesheets/application-user.css and edit the relevant style sheet with the same name as the original one.


6.9.2.2. How to Add a Custom Terms and Conditions File

It is also possible to create a custom vendor-specific terms and conditions file and make it part of the SLMS customer center interface. Just create a static HTML file called terms.html and save it in the /usr/share/slms/external/public/vendor/ directory. Then reload the SLMS customer center. A new link appears in the header of the page referencing the HTML file you created.

6.9.3. Displaying Subscription Information

After being logged in, you can see the Available subscriptions screen with a list of all subscriptions related to your customer account. For each subscription the list shows the appliance name, number of used nodes, subscription validity, and the registration key.

Figure 6.15. List of Subscriptions in the Customer Center

List of Subscriptions in the Customer Center

Click the appliance name to see more detailed information about the appliance together with the list of all nodes registered with it. The nodes are sorted in a table, each row belongs to one node. For each node, the ID, date of the last update download, overall update download size, and the total number of downloaded files are displayed.

Figure 6.16. List of Nodes in Customer Center

List of Nodes in Customer Center

Click Details to view the activity graph of the related node showing the node's download activity for the last 90 days.

To view detailed customer information such as mirroring credentials, click your login name link in the top right.

To log out of the customer center, click Log Out.

Chapter 7. Data Backup and Database Maintenance

SLMS is an application whose life cycle is supposed to be long term. SLMS works with important and sensitive data, and most of it cannot be recovered in case of a system crash or hard disk failure.

Therefore you are strongly advised to make frequent and regular backups of SLMS data to prevent the system from loss of crucial information.

7.1. Database and Storage

SLMS can store its files, mirrored packages and database data either locally, or remotely for clustering purposes. SLMS can share the remote storage space with other SLMS instances.

7.1.1. Database

SLMS uses the PostgreSQL database engine. It uses a database interface library to access the database in read-write mode.

Each SLMS instance uses one database.

7.1.2. Storage

SLMS does not require any special access to storage. The storage space has to be mounted locally with read-write access.

7.2. SLMS Data

SLMS uses the following types of data:

PostgreSQL database data

By default this is /var/lib/pgsql.

locally mirrored repositories

See the mirrorto option in the [Mirroring] Section of /etc/slms.conf. The default directory is /srv/www/slms/mirror.

generated SLMS repositories

See the basedir option in the [Updates] Section of /etc/slms.conf. The default file is /srv/www/slms/updates.

registration and other data

See the slms_storage option in the [SLMS] Section of /etc/slms.conf. The default file is /var/lib/slms/storage/.

SLMS configuration files

The default files are /etc/slms.conf /etc/slms-secrets.conf, /etc/slms-cc.conf, and the files under /etc/slms.d/.

Apache Web server configuration files

/etc/apache2/conf.d/slms_* and /etc/apache2/vhosts.d/slms_* files together with the slms symbolic link in the /etc/apache2/vhosts.d/ directory. This link points to the type of your SLMS scenario.

GPG keys

Files under /var/lib/slms/.gnupg.

log files

Log files are stored in the following directories:

/var/log/slms

Logs of the Rails application, the SLMS migrations, and the communication with SUSE Studio.

/var/lib/slms/storage/jobs

Logs from the delayed jobs (also displayed on the screen) but with additional debug output.

/var/lib/pgsql/data/pg_log

Logs from PostgreSQL. Useful if something goes wrong with the database.

Apache Web server SSL certificate and key files defined in /etc/apache2/vhosts.d/slms_ssl_options.include
  • The default file for the SSL certificate is /etc/slms.d/certs/servercert.pem

  • The default file for the key files is /etc/slms.d/certs/serverkey.pem

7.3. Database Maintenance

SLMS uses PostgreSQL as a database engine. When records are deleted from the database, PostgreSQL never physically removes the data from its tables. The data remain present until you clean the tables manually. This operation is called vacuuming. You are advised to clean up the database periodically, particularly on frequently updated tables.

To simplify the database cleaning, we introduced the slms purge command. It not only handles vacuuming of the SLMS database, but it helps you remove old, unused or invalid database entries, such as records about appliances, subscriptions, update repositories, nodes, or registration keys as well. For more information, see Section 8.1.8, “slms purge”.

Chapter 8. Command Line Scripts

This chapter describes important commands and scripts for managing SLMS administration tasks.

[Important]root privileges

Unlike the Web user interface application, command line scripts do not respect user roles (see Section 6.2.1, “User Roles”). SLMS commands can be run either by the user root or slms. You may find the slms user useful if you do not want to log in as root over the network. In that case you need to modify /etc/passwd and add a valid shell to slms. Then change its password to be able to access the account.

There are several types of SLMS commands:

8.1. slms commands

8.1.1. slms

The slms command usually takes one of its subcommands as an argument. When used without a subcommand, it prints the list of its subcommands. All subcommands accept --help (or -h), which prints the list of available subcommands/options, and --verbose (or -v), which provides the user with more information about the changes that are being executed. A number of subcommands produce results as a tabular list. These accept the --csv (or -z) option, which tells them to export the output data into CSV format.

[Tip]CSV Output

--csv outputs the structured data to the standard output (usually on the screen) by default. To save it to a file, redirect the output with a > sign, for example:

slms appliance --overlays --name appliance1 --csv > appliance1_overlays.csv

Moreover, do not use --verbose together with --csv as it produces additional output and makes the exported data unusable.

8.1.2. slms help

The slms help subcommand command describes all valid options of the related slms subcommand.

[Tip]Omitting the help subcommand

If you do not specify any subcommand's switch—such as slms appliance—the behavior is same as in the case of slms help appliance.

8.1.3. slms admin-ui-user

This command is an equivalent to slms-admin-ui-user, see Section 8.2, “slms-admin-ui-user”.

8.1.4. slms appliance

Usage:

slms appliance options

Lists and manages appliances. The command understands the following options:

--adapt --id appliance_id or --adapt --name appliance_name

Adapts KIWI appliances for use with SLMS.

-l or --list

Lists all appliances if no other option is provided. If the user provides an appliance ID with --id or appliance name with --name, the query will return only the targeted appliance.

To list all available appliances, enter the following:

tux@venus:~> slms appliance --list
----+-------------------+---------------+------------------+-----------
 ID | Name              | Studio ID/kiwi| Status           | Base sys.   
----+-------------------+---------------+------------------+-----------
 1  | SLES11SP1-minimal | 652450        | Ready            | SLES11_SP1
 2  | LAMP-server       | 650851        | Needs adaptation | SLES11_SP2
 3  | SLES11SP2-X       | 650947        | Ready            | SLES11_SP2
----+-------------------+---------------+------------------+-----------
-r or --repos

Lists update repositories for an appliance. Options --id or --name are mandatory.

To list the update repositories of the appliance with ID 6, enter the following:

tux@venus:~> slms appliance --id 6 --repos
----+-----------------------------+---------------+--------------------
 ID | Name                        | Patch Version | Updated At             
----+-----------------------------+---------------+--------------------
 10 | Production Update Reposit.. | 0             | 2013-01-02 09:22:30
 11 | Main Testing Repository     | 0             | 2013-01-02 09:22:30 
----+-----------------------------+---------------+--------------------
-n or --name appliance_name

Provides appliance name for other subcommands.

-i or --id appliance_id

Provides appliance ID for other subcommands.

-e or --set-arch architecture

Sets the CPU architecture for a local KIWI appliance and enables it. Valid options are x86_64, i586, and s390x.

slms appliance --set-arch x86_64 --name jeos1_appliance
-o or --overlays

Shows the overlay files for an appliance.

slms appliance --overlays --id 44
-d or --additional-dependencies

Shows the list of possible additional dependencies such as version freeze or addition of a new package.

slms appliance --additional-dependencies --name lamp_appliance
-x or --exclude-dependency dependency_id

Excludes a dependency from newly created patches.

slms appliance --exclude-dependency --name lamp_appliance
-c or --include-dependency dependency_id

Includes a dependency into newly created patches.

slms appliance --include-dependency --name lamp_appliance
--sync

Synchronizes all data needed for generating appliance update repositories with the recent state.

slms appliance --sync
slms appliance --sync ALL

These previous two commands are identical and will synchronize all appliances available in SLMS.

slms appliance --sync --name magic_appliance

The appliance named magic_appliance will be synchronized.

8.1.5. slms customer

Usage:

slms customer options

Lists and modifies customer information. The command understands the following options:

-l or --list customer_name

Prints detailed information about the specified customer. Note that customer_name does not have to be the whole customer name string, but rather a string contained in the customer name.

-c or --create options

Creates a new customer. You need to provide details about the new customer through additional options (see below for details): --status, --description, --username, --password, --name, or --owner-email.

-m or --modify options

Changes the customer's attributes. You need to provide details about the change through additional options (see below for details): --status, --description, --username, --password, or --rename.

-n or --name customer_name

It either supplies a customer name when creating a new customer (see --create), or you can use it when specifying an existing customer together with options --delete, --modify, or --mirror-details.

-s or --status customer_status

Specifies the customer status when creating or modifying the customer. Allowed values are active or inactive.

-d or --delete

Deletes a customer account specified by either --name or --id.

-r or --rename new_customer_name

Changes the customer's name. Use together with --modify.

-o or --mirror-details

Shows information about mirroring credentials related to the customer specified by --id or --name.

-s or --description description

Changes the description of the customer. Use together with --create or --modify.

-u or --username username

Changes the customer's username. Use together with --create or --modify.

-p or --password password

Changes the customer's password. Use together with --create or --modify.

8.1.6. slms customer contact

Usage:

slms customer contact options

Changes the customer's contact information. The command understands the following options:

-l or --list

Shows the contact of a customer specified with --id or --name.

-id or --customer-id customer_id

Specifies the customer ID. Use with --list, --remove, or --modify.

-n or --customer-name customer_name

Specifies the customer name. Use with --list, --remove, or --modify.

-a or --add

Creates a new contact for a customer (if there is none yet). You need to specify additional contact information with --name, --email, or --password.

-r or --remove

Removes the contact specified with --id or --customer-name.

-m or --modify

Modifies the contact attributes specified with --name, --password, or --email.

-c or --name contact_name

Provides a name for the customer's contact. Use together with --add and --modify.

-p or --passwordpassword

Provides a password for the customer's contact. Use together with --add and --modify.

-e or --emailemail

Provides an e-mail for the customer's contact. Use together with --add and --modify.

8.1.7. slms node

Usage:

slms node options

Lists and manages subscription nodes registered with SLMS. It is useful if you want to do command line filtering based on data. The command understands the following options:

-r node_id or --remove node_id

Deletes a node as identified by its ID number.

-l or --list

Lists all nodes.

tux@venus:~> slms node --list
-------+-----------+-------------+---------+------- --+-------------
NodeID | GUID      | Secret      | Appl ID | Subsc ID | Updt RepoID 
-------+-----------+-------------+---------+------- --+-------------
 1     | lx93i84.. | die94jdgn.. | 1       | 1        | 1          
 2     | die9d9w.. | 12989d84j.. | 2       |          | 2          
-------+-----------+-------------+---------+------- --+-------------
-d or --details node_id

Shows detailed information about the node specified by its ID.

-s or --assign-repo repository_id

Assigns an update repository to one or more nodes specified with --node.

-n or --node node_id

Specifies one or more node IDs for use with other related options. When providing multiple IDs, separate them with commas and avoid spaces between them.

-a or --active YYYY-MM-DD

Filters nodes which are active since the given date. Use together with --list.

-i or --inactive YYYY-MM-DD

Filters nodes which are inactive since the given date. Use together with --list.

8.1.8. slms purge

Usage:

slms purge options

Cleans the SLMS database by removing invalid or unneeded data. The command understands the following options:

--date YYYY-MM-DD

Specifies date for the --jobs and --nodes options.

--appliances

Removes deleted appliances which have no subscriptions assigned. When used together with --force, it removes also appliances that have subscriptions assigned, including the subscriptions.

--subscriptions

Removes subscriptions which are inactive. Only subscriptions older than the date specified with --date will be removed.

--vacuum fast or full

Reclaims the disk space used by deleted database records. full may reclaim more space, but takes much longer and exclusively locks the database table. fast is the default.

--repositories

Removes update repositories which are not used anymore.

--nodes

Removes nodes that have not contacted the server for a period of time. The nodes have to be older than the date specified with the mandatory --date option.

--jobs

Removes jobs which are marked as running. Use together with --date to only remove jobs older than a specified date.

-f or --force

Use together with --appliances to remove existing associated subscriptions.

--rpms

Removes all unused RPM packages from the SLMS repository and database. Unused means packages not included in any of the current appliances or appliance patches. Use if you need to reclaim free disk space.

8.1.9. slms repos

Usage:

slms repos options

Lists and manages mirrored update repositories. The command understands the following options:

-l or --list

Lists all (even unused) repositories.

-u or --list-used

Lists used repositories only.

-n or --list-unused

Lists unused repositories only.

-r or --remove-unused

Removes all unused repositories.

8.1.10. slms subscription

Usage:

slms subscription options

Lists and manages customer subscriptions.

-l or --list

Lists all subscriptions.

-c or --create

Creates a new subscription. The attributes for the new subscription must be provided with other options such as --start-date, --end-date, --nodecount, --appliance-name, --owner, --customer-name or --customer-id, and --active or --inactive.

-m or --modify subscr_id

Changes an existing subscription specified by subscr_id. The subscription attributes can be changed by providing --start-date, --end-date, --nodecount, --active or --inactive.

-i or --inactive

Sets the inactive flag for a subscription. Use together with --create, --modify and --list.

-a or --active

Sets the active flag for a subscription. Use together with --create, --modify and --list.

-s or --start-date YYYY-MM-DD

Sets the start date of the subscription's validity. Use 'None' if you do not want to specify the start date. Use together with --create, --modify and --list.

-e or --end-date YYYY-MM-DD

Sets the end date of the subscription's validity. Use 'None' if you do not want to specify the end date. Use together with --create, --modify and --list.

-n or --nodecount max_nodes

Sets the maximum number of nodes for the subscription. Use together with --create, --modify and --list.

-g or --regenerate_reg_key

Regenerates a registration key. Use together with --modify. The option re-initializes an update repository while copying only RPM packages that appear in any patch, and regenerates the repository metadata. It does not generate any patch itself, so even a rejected patch is not re-created after the option is used. It helps mainly when troubleshooting, and is not needed in a common workflow.

-o or --assign-repo repo_id

Assigns an update repository specified with repo_id to a subscription specified with --subscription_id.

-f or --subscription_id subscr_id

Use to specify the subscription ID together with --list, --remove-repo, or --assign-repo.

-u or --customer-name cust_name

Use to specify a unique customer name together with --list or --create.

-d or --customer-id cust_id

Use to specify the existing customer ID together with --list or --create.

-w or --owner user_email

Supplies the e-mail address when creating a new subscription with --create. Sets the subscription type to testing if provided.

-p or --appliance-name appliance_name

Supplies the appliance name when creating a new subscription with --create.

8.1.11. slms update

Usage:

slms update options

Multi-purpose command to manipulate update repositories. The command understands the following options:

-l or --list

Lists update repositories for an appliance specified with --appliance-id or --appliance-name.

-c or --create-repo repo_name

Creates a new update repository for the appliance specified with --appliance-id or --appliance-name.

-r or --rename new_repo_name

Renames the update repository specified with --repo-id.

-i or repo-id repo_id

Specifies an update repository ID for use with other options such as --rename.

-a or --appliance-id

Specifies an appliance ID for use with other options such as --list.

-p or --create-patch repo_id

Creates a new update patch. Mandatory options are --appliance-name or --appliance-id, and --severity. You can give a patch a specific name with --patch-name ('update' by default). Other available options are --summary, --description, --priority-patch, and --script.

-n or --patch-name patch_name

Gives the patch a name. Use with --create-patch.

-s or --summary patch_summary

Specifies a text summary for a patch. Use with --create-patch.

-S or --script-path file_path

Specifies the path to a file containing a post-update script. Use with --create-patch.

-t or --description description

Specifies a text description for a patch. Use with --create-patch.

-P or --priority-patch

If provided, it will mark the patch as a high priority patch containing only software stack updates. Use with --create-patch.

-y or --severity severity

Specifies a patch severity. Valid options are recommended and security. Use with --create-patch.

-d or --delete repo_id

Deletes an existing update repository.

-u or --publish repo_id

Publishes the content of the testing repository identified by repo_id to the production environment.

-j or --reject repo_id

Rejects the testing repository—it will not be published.

-o or --approve repo_id

Approves the testing repository identified by repo_id. The repository can now be published to customers.

-e or --regenerate repo_id

Regenerates the testing repository.

8.2. slms-admin-ui-user

After the SLMS installation is complete, you need to add the first administrator account you normally use to log in to the Web-based SLMS application. Without this account, you cannot access the Web-based application. The slms-admin-ui-user command helps you create this first administrator account. The command is not limited to adding only the first administrator account—you can create as many administrator accounts as you need.

Usage:

slms-admin-ui-user options

This command understands the following options:

-h or --help

Prints brief information about the subcommand usage.

-l or --list

Lists existing administrator accounts.

-c or --create

Creates one or more administrator accounts.

-o or --create-one

Creates one administrator account and exits.

-f filename or --file filename

Imports a new administrator account from a YAML-formatted file.

To add one or more administrator accounts, enter the following:

tux@venus:~> slms-admin-ui-user -c
 Creating new user...
 Name: Example Administrator
 Email: exampleuser@example.com
 Password: *******
 Repeat Password: *******

 User Example Administrator successfully added.
 Add another user? [y/n]:

8.3. migrate_postgresql_database

The migrate_postgresql_database helps with upgrade of PostgreSQL database from version 8 to 9. You usually need to run it only once per SLMS site after the upgrade of SLMS itself (see Section 2.2, “Upgrade from SLMS 1.2”). Both—the old and the new— versions of PostgreSQL servers must be already installed in the system.

Usage:

migrate_postgresql_database options

The command understands the following options:

-h or --help

Prints useful information on the command's usage.

--file dump_file

Specifies the path to a temporary dump file (/var/lib/slms/slms_db_export.sql.gz by default). If a file of the identical name exists, it is renamed before the new dump is created (time stamp suffix is added). Use together with --dump-only and --restore-only options.

-k or --keep-dump

Leaves the dump of the old-format database on the file system. By default, the dump file is removed after successful upgrade.

-b or --keep-db

Leaves the old-format subdirectory tree on the file system. By default the old database files are removed after successful upgrade.

-c or --clear

Adds the clear commands to the database dump to clear the old data when restoring a database (not used by default, a new empty database is created at restore time, so this should not be needed).

-f or --force

Forces the database migration even if the latest PostgreSQL database is already running.

-d or --dump-only

Only performs a dump of the current database to a file specified with --file.

-r or --restore-only

Only restores the database from a dump file (created with --dump-only) specified with --file.

8.4. rcslms

The rcslms command is used for starting, stopping, and restarting SLMS service, and for checking its status.

Usage:

rcslms subcommand

The command understands the following subcommands:

start

Starts the SLMS service.

stop

Stops the SLMS service and unloads SLMS Apache plug-ins.

status

Checks if the SLMS service is running.

restart

Stops the SLMS service and starts it again.

try-restart

Restarts the SLMS service if it is running.

help

Prints brief usage information.

To restart the SLMS service, enter the following in the command line:

tux@venus:~> rcslms restart

Chapter 9. Configuration Files

This chapter describes SLMS configuration files, their valid options, and possible values.

SLMS uses the following configuration files: /etc/slms.conf, /etc/slms-secrets.conf, and /etc/slms-cc.conf. While /etc/slms.conf contains options affecting general server behavior, /etc/slms-secrets.conf stores more sensitive personal and network data, and /etc/slms-cc.conf includes information related to the SLMS customer center.

SLMS configuration files are stored in an INI file format. They are divided into several logical sections. Each section begins with a label enclosed in square brackets, and ends either before the next section starts, or at the end of the file. The option name is always followed by = and the value. Lines starting with a semicolon usually are comments. They are ignored and not processed.

9.1. /etc/slms.conf

/etc/slms.conf contains general SLMS configuration information, such as where the SSL certificate is stored, where SLMS mirrors update repositories, or what the path to the log file is.

9.1.1. [SUSEStudio] Section of /etc/slms.conf

sslcertpath

Specifies the directory for SSL certificates.

sslcertpath = /etc/ssl/certs

timeout

Specifies the timeout in seconds until the http(s) connection dies as unresponding. Increase the value if there is a huge delay in communication with SUSE Studio, and timeouts occur often.

timeout = 45

9.1.2. [Mirroring] Section of /etc/slms.conf

mirrorto

Specifies the base local directory where update repositories are mirrored.

mirrorto = /srv/www/slms/mirror/

ncc_url

Specifies the URL to access the NCC (Novell Customer Center) XML API.

ncc_url = https://secure-www.novell.com/center/regsvc/

9.1.3. [Updates] Section of /etc/slms.conf

basedir

Specifies the base local parent directory under which the appliance update repositories are created.

basedir = /srv/www/slms/updates/

software_management_packages

Comma separated list of regular expressions that match the packages affecting the software management. Only the listed packages are included into high priority patches, which are applied before other patches.

software_management_packages = rpm,libzypp,zypper,.*satsolver.*,PackageKit.*,packagekit.*,kde4-kupdateapplet.*,.*curl.*,yast2-packager,yast2-pkg-bindings,yast2-wagon,rubygem-webyast-software

9.1.4. [SLMS] Section of /etc/slms.conf

external_server_url

The URL address of external SLMS server used in appliances. In one-server scenario it is the address of the SLMS server.

external_server_url = https://dhcp-slms.example.org

slms_storage

Specifies the directory where SLMS stores data that does not belong to the database.

slms_storage = /var/lib/slms/storage/

vendor

Specifies the vendor name. It is mainly used to display the vendor of the appliance.

vendor = Example Vendor

logfile_size_limit

Specifies the maximum size of the log file (in MB) before it is rotated.

logfile_size_limit = 100

logfile_keep

Specifies the maximum number of rotated log files that will be kept in the directory specified by logfile_path. If the number of log files is exceeded, the oldest rotated log files are deleted automatically.

logfile_keep = 100

loglevel

Specifies how much runtime information the SLMS server outputs into the log file specified in logfile_path. Possible values are debug, info, warn, error, or fatal. debug is the most verbose option, while fatal outputs least information.

loglevel = info

apache_cache_dir

Specifies the directory where Apache Web-server data are stored.

apache_cache_dir = /var/lib/slms/cache

apache_cache_time

Specifies the time in minutes for which the Apache Web-server cached data will be stored. 0 disables the caching completely.

apache_cache_time = 10

enable_statistics

Specifies whether to enable or disable statistics for nodes. 1 enables the statistics, while 0 disables them.

enable_statistics = 1

crm_api_delay

Specifies the delay for CRM API that applies to both successful and unsuccessful authorization. If the administrator knows what they are doing, they can lower the delay, or turn it completely off by changing this option to 0. We also recommend additional limiting the access to the CRM API server (internal), for example by the firewall setting.

crm_api_delay = 2

duration_session_valid

Specifies the duration (in hours) for which the Web application session is valid. After that time elapses, the user is automatically logged out.

duration_session_valid = 24

duration_of_inactivity

Specifies the duration (in minutes) after which the user is automatically logged out if inactive.

duration_of_inactivity = 10

progress_refresh_delay

Specifies the time interval in seconds after which the progress indicator is refreshed in the Web user interface.

progress_refresh_delay = 4

delayed_job_workers

Specifies how many delayed jobs workers will be started. More workers improve parallel job processing, but require more system memory.

delayed_job_workers = 3

kiwi_storage

Specifies the directory where SLMS searches for KIWI definitions of appliances.

kiwi_storage = /var/lib/slms/kiwi

netlogger_dir

Specifies the directory where the log files of netlogger are stored. netlogger_dir = /var/log/slms/netlogger

delta_rpms_count

Specifies the number of delta RPMs that will be created for each new updated RPM package. 0 disables the feature, 1 creates delta RPMs between the last RPM package and the new one, 2 does the same as 1 plus it also creates delta RPMs between the last-but-one and the new RPM package and so on.

The main benefit is that delta RPMs reduce the size of the required download for the clients. The drawback is that bigger disk space is required on the SLMS side, and it also takes more time to create a new patch.

delta_rpms_count = 1

[Note]

To make use of delta RPMS, you need to install the deltarpm package on client machines. Otherwise the update tool will not try to make use of the delta RPM mechanism when applying an update patch.

9.2. /etc/slms-secrets.conf

/etc/slms-secrets.conf contains specific information such as credentials to access network services or a database, GPG key id and passphrase, or a string to generate a unique Web session.

9.2.1. [SUSEStudio] Section of /etc/slms-secrets.conf

restapi

Specifies the URL path to the SUSE Studio REST API (REpresentational State Transfer, a style of software architecture for distributed systems).

restapi = https://susestudio.com/api/v2/user

[Note]SLMS and SUSE Studio Onsite

SUSE Studio Onsite does not use HTTPS protocol by default. If your SLMS server needs to communicate with SUSE Studio Onsite, you have to change the SUSE Studio URL accordingly.

user

Specifies the username to approach the SUSE Studio REST API.

user = exampleuser

apikey

Specifies the API key used as a password for the SUSE Studio REST API.

apikey = examplekey

9.2.2. [Updates] Section of /etc/slms-secrets.conf

signing_key_id

Specifies the id of the GPG key used to sign the update repositories.

signing_key_id = openpgp_key_id

signing_key_pass

Specifies the passphrase of the GPG key used to sign the update repositories.

signing_key_pass = openpgp_key_passphrase

9.2.3. [SLMS] Section of /etc/slms-secrets.conf

session_secret

Specifies a random string used to generate a unique session string to identify the user of the SLMS Web application. The string is generated during the SLMS installation and should never be changed, otherwise all sessions will become invalid.

session_secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

rest_auth_site_key

Specifies a random key used to hash passwords of Web application administrator accounts. The key is generated during the SLMS installation and should never be changed, otherwise all passwords will become invalid. For additional information, see the tip in Section 3.4, “Setup with Two Servers”.

rest_auth_site_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

9.3. /etc/slms-cc.conf

/etc/slms-cc.conf stores information related to the SLMS customer center. For more information on the customer center, see Section 6.9, “Customer Center”.

9.3.1. [UI] Section of /etc/slms-cc.conf

enabled

Specifies whether the customer center is enabled or not.

enabled = yes

label

Specifies the label text shown on the customer center Web page.

label = SUSE Lifecycle Management Server - Customer Center

Chapter 10. Questions and Answers

This chapter provides a set of answers to common problems that SLMS customers may face. If you think you found a topic that can enhance this chapter, contact us (see Chapter 1, About this Guide for more information on feedback) or file a bug.

10.1. Something went wrong. Where are the log files?

Log files are very useful place where you can find information about processes inside SLMS. In case SLMS does not behave the way you expect it, you can have a look at the particular log file and see if there is more information related to the problem. For more information on log files, see log files .

10.2. Hard disk out of space on the SLMS server. How can I free some space?

If it is a long-running SLMS instance, then the command line tool slms purge can help in this situation. See Section 8.1.8, “slms purge” for more information.

10.3. Update tool reports repository metadata problem. What does that mean?

The update tool can be for example zypper, WebYaST, or an online updater applet), depending how you apply update patches. This indicates a problem in SLMS, where the update repository metadata generation goes wrong. In this situation it is possible to re-generate the repository metadata again from scratch. You can do it with the command line tool slms update --regenerate. See Section 8.1.11, “slms update” for more information.

10.4. Why is not a SUSE Studio appliance visible in SLMS after synchronization?

SLMS automatically hides SUSE Studio appliances that are not properly adapted for use with the given SLMS instance. In SUSE Studio, you first need to enable delivery of update patches via SLMS, while the entered hostname has to match the hostname of the server where the registration happens (it is the external server in two-server scenario). For more information, see Section 5.2, “Appliance Adaptation”.

10.5. I plan to replace one SUSE Studio instance with another. Is it OK?

Although this scenario is possible, it is not supported. We understand that for testing purposes it can be handy. Another possible use case may also be switching from SUSE Studio to SUSE Studio Onsite. Be aware that before switching to a new Studio instance, you need to delete all the old appliances, nodes, and subscriptions. You may also consider a complete re-deployment of SLMS, because it is probably easier and has the same effect.

In case of restoring a backed-up version of Studio, you do not have to clean the SLMS database as long as the backed-up Studio database is identical to the one you are replacing (has the same database records).

10.6. I cannot log in to SLMS. What is the problem?

Check whether the initial screen is dark or green. If it is green, then it is a customer center and it has a separate login credentials. For more information, see Section 6.9, “Customer Center”.

10.7. How do I add/replace an old SSL certificate with a new one?

Add the new SSL certificate file as an overlay file (see Section 6.6, “Overlay Files”) that replaces the old one, and add a script to the patch (see Step 6) containing the c_rehash command.

[Tip]

The c_rehash command is included in the openssl package. Check if it is installed before adding the new SSL certificate file.

10.8. How do I adapt an appliance using command line?

Appliance adaptation is discussed in a separate chapter (see Section 5.2, “Appliance Adaptation”). It is required for local KIWI appliances only, while SUSE Studio appliances come into SLMS already enabled and adapted from SUSE Studio.

First synchronize all appliances, then get their list, and read the ID of the appliance you want to publish an update patch for.

tux@venus:~> slms appliance --sync
[...]
tux@venus:~> slms appliance --list
-------+-------------------+-----------------------+---------+-------
 ID    | Name              | Studio ID/kiwi loc    | Status  | Arch
-------+-------------------+-----------------------+---------+-------
 [...]
 15    | SLES_11_SP2_JeOS  | /SLS_11_SP2/source    | Unknown | noarch 
 [...]

The appliance ID is 15. Because it is a new KIWI appliance, you need to set its architecture (which enables it), and then adapt it.

tux@venus:~> slms appliance --id 15 --set-arch x86_64
Architecture for appliance succesfully set.
tux@venus:~> slms appliance --id 15 --list
-----+------------------+--------------------+---------+---------+---------+
 ID  | Name             | Studio ID/kiwi loc | Status  | Base sys| Arch    |
-----+------------------+--------------------+---------+---------+---------+
  15 | SLES_11_SP2_JeOS | /SLS_11_SP2/source | Unknown | UNKNOWN | x86_64  |
-----+------------------+--------------------+---------+---------+---------+

Note that the architecture changed to x86_64.

tux@venus:~> slms appliance --id 15 adapt

After the adaptation finished, build the appliance. Now it is ready to receive updates from your SLMS site.

10.9. How do I publish an update patch using command line?

Once the appliance is enabled and adapted (see Section 10.8, “How do I adapt an appliance using command line?”), list its update repositories. Note the number of pending updates, and the ID of the testing update repository you want to create the patch in. Suppose the ID of our relevant appliance is 15.

tux@venus:~> slms update --list --appliance-id 15
----+--------------------+---------------------+---------+--------+---------
 ID | Repo name          | Status              | Default | Custom | Pending 
----+--------------------+---------------------+---------+--------+---------
 7  | Production Updat.. | Awaiting qa approval| Yes     | No     | 16     
 8  | Main Testing Repo  | Qa rejected         | No      | No     | 16   
----+--------------------+---------------------+---------+--------+---------

The ID of the update repository we are going to use for the update patch is 8, and the number of pending updates is 16. The very basic command for creating an update patch follows.

[Tip]

Remember to always synchronize the appliance before creating an update patch for it. In our case, it would be:

slms appliance --sync --id 15

tux@venus:~> slms update --create-patch 8 --appliance-id 15 \
--patch-name test_patch_no_1 --severity recommended

Now it is time to test the new update patch. If it is broken, reject it with

slms update --reject 8 --appliance-id 15

Otherwise approve it with

slms update --approve 8 --appliance-id 15

and publish in the production environment with

slms update --publish 8 --appliance-id 15

10.9.1. Including and excluding additional files/packages

Optionally, you can modify the patch by including/excluding additional packages or files (see Section 6.6, “Overlay Files”. and Section 6.5, “Manually Handled Packages”). This change has to take place before creating the patch with slms update --create-patch.

To list added overlay files, run

tux@venus:~> slms appliance --id 15 --overlays
--------+----------------------------+-----+------+-----------+--------+
 FileID | Path                       | In? | Perm | Owner     | Group  |
--------+----------------------------+-----+------+-----------+--------+
 34     | /bootsplash.tar            | Y   | 600  | root      | wheel  |
 35     | /build-custom              | N   | 600  | root      | wheel  |
 36     | /etc/HOSTNAME              | Y   | 600  | root      | wheel  |
[...]

Notice the value in the In? ('Included?') column. You can either include already excluded overlay file, or exclude the included one from the next update patch. To include an overlay file, run

tux@venus:~> slms appliance --id 15 --include-overlay 35
The overlay file 35 has been included.

To exclude an overlay file, run

tux@venus:~> slms appliance --id 15 --exclude-overlay 35
The overlay file 35 has been excluded.

To list additional packages, run

tux@venus:~> slms appliance --id 15 --additional-dependencies
--------+-----------------------------------------+-----+------+-------
 FileID | Path                                    | In? | Perm | Owner
--------+-----------------------------------------+-----+------+-------
 1      | libpng12-0                              | >=  | 1... | ?     
 2      | xorg-x11-libX11                         | >=  | 7... | ?     
 3      | xli                                     | >=  | 20.. | ?     
 [...]

To exclude a package from the dependency list, run

tux@venus:~> slms appliance --id 15 --exclude-dependency 2
The overlay file 2 has been excluded.

To include a package, run

tux@venus:~> slms appliance --id 15 --include-dependency 2
The overlay file 2 has been included.

10.9.2. Adding a custom script

Moreover, you can add a custom script that will be run after the next update patch is installed (see Step 6).

Suppose you have a script rehash_keys.sh in the /usr/local/scripts directory that you want to run after the next patch is installed. Make sure the slms user can read the script (and all its parent directories), and then create the patch adding --script:

tux@venus:~>slms update --create-patch 8 --patch-name sec_patch_no_2 \
--appliance-id 15 --severity security \
--script /usr/local/scripts/rehash_keys.sh

10.9.3. Adding custom repositories

If you need more than the two default update repositories (the production one, and the main testing one)—for testing and staging purposes—you can create as many custom update repositories as you need. Use the slms update --create-repo command:

tux@venus:~> slms update --create-repo custom_repo_1 --appliance-id 15
Update repository 'custom_repo_1' has been successfully created.
tux@venus:~> slms update --list --appliance-id 15
--+-----------------------------+----------------------+---------+--------
ID| Repo name                   | Status               | Default | Custom 
--+-----------------------------+----------------------+---------+--------
1 | Production Update Reposit.. | Awaiting qa approval | Yes     | No   
2 | Main Testing Repository     | Published            | No      | No
7 | custom_repo_1               | Awaiting qa approval | No      | Yes
--+-----------------------------+----------------------+---------+--------

The newly created custom update repository has ID 7, and you can normally use it the same way as the two default repositories. See Section 10.9, “How do I publish an update patch using command line?” for more information on how to publish an update patch.

Appendix A. SSL Certificates

For security reasons, the communication between client machines and the SLMS server is encrypted with an SSL key. The public part of the key has to be copied from the SLMS server to the appliance, while the private part must be kept on the server. Otherwise the appliance will not be able to register with the SLMS server.

Correct installation of an SSL certificate in the SLMS environment takes the following general steps:

  1. Install your SSL certificate on the SLMS server. For more information, see Section A.3, “How to Install SSL Certificate on the SLMS Server”.

    1. If your client appliance is not built yet, add the public part of the SSL certificate as an overlay file to the appliance in SUSE Studio. For more information, see Section A.4, “How to Add SSL Certificate to an Appliance”.

    2. If your appliance is already built without the server SSL certificate, you need to copy it to the appliance. For more information, see Section A.5, “How to Copy the SSL Certificate to the Client Appliance”.

Basically, there are two types of SSL certificates: either self-signed certificates, or certificates signed by a well known certification authority (CA).

A.1. Self-signed SSL Certificates

If there is no valid certificate on the SLMS server after you finished the configuration steps, a self-signed one will be automatically created. The client appliance does not know the self-signed certificate. Therefore, the communication with the SLMS server is not straightforward.

In general, customers are not advised to use self-signed certificates for their SLMS servers, as appliances may fail to use the generated updates. One of these reasons is that the appliance does not know the certificate. This is quite common if the certificate was generated during the SLMS configuration. When a customer tries to register the appliance, the certificate verify failed error message appears.

The other reason may be that the certificate is generated for a different server hostname. In this case, the following error message appears: certificate subject name xxx does not match target host name yyy.

The SLMS server needs to have the SSL certificate correctly created so that the hostname (Common Name) in the certificate matches with the external_server_url option in the /etc/slms.conf configuration file.

A.2. CA SSL Certificates

The most comfortable option is to have an SSL certificate signed by a well-known authority (CA). Web browsers usually know these certificates, and you will not notice any problems in communication with the SLMS server.

[Tip]

Your client appliance also needs to communicate with the SLMS server in another way than through the Web browser. For instance, the suse_register command on the client talks with the SLMS server through SSL encryption, too. Add the openssl-certs package to your client appliance in SUSE Studio. It includes a number of certificates signed by well-known CA's, so that your client appliance will have no problems communicating with the SLMS server. The certificates are stored under /etc/ssl/certs by default.

A.3. How to Install SSL Certificate on the SLMS Server

To enable your certificate on the SLMS server, follow these steps:

[Note]

In case of two-server scenario, SLMS server refers to the external SLMS server.

  1. Find the default SSL certificate files. They are stored under /etc/slms.d/certs (servercert.pem and serverkey.pem).

  2. Back up these certificates and copy your new ones exactly to the same location.

  3. Restart the SLMS service with rcslms restart for the changes to take effect.

A.4. How to Add SSL Certificate to an Appliance

Adding an SSL certificate to an appliance in SUSE Studio is now part of enabling the appliance for SLMS in general. Refer to Section 5.2.1, “Appliance Adaptation in SUSE Studio” for more information.

A.5. How to Copy the SSL Certificate to the Client Appliance

To copy the SSL certificate from the SLMS server to a running appliance, follow these steps:

  1. Open your favorite terminal application and copy the SLMS server SSL certificate file in /etc/slms.d/certs/servercert.pem to /etc/ssl/certs on the appliance.

    scp /etc/slms.d/certs/servercert.pem exampleuser@appliance_host:/etc/ssl/certs
  2. Execute c_rehash on the appliance as root to properly import the new certificate.

Appendix B. GNU Licenses

This appendix contains the GNU Free Documentation License version 1.2.

B.1. GNU Free Documentation License

Copyright (C) 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.

0. PREAMBLE

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.

1. APPLICABILITY AND DEFINITIONS

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.

2. VERBATIM COPYING

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.

3. COPYING IN QUANTITY

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.

4. MODIFICATIONS

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:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

  4. Preserve all the copyright notices of the Document.

  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  8. Include an unaltered copy of this License.

  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

  15. Preserve any Warranty Disclaimers.

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.

5. COMBINING DOCUMENTS

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".

6. COLLECTIONS OF DOCUMENTS

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.

7. AGGREGATION WITH INDEPENDENT WORKS

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.

8. TRANSLATION

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.

9. TERMINATION

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.

10. FUTURE REVISIONS OF THIS LICENSE

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.

ADDENDUM: How to use this License for your documents

   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.

Index

A

add-on
installation, Installing SLMS as an Add-On During the Initial SLE Installation
administrator account
creating, slms-admin-ui-user
appliance
adaptation, Appliance Adaptation
appliances
supported, Managing Appliances

C

command line
scripts, Command Line Scripts
configuration
files, Configuration Files
initial, Installation and Deployment
with WebYaST module, All-In-One Server Setup
configuration file
/etc/slms-cc.conf, /etc/slms-cc.conf
/etc/slms-secrets.conf, /etc/slms-secrets.conf
/etc/slms.conf, /etc/slms.conf
Customer Center, Customer Center

M

maintenance
workflow, Maintenance Workflow

Q

Questions and Answers, Questions and Answers

R

registration
URL, All-In-One Server Setup, Internal Server
regression
test, Regressions
requirements
hardware, Minimal System Requirements

SUSE Lifecycle Management Server SUSE Lifecycle Management Server Manual 1.3