SUSE Manager 3

Getting Started

Author: Joseph Cayouette
Contributor: SUSE Manager Team
Publication Date: 2017-10-25

Copyright © 2017 SUSE LLC

Copyright © 2011-2014 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution-Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

This document is an adaption of original works found at https://access.redhat.com/site/documentation/en-US/Red_Hat_Network_Satellite/5.4/ and https://access.redhat.com/site/documentation/en-US/Red_Hat_Network_Satellite/5.5/ and https://access.redhat.com/site/documentation/en-US/Red_Hat_Satellite/.

Red Hat, as a licensor of these documents, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux® is the registered trademark of Linus Torvalds in the United States and other countries. Java® is a registered trademark of Oracle and/or its affiliates. XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries. All other trademarks are the property of their respective owners.

For Novell trademarks, see the Novell Trademark and Service Mark list http://www.novell.com/company/legal/trademarks/tmlist.html. Linux* is a registered trademark of Linus Torvalds. All other third party trademarks are the property of their respective owners. A trademark symbol (®, ™ etc.) denotes a 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 Novell, Inc., SUSE LINUX Products GmbH, the authors, nor the translators shall be held liable for possible errors or the consequences thereof.

1 What is Covered?

Get started with SUSE Manager 3 by setting up a KVM learning environment. This quick-start guide will provide you with introductory guidance on setting up a SUSE Manager server. You will learn the basics of managing both traditional SUSE Manager clients and Salt clients. This guide is intended for system administrators.

1.1 Introducing SUSE Manager

SUSE Manager lets you efficiently manage large sets of Linux systems and keep them up to date. It provides automated and cost-effective software management, asset management, and system provisioning. SUSE Manager provides a best in class solution for organizations requiring absolute control of maintenance and package deployment on their servers. It allows customers the highest level of flexibility and power ensuring their servers remain secure while facilitating and advancing an organizations system life-cycle requirements.

Salt.  The inclusion of Salt in SUSE Manager 3 provides powerful event-driven configuration and management capabilities for fine grained control of any modern infrastructure.

Salt-master.  SUSE Manager 3 takes a commanding role as a Salt-master capable of orchestrating thousands of Salt-minions (SUSE Manager Clients) via remote execution.

Distribution Management.  SUSE Manager 3 is also fully compatible with Red Hat Satellite Server and offers seamless management of both SUSE Linux Enterprise and Red Hat Enterprise Linux client systems.

1.2 Overview

Note
Note: Version Information

SUSE Manager 3 was originally released as a SLES 12 SP1 extension. With the next maintenance update (2017), SUSE Manager 3 will be based on SLES 12 SP3 and it will support SLE 12 SP3 clients officially. In the following sections and chapters, it is highly recommended to use SLE 12 SP3 instead of SP1 or SP2.

SUSE Manager may be integrated within your network infrastructure in multiple ways. In this guide you will be installing SUSE Manager 3 as an extension to SUSE Linux Enterprise Server 12 SP3 utilizing either the JeOS (pronounced Juice, Just Enough Operating System) image or alternatively the full SLES 12 SP3 DVD image within a KVM virtual machine. You will register your SUSE Manager server with SUSE Customer Center then sync or (Mirror) the SUSE Linux Enterprise 12 SP3 channel (Channels may also be referred to a mirrored repository, containing software updates and patch data.) for a client which will be registered with SUSE Manager.

Tip
Tip: SUSE Virtualization Guide

For more information on virtualization, see https://www.suse.com/documentation/sles-12/singlehtml/book_virt/book_virt.html.

1.3 Prerequisites for Installation

This guide requires that you have created an account with SCC (SUSE Customer Center). During installation of both SUSE Linux Enterprise Server 12 SP3 and SUSE Manager 3, SUSE Customer Center credentials will be requested and you must enter them to receive the latest packages and updates. The following procedure will guide you through obtaining your SCC Organizational Credentials.

Procedure 1.1: Obtaining Your SCC Organization Credentials
  1. Open a browser and direct it to https://scc.suse.com/login.

  2. If you have not done so, create an account now.

  3. Log in to your new SCC account.

  4. Under the Management tools widget select Manage Users.

  5. Click the Organization Credentials tab.

  6. Keep this information handy during SUSE Manager 3 setup.

1.4 Obtaining Installation Media

After logging into your SCC account, you can find the installation images provided at the following addresses. Select one and continue reading:

Note
Note: Just Enough Operating System (JeOS) vs. Full Media Image

The SLES 12 SP1 JeOS image provides the quickest route for setup of a test environment. The JeOS image total size is about 240 MB. The alternative would be the 3 GB SUSE Linux Enterprise Server 12 SP3 DVD image. Both installation media are appropriate, but depend upon available bandwidth or your application needs. Both methods of installation will be covered in this guide.

