Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]

6 Getting Started with Salt

6.1 Introduction

This section introduces you to the new Salt features added in SUSE Manager 3. This chapter assumes you have completed all previous Getting Started sections. At a minimum have the following setup:

  • A freshly installed SUSE Manager server with a main admin account and a synced product channel

  • Preferably two registered Salt minions to experiment with.

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.

Note
Note

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.

The current version of Salt in SUSE Manager is 2018.3.0.

6.2 Understanding Salt Calls

Salt Calls

Salt calls are defined by three main properties:

salt 'target' <function> [arguments]
Target

Use the second property in a Salt call to target a single machine or group of machines. 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 webserver label:

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. Arguments 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.ls 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.

Warning
Warning: Updating Salt

Do not update salt itself using Salt states. First update all other system packages using Salt states then update salt as a separate stand-alone step from the SUSE Manager Web UI.

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.

Beacons

Beacons allow an admin to use the event system in Salt to monitor non-Salt processes. Minions may use beacons to hook into many types of system proceses for constant monitoring. Once a targeted monitored activity occurs an event is sent on the Salt event bus that may be used to trigger a reactor.

Important
Important: Enabling Beacons

To work with beacons on Salt minions the package python-pyinotify must be installed for SUSE systems. For RES systems install python-inotify. This package is not installed automatically during the salt minion package installation.

Note
Note: Peer Communication with salt-broker

The salt-broker acts like a switch and not like a hub, therefore Peer communication will only work for minions behind the same broker/Proxy. For more information on Salt and peer communication see: https://docs.saltstack.com/en/latest/ref/peer.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

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

salt-key -l

List public keys:

salt-key -l
salt-key -A

Accept all pending keys:

salt-key -A

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: Do Not Edit

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: Do Not Edit

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 perform any actions on this directory. However the state data placed here affects the Highstate of minions and is merged with the result generated by SUSE Manager.

Note
Note: Editable

Place 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: Do Not Edit

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.

6.6 Install the SUSE Manager Locale Formula

The following section provides guidance on installing and using SUSE provided Salt formulas.

Procedure: Installing the Locale Formula
  1. Install the locale formula with:

    zypper install locale-formula
    Note
    Note

    This installs the package contents to /usr/share/susemanager/formulas/{metadata,states}

  2. After installing the RPM, log in to the SUSE Manager Web UI.

  3. Browse to the Main Menu › System Details page of any minion you would like to apply the formula to.

  4. On the Main Menu › System Details page you will see a new Formulas tab. Select it to view a list of installed formulas.

  5. From the Formulas list select Formulas › Locale and click Save.

  6. A new tab will appear next to the Formula › Locale subtab. Select the new Formulas › Locale tab.

  7. The Formalas › Locale tab contains options for setting the language, keyboard layout, timezone, and whether hardware clock is set to UTC. Select the desired options and click Save.

  8. Run the following command to verify pillar settings. The output has been truncated.

    salt '$your_minion' pillar.items
    ...
       keyboard_and_language:
           ----------
           keyboard_layout:
               English (US)
           language:
               English (US)
       machine_password:
           foobar
       mgr_server:
           manager_server
       org_id:alt '$your_minion_here'
           1
       timezone:
           ----------
           hardware_clock_set_to_utc:
               True
           name:
               CET
        ...
  9. Apply this state to your minion by applying the highstate from the command line with:

    salt '$your_minion' state.highstate
    Note
    Note

    You can also apply the highstate from the previous formula tab from the SUSE Manager Web UI by selecting System Details › States and clicking Apply Highstate.

6.7 Use Pillars to Set the Package Download Endpoint

By default, SUSE Manager assumes that the download endpoint to use is the FQDN of the SUSE Manager server, or the SUSE Manager Proxy. However, there are some cases where you might like to use a different FQDN as the download endpoint. The most common example is if you need to use load balancing, caching proxies, or in environments with complicated networking requirements.

To change the package download endpoint, you can manually adjust three salt pillars: * pkg_download_point_protocol, defaults to https. * pkg_download_point_host, defaults to the FQDN of the SUSE Manager Server (or Proxy, if in use). * pkg_download_point_port, defaults to 443.

If you do not adjust these pillars directly, SUSE Manager will fall back to the default values.

Procedure: Changing the package download endpoint pillar
  1. Navigate to /srv/pillar/ and create a file called top.sls with these contents:

    base:
      '*':
        - pkg_download_endpoints

    This example directs Salt to look at the pkg_download_endpoints.sls file to determine the base URL to use. You can adjust this file to target different minions or groups, depending on your environment.

  2. Remain in /srv/pillar/ and create a file called pkg_download_endpoints.sls with the base URLs you want to use. For example:

    pkg_download_point_protocol: http
    pkg_download_point_host: example.com
    pkg_download_point_port: 444
  3. OPTIONAL: You can use grains to set conditional values, for example:

{% if grains['fqdn'] == 'minion1.example.com' %}
    pkg_download_point: example1.com
{% elif grains['fqdn'] == 'minion2.example.com' %}
    pkg_download_point: example2.com
{% else %}
    pkg_download_point: example.com
{% endif %}
  1. OPTIONAL: If you want to use external pillars, for example Group IDs, open the master configuration file and set the ext_pillar_first parameter to true. You can then use Group IDs to set conditional values, for example:

    {% if pillar['group_ids'] is defined and Group_ID in pillar['group_ids'] %}
      pkg_download_point_protocol: http
      pkg_download_point_host: example.com
      pkg_download_point_port: 444
    {% else %}
      pkg_download_point_protocol: ftp
      pkg_download_point_host: example.com
      pkg_download_point_port: 445
    {% endif %}

6.8 Disabling the Salt Mine

In older versions, SUSE Manager used a tool called Salt mine to check minion availability. The Salt mine would cause minions to contact the server every hour, which created significant load. With the introduction of a more efficient mechanism in SUSE Manager 3.2, the Salt mine is no longer required. Instead, the SUSE Manager server uses Taskomatic to ping only the minions that appear to have been offline for twelve hours or more, with all minions being contacted at least once in every twenty four hour period by default. You can adjust this by changing the web.system_checkin_threshold parameter in rhn.conf. The value is expressed in days, and the default value is 1.

Newly registered Salt minions will have the Salt mine disabled by default. If the Salt mine is running on your system, you can reduce load by disabling it. This is especially effective if you have a large number of minions.

Disable the Salt mine by running this command on the server:

salt '*' state.sls util.mgr_mine_config_clean_up

This will restart the minions and generate some Salt events to be processed by the server. If you have a large number of minions, handling these events could create excessive load. To avoid this, you can execute the command in batch mode with this command:

salt --batch-size 50 '*' state.sls util.mgr_mine_config_clean_up

You will need to wait for this command to finish executing. Do not end the process with CtrlC.

Print this page