Salt

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

For a full list of callable functions, see https://docs.saltstack.com/en/latest/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

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.

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.

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

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

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.

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.

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.

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.

Editable

Place custom Salt data here.

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.

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.

Editable Directory

Place your custom Salt pillar data here.

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

    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.