1.5 Hardware Requirements

Review the following table for SUSE Manager hardware and software requirements. For installation on z Systems, see Book “Advanced Topics”, Chapter 1 “SUSE Manager on IBM z Systems.

Hardware

Recommended

CPU

Multi-core 64-bit CPU (x86_64)

RAM

Minimum 4 GB+ for test server

Minimum 16 GB+ for base installation

Minimum 32 GB+ for a production server

Free Disk Space

Minimum 100 GB for root partition

For the purposes of this guide the default JeOS root partition size of 24 GB will be sufficient

Minimum 50 GB for /var/lib/pgsql

Minimum 50 GB per SUSE product + 100 GB per Red Hat product /var/spacewalk

1.6 Supported Client Systems

Clients with the following operating systems are supported for registration with SUSE Manager. If you plan on using the new Salt features, ensure your clients are supported.

Note
Note: Supported Versions and SP Levels

Client operating system versions and SP levels must be under general support (normal or LTSS) to be supported with SUSE Manager. For details, see https://www.suse.com/lifecycle.

Operating Systems

Architecture

Traditional Clients

Salt Clients

SUSE Linux Enterprise 11 SP4 LTSS

x86, x86_64, Itanium, IBM POWER, z Systems

Supported

Supported

SUSE Linux Enterprise 12 SP1, SP2, SP3

x86_64, IBM POWER (ppc64le), z Systems

Supported

Supported

Red Hat Enterprise Linux 5

x86, x86_64

Supported

Unsupported

Red Hat Enterprise Linux 6

x86, x86_64

Supported

Supported

Red Hat Enterprise Linux 7

x86, x86_64

Supported

Supported

Novell Open Enterprise Server 11, SP1, SP2, SP3 LTSS

x86, x86_64

Supported

Coming Soon

1.7 Additional Requirements

To successfully complete this guide some network requirements must be met. The following section will walk you through these requirements.

Fully Qualified Domain Name (FQDN):  The SUSE Manager server must resolve its FQDN correctly or cookies will not work properly on the Web UI. For more information on FQDN, see:

Hostname and IP Address:  To ensure that SUSE Manager's domain name can be resolved by its clients, both server and client machines must be connected to a working Domain Name System (DNS) server. This guide assumes the required infrastructure exists within your environment. For more information on setting up a (DNS) server, see:

Important
Important: Naming Your Server

The hostname of SUSE Manager must not contain uppercase letters as this may cause jabberd to fail. Choose the hostname of your SUSE Manager server carefully. Although changing the server name is possible, it is a complex process and unsupported.

For a more complete overview on SUSE Manager requirements not covered in this guide, see Book “Best Practices”, Chapter 2 “Introduction”.

1.8 Firewall Rules

In a production environment SUSE Manager server and its clients should always utilize firewall rules. The following table provides an overview of required ports for use by SUSE Manager 3. Alternatively you may wish to disable the firewall during evaluation.

Table 1.1: Required Server Ports

Port

Description

67

Required when SUSE Manager is configured as a DHCP server for systems requesting IP addresses.

69

Used when SUSE Manager is configured as a PXE server and allows installation and re-installation of PXE-boot enabled systems.

80

Used to contact SUSE Customer Center. All Web UI, client, and proxy server requests travel via http or https.

443

All Web UI, client, and proxy server requests via http or https and SUSE Manager uses this port for SUSE Customer Center inbound traffic.

5222

When you wish to push actions to clients this port is required by the osad daemon running on your client systems.

5269

Needed if you push actions to or via a SUSE Manager Proxy.

4505

Required by the Salt-master for communication via TCP to minions.

4506

Required by the Salt-master for communication via TCP to minions.

2 JeOS Installation

2.1 Virtual Machine Manager (virt-manager) Settings

This chapter provides the required (KVM) settings for installation of SUSE Linux Enterprise Just Enough Operating System (JeOS) 12 as the base for the SUSE Manager 3. A kernel virtual machine (KVM) combined with Virtual Machine Manager (virt-manager) will be used as a sandbox for your first installation.

Enter the following settings when creating a new virtual machine using virt-manager.

KVM Settings

Installation Method:

Import Existing Disk Image

OS:

Linux

Version:

SLES12-SP1-JeOS-for-kvm-and-xen.x86_64-GM.qcow2

Memory:

4096 MB

CPU's:

2

Storage Format:

.qcow 24 GB (Default) JeOS Root Partition

Virtual Disks:

VirtIO Disk 2

VirtIO Disk 3

VirtIO Disk 4

 

101 GB for /var/spacewalk

