Salt User Guide

If you’re looking to learn about Salt, you’ve come to the right place.

• View the Sphinx-built documentation here

• View the source repo here

About the Salt User Guide

The Salt User Guide supplements and extends the core documentation for the Salt Project. This guide is intended to help Salt users learn about Salt’s core concepts and features. It was originally authored by Alan Cugler and reviewed as a cross-collaborative effort between many Salt experts.

Contributions from anyone inside the Salt project community are always welcome. Please read the Contributing to Salt documentation for more information.

Related links

Check out the following links related to the Salt User Guide:

• Salt Project: The repository for the Salt Project.

• Salt Project Home Page: The web portal for Salt community events and resources.

• Contributing Guide: For information about contributing to the Salt User Guide and other Salt documentation projects, including how to set up your environment and other policies around submitting merge requests or issues.

• Salt Style Guide: For general guidance about using Salt Project terms and other style or formatting conventions.

• Writing Salt documentation (rST guide): For conventions and guidelines about formatting reStructured Text (rST) in Salt documentation.

Other Salt documentation

The following documentation is part of the Salt Project documentation:

• Salt Install Guide: This guide provides instructions for installing Salt on Salt supported operating systems. It also explains how to configure Salt, start Salt services, and verify your installation.

• Salt Project documentation: Includes the full documentation for the Salt Project.

• Module documentation: The Salt modules and state modules explain the use cases and arguments needed to execute the Salt modules.

Overview of the toolchain

This repository uses the following tools:

• The Salt User Guide documentation is composed in reStructured text (rST), which is a version of Markdown that is generally used in Python-based projects.

• The rST is then run through Sphinx, a static site generator that converts the rST into HTML for publication on the web.

• Sphinx applies the Furo Theme for Sphinx to render the site.

• The guide is also accessible directly on GitLab using the GitLab pages feature.

• GitLab handles the CI/CD pipeline for the project.

• Successful pipelines on the master branch get published to the docs.saltproject.io domain

Table of Contents

Salt basics

• Salt overview
  • Features of Salt
  • Salt management concepts
  • Salt topology
• Salt install, config, and start
• Salt grains
  • Use case
  • Grains terminal commands
  • Configuration settings
  • Defining custom grains
  • Precedence
  • States with grains
• State system behind the scenes
  • Salt state processing
  • State rendering
  • State compile
  • State runtime
  • Summarizing the state processing routines
• Salt states
  • Overview of Salt states
  • State structure vs. terminal commands
  • State language variations
  • State modules
  • Organizing states
  • Managing multiple environments
• Using Jinja with Salt
  • Salt renderers
  • Using the Jinja renderer
  • Injecting data into Salt state files
  • Jinja statements
  • Importing data
  • Templating application configuration files
  • Outputters and parsing return data
• Pillar
  • Pillar use case
  • Basics
  • Rendering pillar
  • Configuration settings
  • In-memory vs. on-demand data
  • External pillar
  • Pillar namespace
  • Pillar data merge
  • Include pillar
  • Pillar cache
  • Pillar environment
  • Jinja in pillar
  • States with pillar
• Map files
  • Use case
  • Jinja logic abstraction
  • Static lookup data
  • Alternate map rendering
  • Troubleshoot rendering

Intermediate Salt

• Beacons
  • Use case
  • Minion configuration
  • Beacon published events
  • Managing at the terminal
  • Pillar deployed beacon
  • State deployed beacon
• Reactors
  • Use case
  • Event system
  • Beacons and reactors
  • Master configuration
  • Reactor states
  • Client interfaces
  • Debugging the reactor
• Runners and orchestration
  • Salt runners
  • Salt orchestration
• State requisites and declarations
  • ID vs. name
  • State execution order
  • Requisite declarations
  • Including other SLS files
  • Extending external SLS data
  • The requisite _in declarations
  • Altering states
• Salt execution framework
  • Types of executions
  • Calling modules locally on a minion
  • The Salt command line execution
  • Salt job management
  • Running jobs on the Salt master and managing jobs
  • The event system
• Salt SSH
  • Managing systems with Salt SSH
  • Configuring the Salt SSH roster
  • Calling salt-ssh
• Troubleshooting
  • Checking process status
  • Viewing log files
  • Viewing Salt events
  • Opening ports
  • Salt keys
  • Troubleshooting states
  • Adding logging to custom modules
  • Debugging reactor states
  • Problems with sync/cache
  • Troubleshoot rendering
• Scheduler
  • Scheduling jobs
  • Managing jobs and schedules
  • Scheduling jobs from pillar
  • Managing schedules in states
• Execution architecture
  • Salt execution
  • Types of execution
  • Salt components
  • Calling modules locally on a minion
  • Return code passthrough
  • Sending jobs to the Salt master
  • The event system
  • Salt master processes
  • The Salt execution architecture
• Salt security
  • More about keys
  • The pki_dir
  • Increasing security
  • Decreasing security
  • Publisher ACLs
  • External authentication system
  • Hardening Salt