6 Getting Started with Salt
6.1 Introduction #
This section introduces you to the new Salt features added in Uyuni 3. This chapter assumes you have completed all previous Getting Started sections. At a minimum have the following setup:
A freshly installed Uyuni 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
This guide does not attempt to cover all that Salt has to offer. This guide is a primer for using Salt with Uyuni. For comprehensive Salt documentation, see https://docs.saltstack.com/en/latest/contents.html.
The current version of Salt in Uyuni 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
webserverlabel: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: Lookup a Subnet Using the
ipCommandYou can use the
ipcommand to find the subnet mask in the format of192.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.installrequires 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.lsfunction:salt '*' grains.ls
List collected grain system data by using the
grains.lsfunction: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: 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 Uyuni 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: 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: 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 Uyuni 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: TrueThe 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 #
Uyuni as the Salt master reads its state data from three specific file root directories.
- /usr/share/susemanager/salt
This directory is created by Uyuni and its content generated by the
/usr/share/susemanager/modules/tops/mgr_master_tops.pypython module. It is shipped and updated together with Uyuni and includes certificate setup and common state logic that will be applied to packages and channels.Warning: Do Not Edit
You should not edit or add custom Salt data to this directory.
- /srv/susemanager/salt
This directory is created by Uyuni 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: Do Not Edit
You should not edit or add custom Salt data to this directory.
- /srv/salt
The directory
/srv/saltis 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 Uyuni.Note: Editable
Place custom Salt data here.
6.5.2 pillar_roots #
Uyuni as the Salt master reads its pillar data from two specific pillar root directories.
- /usr/share/susemanager/pillar
This directory is generated by Uyuni. It is shipped and updated together with Uyuni.
Warning: Do Not Edit
You should not edit or add custom Salt data to this directory.
- /srv/pillar
Uyuni 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 Uyuni.
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 #
Install the locale formula with:
zypper install locale-formula
Note
This installs the package contents to
/usr/share/susemanager/formulas/{metadata,states}After installing the RPM, log in to the Uyuni Web UI.
Browse to the › page of any minion you would like to apply the formula to.
On the › page you will see a new tab. Select it to view a list of installed formulas.
From the list select › and click .
A new tab will appear next to the › subtab. Select the new › tab.
The › tab contains options for setting the language, keyboard layout, timezone, and whether hardware clock is set to UTC. Select the desired options and click .
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 ...Apply this state to your minion by applying the highstate from the command line with:
salt '$your_minion' state.highstate
Note
You can also apply the highstate from the previous formula tab from the Uyuni Web UI by selecting › and clicking .