50 GB for /var/lib/pgsql

4 GB for swap

Name:

example-server

Network

Bridge br0

Tip
Tip: SUSE Virtualization Guide

For more information on virtualization, see https://www.suse.com/documentation/sles-12/singlehtml/book_virt/book_virt.html.

2.2 JeOS KVM Settings

Create 3 additional virtual disks required for the SUSE Manager storage partitions.

Procedure 2.1: Creating the Required Partitions with KVM
  1. Create a new virtual machine using the downloaded JeOS KVM image and select Import existing disk image.

  2. Configure RAM and number of CPU's: At least 4 GB RAM and 2 CPUs.

  3. Name your KVM machine and select the >Customize configuration before install checkbox.

  4. Select the Add Hardware button and create three new virtual disks with the following specifications. These disks will be partitioned and mounted in the following procedure.

    VirtIO Storage Disks

    Name

    Sizing

    VirtIO Disk 2

    spacewalk

    101 GB

    VirtIO Disk 3

    pgsql

    50 GB

    VirtIO Disk 4

    swap

    4 GB

  5. Select Begin Installation and your new VM will boot from the JeOS image.

Proceed through the basic JeOS installation prompts until you reach the command line.

2.3 Preparing JeOS for SUSE Manager

Procedure 2.2: Preparing JeOS for SUSE Manager Installation
  1. Register with SCC:

    # SUSEConnect -e EMAIL_ADDRESS -r SUSE_MANAGER_CODE
  2. Add SUSE Manager repositories:

    # SUSEConnect -p SUSE-Manager-Server/3.0/x86_64 -r SUSE_MANAGER_CODE
  3. Install yast2 and yast2-installation packages. You will need YaST Partitioner to prepare the storage partitions:

    # zypper in yast2 yast2-installation
  4. Partition and mount the virtual disks at the following locations using YaST Partitioner (yast2 disk).

    VirtIO Storage Disks

    Name

    Storage Size

    File System Type

    VirtIO Disk 2

    /var/spacewalk

    101 GB

    XFS

    VirtIO Disk 3

    /var/lib/pgsql

    50 GB

    XFS

    VirtIO Disk 4

    /swap

    4 GB

    swap

  5. SLES 12 SP1 is installed on the BTRFS file system. A mount point is created automatically for /var/lib/pgsql/ (even when not installed). This must be removed or commented out from the /etc/fstab entries. As root edit /etc/fstab and comment out or remove the line:

    /var/lib/pgsql btrfs subvol=@/var/lib/pgsql 0 0
    Warning
    Warning: Removing the /etc/fstab pgsql Entry

    If you do not remove this line from fstab the first time you shutdown the server you will lose your database. This occurs because you will have duplicate entries in the fstab.

  6. Exit partitioner and install the SUSE Manager pattern:

    # zypper in -t pattern suma_server
  7. Execute SUSE Manager setup:

    # yast2 susemanager_setup

Proceed to Chapter 4, Setup.

3 SLES 12 Installation

Note
Note: Version Information

SUSE Manager 3 was originally released as a SLES 12 SP1 extension. With the next maintenance update (2017), SUSE Manager 3 will be based on SLES 12 SP3 and it will support SLE 12 SP3 clients officially. In the following sections and chapters, it is highly recommended to use SLE 12 SP3 instead of SP1 or SP2.

3.1 SLES 12 KVM Requirements

This chapter provides the required (kvm) settings for installation of SUSE Linux Enterprise Server 12 SP3 media as the base for the SUSE Manager 3. A kernel virtual machine (kvm) combined with Virtual Machine Manager (virt-manager) will be used as a sandbox for this installation.

Enter the following settings when creating a new virtual machine using virt-manager.

KVM Settings for SLES 12 SP3

Installation Method:

Local install media (ISO image or CDROM)

OS:

Linux

Version:

SLE-12-SP3-Server-x86_64-GM-DVD1.iso

Memory:

4096 MB

CPUs:

2

Storage Format:

ISO 3 GB

Additional Disks:

Virtual Disk 1

Virtual Disk 2

103 GB split between 2 GB swap and 100 GB mounted at: /var/spacewalk/

50 GB will be mounted at /var/lib/pgsql

Name:

example-server

Network

Bridge br0

3.2 SLES 12 KVM Settings

This section provides guidance on installation of SUSE Manager utilizing the full installation media with KVM and virt-manager. This section assumes you have previously setup an account with SCC and downloaded the SLES 12 SP3 full installation media.

Procedure 3.1: Preparing for SLES 12 SP3 Installation
  1. In virt-manager select File then New Virtual Machine.

  2. Choose Local install media (ISO image or CDROM).

  3. Ensure Use ISO Image is selected then click Browse and locate the full SLES 12 SP3 image you downloaded from your SCC account.

  4. Configure your machine with at least 4096 MB RAM and a minimum of 2 CPUs.

  5. Create a storage device with a minimum of 200 GB storage space for the installation. (During the partitioning setup of the SLES 12 SP3 installation this disk should be partitioned into a 4 GB swap a 100 GB partition for /var/spacewalk/ (XFS) and an additional 50 GB partition for /var/lib/pgsql/ (XFS). The remaining storage space will be used by the operating system). Select Finish to begin installation.

Installation of SUSE Linux Enterprise Server 12 SP3 will begin. For more information on completing an installation of SUSE Linux Enterprise Server 12, see https://www.suse.com/documentation/sles-12/book_quickstarts/data/sec_sle_installquick.html.

3.3 Selecting the SUSE Manager 3 Extension

During the SUSE Linux Enterprise Server 12 SP3 installation you will be presented with the Extension and Module Selection (see Figure 3.1, “Selecting SUSE Manager Extension”). Select the SUSE Manager 3 Extension and then complete the SUSE Linux Enterprise Server 12 SP3 installation. This new extension will install SUSE Manager 3 and configures SUSE Manager as a Salt-master by default.

Selecting SUSE Manager Extension
Figure 3.1: Selecting SUSE Manager Extension

4 Setup

4.1 Included Topics

This section covers setup procedures of SUSE Manager 3. You will perform the following procedures:

  • Initiate SUSE Manager 3 setup from the command line

  • Create the admin user with the SUSE Manager Web UI

  • Synchronize with SUSE Customer Center (SCC) to obtain a list of product channels available for your clients.

  • Add the SUSE Linux Enterprise 12 SP1 channel

Note
Note: Version Information

SUSE Manager 3 was originally released as a SLES 12 SP1 extension. With the next maintenance update (2017), SUSE Manager 3 will be based on SLES 12 SP3 and it will support SLE 12 SP3 clients officially. In the following sections and chapters, it is highly recommended to use SLE 12 SP3 instead of SP1 or SP2.

4.2 SUSE Manager Setup

Procedure 4.1: SUSE Manager Setup

This section will guide you through SUSE Manager setup procedures.

  1. To begin login to the SUSE Linux Enterprise 12 desktop. Open a terminal and as root and type: yast2 susemanager_setup to initiate setup.

  2. On the initial screen select Setup SUSE Manager from scratch and then select Next to continue.

  3. Enter an email address which will receive notifications about the server's status. The number of emails sent from SUSE Manager can be extensive, therefore notifications via email may be disabled from the Web UI after setup if desired. Select Next to continue.

  4. Enter your certificate information and a password. The password should be stored in a secure location. Without this password it will not be possible to setup a SUSE Manager Proxy Server. Select Next to proceed.

  5. You will be using an Embedded Database for this guide. Enter a database user and password. This password should be stored in a secure location. Select Next to continue.

  6. SUSE Manager requires that you connect to SUSE Customer Center for software, updates and patches. You will be unable to synchronize or provide channels to your clients without this information. Enter your SUSE Customer Center Organization Credentials. You may register or login https://scc.suse.com/login to access to your organization credentials. Select Next to continue.

  7. Select Yes to run setup when prompted. When completed you will be presented with your new SUSE Manager Web UI address. Select Finish to complete SUSE Manager setup.

In Section 4.3, “Creating the Administrator's Account” you will create the administrator's account and synchronize with SUSE Customer Center.

4.3 Creating the Administrator's Account

This section will walk you through creating the administrator's account for your SUSE Manager Server. The administrator's account is the highest authority account within SUSE Manager and therefore administrator account access information should be stored in a secure location. It is recommended that an administrator creates low level user accounts designated for administration of each organization or group under the administrator's account for security.

Procedure 4.2: Setting up the Administrator's Account
  • To begin open your browser and direct it to your SUSE Manager Server URL which was provided to you after completing setup.

    Enter your Desired Login name and Desired Password. Fill in the Account Information fields including an email for system notifications. Select Create Login to finish creating your administration account.

Congratulations! You should now be presented with the SUSE Manager Front Page. The next section will help prepare the server for connecting your first client.

4.4 Synchronizing with SUSE Customer Center (SCC)

SUSE Customer Center maintains a collection of repositories which contain packages, software and updates for all supported client systems. These repositories are organized into channels each of which provide software specific to a distribution, release and architecture. You must synchronize your SUSE Manager Server with SUSE Customer Center to add channels for your client systems. After synchronizing with SUSE Customer Center your clients are able to receive updates or be organized into groups to be assigned to a specific software channel. This section covers synchronizing with SUSE Customer Center from the Web UI and adding your first client channels.

Procedure 4.3: Synchronizing with SUSE Customer Center
  1. From the SUSE Manager Web UI start page select the Admin tab.

  2. From the Setup Wizard page select the SUSE Products tab. Wait a moment for the Available Products Below list to populate. You are present with a list of repositories provided from SUSE Customer Center. Each of these repositories represents a single software source known as a Base Channel within SUSE Manager. You can see the distribution, architecture and version from this page.

  3. As you are adding a SUSE Linux Enterprise 12 client based on the x86_64 architecture, scroll down the page and select the check box for this channel now.

    • Add single channels to SUSE Manager by selecting the + button to the left of each channel.

    • Add multiple channels by selecting the check boxes to the left of the channels list and then schedule synchronization by clicking the + Add products button located at the bottom of the page.

After adding your first channel SUSE Manager will schedule the channel to be copied and begin mirroring it. This can take a long time as SUSE Manager must copy all software sources from the SUSE Vendor repositories located at SUSE Customer Center to your servers local /var/spacewalk/ directory.

Tip
Tip: PostgreSQL andTransparant Huge Pages

In some environments, Transparent Huge Pages provided by the kernel may slow down PostgreSQL workloads significantly.

To disable transparant huge pages set the transparent_hugepage kernel parameter to never. This has to be changed in /etc/default/grub and added to the line GRUB_CMDLINE_LINUX_DEFAULT, for example:

GRUB_CMDLINE_LINUX_DEFAULT="resume=/dev/sda1 splash=silent quiet showopts elevator=noop transparent_hugepage=never"

To write the new configuration run grub2-mkconfig -o /boot/grub2/grub.cfg. To update the grub2 during boot run grub2-install /dev/sda.

Monitor channel synchronization process in real-time by viewing channel log files located in the following directory:

example-server:/var/log/rhn/reposync/# tail -f <Channel_Name>.log

After your channel sync has completed proceed to the next section.

5 Registering Clients

5.1 Introduction

All releases previous to and including SUSE Manager 2.1 were implemented and shipped with a client management framework, which today is still fully supported. In addition to this traditional framework SUSE Manager 3 includes a complete Salt solution. Salt is an end-to-end data-center automation tool which may also be used outside the scope of SUSE Manager to introduce reactive, real-time orchestration, and configuration management. Two of the greatest advantages of adding the Salt framework to SUSE Manager 3 are that it remains a popular open source project with a vibrant community and that it continues to be well documented and supported across the Web. Managed systems may coexist using both methods, allowing you to become comfortable using Salt while keeping existing deployments intact.

Note
Note: Version Information

SUSE Manager 3 was originally released as a SLES 12 SP1 extension. With the next maintenance update (2017), SUSE Manager 3 will be based on SLES 12 SP3 and it will support SLE 12 SP3 clients officially. In the following sections and chapters, it is highly recommended to use SLE 12 SP3 instead of SP1 or SP2.

5.2 Creating Your Keys

The following procedure will guide you through creating the activation keys for your test channels. Activation keys can be used for both Salt and traditional clients.

Activation keys define the number of software entitlements, channels and groups a client system is allowed to subscribe to. This information is passed on to all systems registered with a key. Each activation key is bound to the organization for which it has been created. For this guide you will be using the default SUSE Manager organization which includes all software entitlements. Activation keys may be used with traditional clients or with Salt clients.

Procedure 5.1: Creating Activation Keys
  1. Log in to the SUSE Manager Web UI as administrator.

  2. Switch to the Systems tab and select Activation Keys.

  3. Click the Create Key link at the upper right corner.

  4. Enter a Description to identify the generated activation key.

  5. Enter a human readable Key string value such as SLES12-SP3.

    Warning
    Warning: Allowed Characters

    For all SUSE Products do not use commas within the key string. Red Hat Products require commas. For more information, see Book “Reference Manual”, Chapter 2 “Systems”, Section 2.8 “Activation Keys”.

  6. Enter 1 in the Usage field. This allows one client to register using this key and uses one of your subscription entitlements.

  7. Select the SUSE Linux Enterprise 12 SP3 channel you added earlier from the Base Channels drop down.

  8. Leave the Contact Method at default.

  9. Leave Universal Default unchecked. Click Create Activation Key to finish creating the key for the first channel.

5.3 Creating the SUSE Manager Tools Repository

In this section you will create a tools repository on the SUSE Manager Server for providing client tools. The client tools repository contains packages for installing Salt on minions as well as the required packages for registering traditional clients during the bootstrapping procedure. These packages will be installed from the newly generated repository during the registration process. In the following procedure you will create the SUSE Linux Enterprise 12 SP3 tools repository.

Important
Important: Creating a Tools Repository when an SCC Channel has not been Synced

Before following the procedure to create the tools repository make sure the SUSE vendor channel you will be using with your client has been completely synced. You can check this by running tail -f /var/log/rhn/reposync/CHANNEL_NAME.log as root. For example:

# tail -f /var/log/rhn/reposync/sles12-sp3-pool-x86_64.log
Procedure 5.2: Generating the Tools Repository for SUSE Linux Enterprise 12 SP3
  1. Open a terminal on the server as root and enter the following command to list available bootstrap repositories:

    # mgr-create-bootstrap-repo -l
    SLE-12-SP3-x86_64
  2. Then invoke the same command using the listed repository as the product label to actually create the bootstrap repository:

    # mgr-create-bootstrap-repo -c SLE-12-SP3-x86_64
  3. SUSE Manager will create and add the client tools to the newly created repositories directory located at /srv/www/htdocs/pub/repositories/.

5.4 Registering Traditional Clients

5.4.1 Generating a Bootstrap Script

This section goes over generating a template bootstrap script which will be copied and modified for use with your traditional clients.

Traditional clients register with SUSE Manager via a bootstrap script executed on the client which deploys all necessary packages to it. The bootstrap script contains parameters which assigns a client system to its base channel. Two of these important parameters are:

  • Activation Keys

  • GNU Privacy Guard (GPG) Keys

Note
Note: GPG Keys

GPG Keys will not be covered in this guide. In the future review the Best practice guide for this topic.

Note
Note: Bootstrap Scripting Best Practices

It is possible to use various methods to register clients for use with SUSE Manager in mass using bootstrap. Using batch scripts for mass registration of both VM and Bare Metal machines is a possibility. Some of these methods will be covered in the Best Practices Guide and will be added as examples at a later time.

The following procedure will guide you through generating a bootstrap template script.

Procedure 5.3: Creating a Bootstrap Script
  1. On the SUSE Manager Web UI, switch to the Admin tab and select SUSE Manager Configuration › Bootstrap Script.

  2. Leave the default settings and click the Update button.

  3. A template bootstrap script is generated and stored on the server's file system in the /srv/www/htdocs/pub/bootstrap directory.

    # cd /srv/www/htdocs/pub/bootstrap
    # ls
    bootstrap.sh                  client_config_update.py
    client-config-overrides.txt   sm-client-tools.rpm

    The bootstrap script is also available at https://example.com/pub/bootstrap/bootstrap.sh.

Section 5.4.2, “Modifying the Bootstrap Script” will cover copying and modifying your bootstrap template for use with each client.

5.4.2 Modifying the Bootstrap Script

In this section you will copy and modify the template bootstrap script you created from Section 5.4.1, “Generating a Bootstrap Script”.

The minimal requirement when modifying a bootstrap script for use with SUSE Manager is inclusion of an activation key. Depending on your organizations security requirements it is strongly recommended to include one or more (GPG) keys (for example, your organization key, and package signing keys). For the purposes of this guide you will be registering with the activation keys created in the previous section.

Procedure 5.4: Modifying the Bootstrap Script
  1. Log in as root on the command line on your SUSE Manager server.

  2. Navigate to the bootstrap directory with:

    # cd /srv/www/htdocs/pub/bootstrap/
  3. Create and rename two copies of the template bootstrap script for use with each of your clients.

    # cp bootstrap.sh bootstrap-sles11-sp4.sh
    # cp bootstrap.sh bootstrap-sles12-sp3.sh
  4. Open sles12-sp3.sh for modification. Scroll down and modify both lines marked in green. You must comment out exit 1 with a hash mark (#) to activate the script and then enter the name of the key for this script in the ACTIVATION_KEYS= field as follows:

    echo "Enable this script: comment (with #'s) this block (or, at least just"
    echo "the exit below)"
    echo
    #exit 1
    
    # can be edited, but probably correct (unless created during initial install):
    # NOTE: ACTIVATION_KEYS *must* be used to bootstrap a client machine.
    ACTIVATION_KEYS=1-sles12-sp3
    ORG_GPG_KEY=
  5. When you have finished your modifications save the file and repeat this procedure for the second bootstrap script. Then proceed to Section 5.4.3, “Connecting Your First Client”.

Note
Note: Finding Your Keys

To find key names you have created: Select the Overview tab from the Web UI and then click Manage Activation keys › Key Field. All keys created for channels are listed here. You must enter the full name of the key you wish to use in the bootstrap script exactly as presented in the key field.

5.4.3 Connecting Your First Client

This section covers connecting your clients to SUSE Manager with the modified bootstrap script.

Procedure 5.5: Running the Bootstrap Script
  1. On your SUSE Manager Server as root navigate to the following directory:

    # cd /srv/www/htdocs/pub/bootstrap/
  2. Run the following command to execute the bootstrap script on the client:

    # cat MODIFIED-SCRIPT.SH | ssh root@example.com /bin/bash
  3. The script will execute and proceed to download the required dependencies located in the repositories directory you created earlier. Once the script has finished running, log in to the Web UI and select the Systems tab to see your new client listed.

This concludes the bootstrap section of this guide. Section 5.5, “Registering Salt Clients” will go over registering Salt minions for use with SUSE Manager 3.

5.5 Registering Salt Clients

There are currently three methods for registering Salt minions. The following section describes the first method and uses a bootstrap repository. The second method is to create a bootstrap script using mgr-bootstrap and include the optional --salt parameter. Bootstrapping Salt minions with mgr-bootstrap --salt is performed in the same manner as bootstrapping traditional clients; for more information, see Section 5.4, “Registering Traditional Clients”. The third method is performed from the SUSE Manager Web UI; find this method located in Book “Reference Manual”, Chapter 3 “Salt”, Section 3.2 “Bootstrapping Salt Minions”.

The following section assumes you have created a SUSE Manager tools repository. You can review creating a tools repository in Section 5.3, “Creating the SUSE Manager Tools Repository”.

When you have setup a base channel from the Web UI clients to obtain software sources from, for example: SLES12-SP3-Pool for x86_64 perform the following procedure to register a Salt minion.

Procedure 5.6: Registering Salt Minions
  1. On your minion as root enter the following command:

    # zypper ar http://FQDN.SUSE.Manager.com/pub/repositories/sle/12/3/bootstrap/ \
       sles12-sp3
    Note
    Note

    Do not use HTTPS. Use HTTP instead to avoid errors.

  2. After adding the repository containing the necessary Salt packages execute:

    # zypper in salt-minion
  3. Modify the minion configuration file to point to the fully qualified domain name (FQDN) of the SUSE Manager server (master):

    # vi /etc/salt/minion

    Find and change the line:

    master: salt

    to:

    master: FQDN.SUSE.Manager.com
  4. Restart the Salt minion with:

    # systemctl restart salt-minion

    or on non-systemd OS:

    # rcsalt-minion restart

Your newly registered minion should now show up within the Web UI under Salt › Onboarding. Accept its key to begin management.

6 Getting Started with Salt

6.1 Introduction

This chapter provides an introduction to using the new Salt features added in SUSE Manager 3. This chapter assumes you have completed all former sections within the Getting Started Guide. You should have a running SUSE Manager server and at least one on-boarded Salt minion to complete the sections of this chapter. If you find yourself stuck at any point refer to the SaltStack Get Started tutorial located at https://docs.saltstack.com/en/getstarted/fundamentals/index.html.

Tip
Tip: Use More than One Minion

Connecting two or more minions during your testing is considered best practice. This will allow you to target individual minions using Salt and experiment with the power of its targeting features.

This guide does not attempt to cover all that Salt has to offer. This guide is a primer for using Salt with SUSE Manager. For comprehensive Salt documentation, see https://docs.saltstack.com/en/latest/contents.html.

6.2 Understanding Salt Calls

Salt Calls

A great place to start would be learning basic Salt calls. Salt calls are defined by three main properties:

# salt 'target' function [arguments]
Target

Use the second property in a Salt call to define a target machine. Specify the minion or group of minions you would like to run a function on.

General Targeting

List available grains on all minions:

# salt '*' grains.ls

Ping a specific minion:

# salt 'web1.example.com' test.ping
Glob Targeting

Ping all minions using a domain:

# salt '*example.com' test.ping

Display the OS name of all minions with the label webserver:

# salt 'webserver*' grains.item oscodename
List Targeting
# salt -L 'webserver.example.com,db.example.com' test.ping
Regular Expression Targeting

You may use PCRE-compliant regular expressions:

# salt -E '(?!web)' test.ping
IP Address Targeting

List minion IP addresses:

# salt '*' network.ip_addrs

Ping a specific minion IP address:

# salt -S '172.31.60.74' test.ping

Ping all minions on a subnet:

# salt -S 172.31.0.0/16 test.ping
Tip
Tip: Lookup a Subnet Using the ip Command

You can use the ip command to find the subnet mask in the format of 192.168.1.1/24:

# ip -o -f inet addr show | awk '/scope global/ {print $4}'
Function

Once you have specified a target, provide the function you would like to call. Functions also accept arguments. These are space-delimited. For example:

salt '*' cmd.run 'echo "Hello: $FIRST_NAME"' env='{FIRST_NAME: "John"}'
Locating Additional Minion Functions

Find more functions which can be called on minions by running:

salt '*' sys.doc

A full list of callable functions are located here: https://docs.saltstack.com/en/2015.8/ref/modules/all/index.html

Arguments

Provides the extra data needed by a function you are calling. The command pkg.install requires an argument specifying a package to install. YaST has been selected for installation. For example:

# salt '*' pkg.install yast2

6.3 Common Salt Terminology

Grains

Grains provide information about the hardware of a minion. For example, the operating system, IP addresses, network interfaces, memory, etc. When running a Salt command from keep in mind any modules and functions called are run locally from the system being called. Salt modules are stored on minions and master within the following directory:

/usr/lib/python2.7/site-packages/salt/

List all available grains with the grains.ls function:

# salt '*' grains.ls

List collected grain system data by using the grains.items function:

# salt '*' grains.items

For more information on grains, see https://docs.saltstack.com/en/latest/topics/grains/.

States

States are templates which place systems into a known configuration, for example which applications and services are installed and running on those systems. States are a way for you to describe what each of your systems should look like. Once written, states are applied to target systems automating the process of managing and maintaining a large numbers of systems into a known state. For more information on states, see https://docs.saltstack.com/en/latest/topics/tutorials/starting_states.html.

Pillar

Pillars unlike grains are created on the master. Pillar files contain information about a minion or group of minions. Pillars allow you to send confidential information to a targeted minion or group of minions. Pillars are useful for sensitive data, configuration of minions, variables, and any arbitrary data which should be defined. For more information on pillars, see https://docs.saltstack.com/en/latest/topics/tutorials/pillar.html.

6.4 Useful Salt Commands

The following list provides several useful Salt commands.

salt-run

Print a list of all minions that are up:

# salt-run manage.up

Print a list of all minions that are down:

# salt-run manage.down

Print a list with the current status of all Salt minions

# salt-run manage.status

Check the version of Salt running on the master and active minions

# salt-run manage.versions
salt-cp

Copies a file to a minion or set of minions.

# salt-cp '*' foo.conf /root

For more information, see https://docs.saltstack.com/en/latest/ref/cli/salt-cp.html.

6.5 Salt File Locations and Structure

The following screen describes Salt file structures and their locations used by the SUSE Manager server. These files are listed in /etc/salt/master.d/susemanager.conf:

#Configure different file roots

file_roots:
  base:
    - /usr/share/susemanager/salt    #Should not be touched by a user
    - /srv/susemanager/salt          #Should not be touched by a user
    - /srv/salt                      #Your custom states go here

# Configure different pillar roots

pillar_roots:
  base:
    - /usr/share/susemanager/pillar  #Should not be touched by a user
    - /srv/pillar                    #Custom pillars go here

# Extension modules path

extension_modules: /usr/share/susemanager/modules

# Master top configuration

master_tops:
  mgr_master_tops: True

The following tips should be kept in mind when working with /etc/salt/master.d/susemanager.conf.

  • Files listed are searched in the order they appear.

  • The first file found is called.

6.5.1 file_roots

SUSE Manager as the Salt master reads its state data from three specific file root directories.

/usr/share/susemanager/salt

This directory is created by SUSE Manager and its content generated by the /usr/share/susemanager/modules/tops/mgr_master_tops.py python module:

It is shipped and updated together with SUSE Manager and includes certificate setup and common state logic that will be applied to packages and channels.

Warning
Warning: Non-editable Directory

You should not edit or add custom Salt data to this directory.

/srv/susemanager/salt

This directory is created by SUSE Manager and contains assigned channels and packages for minions, groups, and organizations. These files will be overwritten and regenerated. A good analogy for this directory would be the SUSE Manager database translated into Salt directives.

Warning
Warning: Non-editable Directory

You should not edit or add custom Salt data to this directory.

/srv/salt

The directory /srv/salt is for your custom state data, salt modules etc. SUSE Manager does not touch or do anything with this directory. However the state data placed here affects the Highstate of minions and is merged with the result generated by SUSE Manager.

Tip
Tip: Editable Directory

Place your custom Salt data here.

6.5.2 pillar_roots

SUSE Manager as the Salt master reads its pillar data from two specific pillar root directories.

/usr/share/susemanager/pillar

This directory is generated by SUSE Manager. It is shipped and updated together with SUSE Manager.

Warning
Warning: Non-editable Directory

You should not edit or add custom Salt data to this directory.

/srv/pillar

SUSE Manager by default does not touch or do anything with this directory. However the custom pillar data placed here is merged with the pillar result created by SUSE Manager.

Tip
Tip: Editable Directory

Place your custom Salt pillar data here.

Print this page