saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-16 17:50:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Remove install topics and update top nav

Browse source
This commit is contained in:
Alyssa Rock 2022-06-24 13:42:52 -06:00 • committed by Gareth J. Greenaway
parent 058379e0be
commit 76d5d0c2e3
16 changed files with 3 additions and 2382 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/_themes/saltstack2/layout.html vendored
View file

@ -158,7 +158,7 @@
<div class="collapse navbar-collapse" id="navbarCollapse">
<ul class="nav navbar-nav">
<li><a href="/en/latest/">Overview</a></li>
<li><a href="/en/getstarted/">Tutorials</a></li>
<li><a href="https://docs.saltproject.io/salt/user-guide/en/latest/">Salt User Guide</a></li>
<li><a href="/en/latest/contents.html">Documentation</a></li>
<li><a href="https://repo.saltproject.io">Downloads</a></li>
<li><a href="/en/latest/topics/development/">Develop</a></li>

69
doc/topics/installation/arch.rst
View file

@ -1,69 +0,0 @@
==========
Arch Linux
==========
Installation
============
Salt (stable) is currently available via the Arch Linux Official repositories.
There are currently -git packages available in the Arch User repositories (AUR)
as well.
Stable Release
--------------
Install Salt stable releases from the Arch Linux Official repositories as follows:
.. code-block:: bash
pacman -S salt
Tracking develop
----------------
To install the bleeding edge version of Salt (**may include bugs!**),
use the -git package. Installing the -git package as follows:
.. code-block:: bash
wget https://aur.archlinux.org/packages/sa/salt-git/salt-git.tar.gz
tar xf salt-git.tar.gz
cd salt-git/
makepkg -is
.. note:: yaourt
If a tool such as Yaourt_ is used, the dependencies will be
gathered and built automatically.
The command to install salt using the yaourt tool is:
.. code-block:: bash
yaourt salt-git
.. _Yaourt: https://aur.archlinux.org/packages.php?ID=5863
Post-installation tasks
=======================
**systemd**
Activate the Salt Master and/or Minion via ``systemctl`` as follows:
.. code-block:: bash
systemctl enable salt-master.service
systemctl enable salt-minion.service
**Start the Master**
Once you've completed all of these steps you're ready to start your Salt
Master. You should be able to start your Salt Master now using the command
seen here:
.. code-block:: bash
systemctl start salt-master
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

133
doc/topics/installation/debian.rst
View file

@ -1,133 +0,0 @@
.. _installation-debian:
===========================
Debian GNU/Linux / Raspbian
===========================
Debian GNU/Linux distribution and some derivatives such as Raspbian already
have included Salt packages to their repositories. However, current stable
Debian release contains old outdated Salt releases. It is
recommended to use SaltStack repository for Debian as described
:ref:`below <installation-debian-repo>`.
Installation from official Debian and Raspbian repositories is described
:ref:`here <installation-debian-raspbian>`.
.. _installation-debian-repo:
Installation from the Official SaltStack Repository
===================================================
Packages for Debian 10 (Buster) and Debian 9 (Stretch) are available in the
Official SaltStack repository.
Instructions are at https://repo.saltproject.io/#debian.
.. note::
Archived builds from unsupported branches:
- `Archive 1 <https://archive.repo.saltproject.io/py3/debian/>`__
- `Archive 2 <https://archive.repo.saltproject.io/debian/dists/>`__
If looking to use archives, the same directions from the `Debian install
directions <https://repo.saltproject.io/#debian>`__ can be used by replacing
the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the
archives. Here is an example ``sed`` command:
.. code-block:: bash
# Salt repo configurations are found in the /etc/apt/sources.list.d/salt.list directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/apt/sources.list.d/salt.list
.. warning::
Regular security support for Debian 8 ended on June 30th 2018. As a result,
3000.3 and 2019.2.5 will be the last Salt releases for which Debian 8
packages are created. Debian 8 also reached LTS EOL on June 30 2020.
Regular security support for Debian 7 ended on April 25th 2016. As a result,
2016.3.1 and 2015.8.10 will be the last Salt releases for which Debian
7 packages are created. Debian 7 also reached LTS EOL on May 31 2018.
.. _installation-debian-raspbian:
Installation from the Debian / Raspbian Official Repository
===========================================================
The Debian distributions contain mostly old Salt packages
built by the Debian Salt Team. You can install Salt
components directly from Debian but it is recommended to
use the instructions above for the packages from the official
Salt repository.
On Jessie there is an option to install Salt minion from Stretch with
`python-tornado` dependency from `jessie-backports` repositories.
To install fresh release of Salt minion on Jessie:
#. Add `jessie-backports` and `stretch` repositories:
**Debian**:
.. code-block:: bash
echo 'deb http://httpredir.debian.org/debian jessie-backports main' >> /etc/apt/sources.list
echo 'deb http://httpredir.debian.org/debian stretch main' >> /etc/apt/sources.list
**Raspbian**:
.. code-block:: bash
echo 'deb http://archive.raspbian.org/raspbian/ stretch main' >> /etc/apt/sources.list
#. Make Jessie a default release:
.. code-block:: bash
echo 'APT::Default-Release "jessie";' > /etc/apt/apt.conf.d/10apt
#. Install Salt dependencies:
**Debian**:
.. code-block:: bash
apt-get update
apt-get install python-zmq python-systemd/jessie-backports python-tornado/jessie-backports salt-common/stretch
**Raspbian**:
.. code-block:: bash
apt-get update
apt-get install python-zmq python-tornado/stretch salt-common/stretch
#. Install Salt minion package from Latest Debian Release:
.. code-block:: bash
apt-get install salt-minion/stretch
.. _debian-install-pkgs:
Install Packages
================
Install the Salt master, minion or other packages from the repository with
the `apt-get` command. These examples each install one of Salt components, but
more than one package name may be given at a time:
- ``apt-get install salt-api``
- ``apt-get install salt-cloud``
- ``apt-get install salt-master``
- ``apt-get install salt-minion``
- ``apt-get install salt-ssh``
- ``apt-get install salt-syndic``
.. _debian-config:
Post-installation tasks
=======================
Now, go to the :ref:`Configuring Salt <configuring-salt>` page.

154
doc/topics/installation/eos.rst
View file

@ -1,154 +0,0 @@
=========================================
Arista EOS Salt minion installation guide
=========================================
The Salt minion for Arista EOS is distributed as a SWIX extension and can be installed directly on the switch. The EOS network operating system is based on old Fedora distributions and the installation of the ``salt-minion`` requires backports. This SWIX extension contains the necessary backports, together with the Salt basecode.
.. note::
This SWIX extension has been tested on Arista DCS-7280SE-68-R, running EOS 4.17.5M and vEOS 4.18.3F.
Important Notes
===============
This package is in beta, make sure to test it carefully before running it in production.
If confirmed working correctly, please report and add a note on this page with the platform model and EOS version.
If you want to uninstall this package, please refer to the uninstalling_ section.
Installation from the Official SaltStack Repository
===================================================
Download the swix package and save it to flash.
.. code-block:: bash
veos#copy https://salt-eos.netops.life/salt-eos-latest.swix flash:
veos#copy https://salt-eos.netops.life/startup.sh flash:
Install the Extension
=====================
Copy the Salt package to extension
.. code-block:: bash
veos#copy flash:salt-eos-latest.swix extension:
Install the SWIX
.. code-block:: bash
veos#extension salt-eos-latest.swix force
Verify the installation
.. code-block:: bash
veos#show extensions | include salt-eos
salt-eos-2017-07-19.swix 1.0.11/1.fc25 A, F 27
Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER)
.. code-block:: bash
veos#bash vi /mnt/flash/startup.sh
Make sure you enable the eAPI with unix-socket
.. code-block:: console
veos(config)#management api http-commands
protocol unix-socket
no shutdown
Post-installation tasks
=======================
Generate Keys and host record and start Salt minion
.. code-block:: bash
veos#bash
#sudo /mnt/flash/startup.sh
``salt-minion`` should be running
Copy the installed extensions to boot-extensions
.. code-block:: bash
veos#copy installed-extensions boot-extensions
Apply event-handler to let EOS start salt-minion during boot-up
.. code-block:: console
veos(config)#event-handler boot-up-script
trigger on-boot
action bash sudo /mnt/flash/startup.sh
For more specific installation details of the ``salt-minion``, please refer to :ref:`Configuring Salt<configuring-salt>`.
.. _uninstalling:
Uninstalling
============
If you decide to uninstall this package, the following steps are recommended for safety:
1. Remove the extension from boot-extensions
.. code-block:: bash
veos#bash rm /mnt/flash/boot-extensions
2. Remove the extension from extensions folder
.. code-block:: bash
veos#bash rm /mnt/flash/.extensions/salt-eos-latest.swix
2. Remove boot-up script
.. code-block:: console
veos(config)#no event-handler boot-up-script
Additional Information
======================
This SWIX extension contains the following RPM packages:
.. code-block:: text
libsodium-1.0.11-1.fc25.i686.rpm
libstdc++-6.2.1-2.fc25.i686.rpm
openpgm-5.2.122-6.fc24.i686.rpm
python-Jinja2-2.8-0.i686.rpm
python-PyYAML-3.12-0.i686.rpm
python-babel-0.9.6-5.fc18.noarch.rpm
python-backports-1.0-3.fc18.i686.rpm
python-backports-ssl_match_hostname-3.4.0.2-1.fc18.noarch.rpm
python-backports_abc-0.5-0.i686.rpm
python-certifi-2016.9.26-0.i686.rpm
python-chardet-2.0.1-5.fc18.noarch.rpm
python-crypto-1.4.1-1.noarch.rpm
python-crypto-2.6.1-1.fc18.i686.rpm
python-futures-3.1.1-1.noarch.rpm
python-jtextfsm-0.3.1-0.noarch.rpm
python-kitchen-1.1.1-2.fc18.noarch.rpm
python-markupsafe-0.18-1.fc18.i686.rpm
python-msgpack-python-0.4.8-0.i686.rpm
python-napalm-base-0.24.3-1.noarch.rpm
python-napalm-eos-0.6.0-1.noarch.rpm
python-netaddr-0.7.18-0.noarch.rpm
python-pyeapi-0.7.0-0.noarch.rpm
python-salt-2017.7.0_1414_g2fb986f-1.noarch.rpm
python-singledispatch-3.4.0.3-0.i686.rpm
python-six-1.10.0-0.i686.rpm
python-tornado-4.4.2-0.i686.rpm
python-urllib3-1.5-7.fc18.noarch.rpm
python2-zmq-15.3.0-2.fc25.i686.rpm
zeromq-4.1.4-5.fc25.i686.rpm

123
doc/topics/installation/fedora.rst
View file

@ -1,123 +0,0 @@
======
Fedora
======
Beginning with version 0.9.4, Salt has been available in the primary Fedora
repositories and `EPEL`_. It is installable using ``yum`` or ``dnf``, depending
on your version of Fedora.
.. note::
Released versions of Salt starting with ``2015.5.2`` through ``2016.3.2``
do not have Fedora packages available though `EPEL`_. To install a version
of Salt within this release array, please use SaltStack's `Bootstrap Script`_
and use the git method of installing Salt using the version's associated
release tag.
Release ``2016.3.3`` and onward will have packaged versions available via
`EPEL`_.
**WARNING**: Fedora 19 comes with systemd 204. Systemd has known bugs fixed in
later revisions that prevent the salt-master from starting reliably or opening
the network connections that it needs to. It's not likely that a salt-master
will start or run reliably on any distribution that uses systemd version 204 or
earlier. Running salt-minions should be OK.
Installation
============
Salt can be installed using ``yum`` and is available in the standard Fedora
repositories.
Stable Release
--------------
Salt is packaged separately for the minion and the master. It is necessary only to
install the appropriate package for the role the machine will play. Typically, there
will be one master and multiple minions.
.. code-block:: bash
yum install salt-master
yum install salt-minion
Installing from ``updates-testing``
-----------------------------------
When a new Salt release is packaged, it is first admitted into the
``updates-testing`` repository, before being moved to the stable repo.
To install from ``updates-testing``, use the ``enablerepo`` argument for yum:
.. code-block:: bash
yum --enablerepo=updates-testing install salt-master
yum --enablerepo=updates-testing install salt-minion
Installation Using pip
======================
Since Salt is on `PyPI`_, it can be installed using pip, though most users
prefer to install using a package manager.
Installing from pip has a few additional requirements:
* Install the group 'Development Tools', ``dnf groupinstall 'Development Tools'``
* Install the 'zeromq-devel' package if it fails on linking against that
afterwards as well.
A pip install does not make the init scripts or the /etc/salt directory, and you
will need to provide your own systemd service unit.
Installation from pip:
.. code-block:: bash
pip install salt
.. warning::
If installing from pip (or from source using ``setup.py install``), be
advised that the ``yum-utils`` package is needed for Salt to manage
packages. Also, if the Python dependencies are not already installed, then
you will need additional libraries/tools installed to build some of them.
More information on this can be found :ref:`here
<installing-for-development>`.
Post-installation tasks
=======================
**Master**
To have the Master start automatically at boot time:
.. code-block:: bash
systemctl enable salt-master.service
To start the Master:
.. code-block:: bash
systemctl start salt-master.service
**Minion**
To have the Minion start automatically at boot time:
.. code-block:: bash
systemctl enable salt-minion.service
To start the Minion:
.. code-block:: bash
systemctl start salt-minion.service
Now go to the :ref:`Configuring Salt<configuring-salt>` page.
.. _`Bootstrap Script`: https://github.com/saltstack/salt-bootstrap
.. _`EPEL`: https://fedoraproject.org/wiki/EPEL
.. _`PyPI`: https://pypi.org/project/salt/

83
doc/topics/installation/freebsd.rst
View file

@ -1,83 +0,0 @@
.. meta::
:description: How do you install Salt on FreeBSD?
:keywords: freebsd
=======
FreeBSD
=======
Installation
============
Salt is available in the FreeBSD ports tree at `sysutils/py-salt
<https://www.freshports.org/sysutils/py-salt/>`_.
FreeBSD binary repo
===================
Install Salt on FreeBSD via the official package repository. Salt is packaged
with whichever Python version is currently the `default on FreeBSD <https://cgit.freebsd.org/ports/tree/Mk/bsd.default-versions.mk>`_.
Python 3.8 is currently default, install from packages like this:
.. code-block:: bash
pkg install py38-salt
FreeBSD ports
=============
Installation from ports:
.. code-block:: bash
cd /usr/ports/sysutils/py-salt
make install
Python 3.7 can be used by setting default Python version to 3.7:
.. code-block:: text
echo "DEFAULT_VERSIONS+= python=3.7" >> /etc/make.conf
Post-installation tasks
=======================
**rc.conf**
Activate the Salt Master in ``/etc/rc.conf``:
.. code-block:: bash
sysrc salt_master_enable="YES"
**Start the Master**
Start the Salt Master as follows:
.. code-block:: bash
service salt_master start
**rc.conf**
Activate the Salt Minion in ``/etc/rc.conf``:
.. code-block:: bash
sysrc salt_minion_enable="YES"
**Start the Minion**
Start the Salt Minion as follows:
.. code-block:: bash
service salt_minion start
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

14
doc/topics/installation/gentoo.rst
View file

@ -1,14 +0,0 @@
======
Gentoo
======
Salt can be easily installed on Gentoo via Portage:
.. code-block:: bash
emerge app-admin/salt
Post-installation tasks
=======================
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

195
doc/topics/installation/index.rst
View file

@ -3,197 +3,6 @@
============
Installation
============
This section contains instructions to install Salt. If you are setting up your
environment for the first time, you should install a Salt master on
a dedicated management server or VM, and then install a Salt minion on each
system that you want to manage using Salt. For now you don't need to worry
about your :ref:`architecture <architecture-overview>`, you can easily add
components and modify your configuration later without needing to reinstall
anything.
The general installation process is as follows:
1. Install a Salt master using the instructions for your platform or by running
the Salt bootstrap script. If you use the bootstrap script, be sure to
include the ``-M`` option to install the Salt master.
2. Make sure that your Salt minions can :ref:`find the Salt master
<master-dns>`.
3. Install the Salt minion on each system that you want to manage.
4. Accept the Salt :ref:`minion keys <using-salt-key>` after the Salt minion
connects.
After this, you should be able to run a simple command and receive salt version returns from
all connected Salt minions.
.. code-block:: bash
salt '*' test.version
Quick Install
-------------
On most distributions, you can set up a **Salt Minion** with the
:ref:`Salt bootstrap <salt-bootstrap>`.
Platform-specific Installation Instructions
-------------------------------------------
These guides go into detail how to install Salt on a given platform.
.. toctree::
:maxdepth: 1
arch
debian
eos
fedora
freebsd
gentoo
nxos
openbsd
osx
rhel
solaris
ubuntu
windows
suse
Initial Configuration
---------------------
.. toctree::
:maxdepth: 1
../../ref/configuration/index
Additional Installation Guides
------------------------------
.. toctree::
:maxdepth: 1
../tutorials/salt_bootstrap
../tutorials/firewall
../tutorials/preseed_key
../tutorials/walkthrough_macosx
../tutorials/rooted
../tutorials/standalone_minion
../tutorials/quickstart
.. _installation-dependencies:
Dependencies
------------
Salt should run on any Unix-like platform so long as the dependencies are met.
* `Python`_ - Python2 >= 2.7, Python3 >= 3.4
* `msgpack`_ - High-performance message interchange format
* `YAML`_ - Python YAML bindings
* `Jinja2`_ - parsing Salt States (configurable in the master settings)
* `MarkupSafe`_ - Implements a XML/HTML/XHTML Markup safe string for Python
* `apache-libcloud`_ - Python lib for interacting with many of the popular
cloud service providers using a unified API
* `Requests`_ - HTTP library
* `Tornado`_ - Web framework and asynchronous networking library
* `futures`_ - Python2 only dependency. Backport of the concurrent.futures package from Python 3.2
* ZeroMQ:
* `ZeroMQ`_ >= 3.2.0
* `pyzmq`_ >= 2.2.0 - ZeroMQ Python bindings
* `PyCrypto`_ - The Python cryptography toolkit
.. warning::
For historical reasons, Salt requires PyCrypto as a "lowest common
denominator". However, `PyCrypto is unmaintained`_ and best practice is to
manually upgrade to use a more maintained library such as `PyCryptodome`_. See
`Issue #52674`_ and `Issue #54115`_ for more info
.. _PyCrypto is unmaintained: https://github.com/dlitz/pycrypto/issues/301#issue-551975699
.. _PyCryptodome: https://pypi.org/project/pycryptodome/
.. _Issue #52674: https://github.com/saltstack/salt/issues/52674
.. _Issue #54115: https://github.com/saltstack/salt/issues/54115
Salt defaults to the `ZeroMQ`_ transport. The ``--salt-transport`` installation
option is available, but currently only supports the ``zeromq`` option. This
may be expanded in the future.
.. code-block:: bash
python setup.py --salt-transport=zeromq install
This way, only the required dependencies are pulled by the setup script if need
be.
If installing using pip, the ``--salt-transport`` install option can be
provided like:
.. code-block:: bash
pip install --install-option="--salt-transport=zeromq" salt
.. note::
Salt does not bundle dependencies that are typically distributed as part of
the base OS. If you have unmet dependencies and are using a custom or
minimal installation, you might need to install some additional packages
from your OS vendor.
Optional Dependencies
---------------------
* `mako`_ - an optional parser for Salt States (configurable in the master
settings)
* gcc - dynamic `Cython`_ module compiling
.. _`Python`: https://www.python.org/downloads/
.. _`ZeroMQ`: https://zeromq.org/
.. _`pyzmq`: https://github.com/zeromq/pyzmq
.. _`msgpack`: https://pypi.python.org/project/msgpack/
.. _`M2Crypto`: https://gitlab.com/m2crypto/m2crypto
.. _`PyCrypto`: https://www.dlitz.net/software/pycrypto/
.. _`YAML`: https://pyyaml.org/
.. _`Jinja2`: https://jinja.palletsprojects.com/en/2.11.x/
.. _`MarkupSafe`: https://pypi.org/project/MarkupSafe/
.. _`mako`: https://www.makotemplates.org/
.. _`Cython`: https://cython.org/
.. _`apache-libcloud`: http://libcloud.apache.org
.. _`Requests`: http://docs.python-requests.org/en/latest
.. _`Tornado`: http://www.tornadoweb.org/en/stable/
.. _`futures`: https://github.com/agronholm/pythonfutures
Upgrading Salt
--------------
When upgrading Salt, the master(s) should always be upgraded first. Backward
compatibility for minions running newer versions of salt than their masters is
not guaranteed.
Whenever possible, backward compatibility between new masters and old minions
will be preserved. Generally, the only exception to this policy is in case of
a security vulnerability.
.. seealso::
:ref:`Installing Salt for development <installing-for-development>` and
contributing to the project.
Building Packages using Salt Pack
---------------------------------
Salt-pack is an open-source package builder for most commonly used Linux
platforms, for example: Redhat/CentOS and Debian/Ubuntu families, utilizing
SaltStack states and execution modules to build Salt and a specified set of
dependencies, from which a platform specific repository can be built.
https://github.com/saltstack/salt-pack
See the `Salt Install Guide <https://docs.saltproject.io/salt/install-guide/en/latest/>`_
for the current installation instructions.

410
doc/topics/installation/nxos.rst
View file

@ -1,410 +0,0 @@
============================================================
Cisco Nexus Salt Minion Installation and Configuration Guide
============================================================
This document describes the Salt Minion installation and configuration on Cisco Nexus switches. These instructions detail the process for managing the Nexus switches using a Proxy Minion or Native Minion on platforms that have GuestShell support.
.. contents:: Table of Contents
Pre-Install Tasks
=================
STEP 1: Verify Platform and Software Version Support
----------------------------------------------------
The following platforms and software versions have been certified to work with this version of Salt.
.. table:: Platform / Software Minimum Requirements
:widths: auto
:align: center
=================== ===================== ================ =================== =================
Supported Platforms Minimum NX-OS Version SSH Proxy Minion NX-API Proxy Minion GuestShell Minion
=================== ===================== ================ =================== =================
Cisco Nexus N3k 7.0(3)I2(5) and later Supported Supported Supported
Cisco Nexus N9k 7.0(3)I2(5) and later Supported Supported Supported
Cisco Nexus N6k 7.3(0)N1(1) and later Supported Not Supported Not Supported
Cisco Nexus N7k 7.3(0)D1(1) and later Supported Supported Not Supported
=================== ===================== ================ =================== =================
.. table:: Platform Models
:widths: auto
:align: center
======== ===========
Platform Description
======== ===========
N3k Support includes N30xx, N31xx, N32xx and N35xx models
N6k Support includes all N6xxx models
N7k Support includes all N7xxx models
N9k Support includes all N9xxx models
======== ===========
STEP 2: Choose Salt Minion Type
-------------------------------
Using the tables above, select the Salt Minion type.
Choices:
* ``SSH`` Proxy Minion (See `Salt Proxy Minion Configuration`_ Section)
* ``NX-API`` Proxy Minion (See `Salt Proxy Minion Configuration`_ Section)
* ``GuestShell`` Native Minion (See `GuestShell Salt Minion Installation`_ Section)
* Some platforms support a native minion installed directly on the NX-OS device inside the GuestShell
* The GuestShell is a secure Linux container environment running CentOS
STEP 3: Network Connectivity
----------------------------
Ensure that IP reachability exists between the NX-OS Salt Minion device and the SaltStack Master.
**Note:** The management interface exists in a separate VRF context and requires additional configuration as shown.
Example: Nexus CLI Configuration for connectivity via management interface
.. code:: bash
config term
vrf context management
ip name-server 10.0.0.202
ip domain-name mycompany.com
ip route 0.0.0.0/0 10.0.0.1
interface mgmt0
vrf member management
ip address 10.0.0.99/24
ntp server 10.0.0.201 use-vrf management
end
Salt Proxy Minion Configuration
===============================
Here is a sample Proxy Minion directory structure
.. code:: bash
saltmaster:/srv/pillar$tree
.
├── n3k-proxy.sls
├── n7k-proxy.sls
└── top.sls
This displays a top sls file and two proxy minion sls files for a Nexus 3k and Nexus 7k device.
Sample contents for the ``top.sls`` file.
.. code:: yaml
saltmaster:/srv/pillar$cat top.sls
base:
n3k-proxy:
- n3k-proxy
n7k-proxy:
- n7k-proxy
Proxy Minion Pillar Data
------------------------
Here is a sample Proxy Minion pillar data file.
All of the data for both ssh and nxapi proxy minion types can be stored in the same pillar data file. To choose ``ssh`` or ``nxapi``, simply set the ``connection:`` parameter accordingly.
.. code:: yaml
saltmaster:/srv/pillar$cat n7k-proxy.sls
proxy:
proxytype: nxos
# Specify ssh or nxapi connection type (default is ssh)
#connection: ssh
connection: nxapi
# Parameters Common to both SSH and NX-API
host: n7k.example.com
username: admin
password: password
# SSH Parameters
prompt_name: n7k
ssh_args: '-o PubkeyAuthentication=no'
key_accept: True
# NX-API Parameters
transport: https
port: 443
verify: False
# Option to prevent auto-save after each configuration command.
# Setting this to True will improve performance when using
# nxos execution module functions to configure the device.
no_save_config: True
* For the most current nxos proxy minion configuration options, See :mod:`salt.proxy.nxos <salt.proxy.nxos>`
* For the most current list of nxos execution module functions, See :mod:`salt.modules.nxos<salt.modules.nxos>`
GuestShell Salt Minion Installation
===================================
This section is only required when running the SaltStack Minion from the ``guestshell``.
STEP 1a: Enable the Guestshell on low footprint N3ks
----------------------------------------------------
**NOTE:** Skip down to **STEP 1b** if the target system is not a low footprint N3k.
Nexus 3xxx switches with 4 GB RAM and 1.6 GB bootflash are advised to use compacted images to reduce the storage resources consumed by the image. As part of the compaction process, the ``guestshell.ova`` is removed from the system image. To make use of the guestshell on these systems, the guestshell.ova may be downloaded and used to install the guestshell.
Guestshell OVA Download Link_
.. _Link: https://software.cisco.com/download/home/283970187/type/282088129/release/9.2%25281%2529?catid=268438038
Starting in release ``9.2(1)`` and onward, the .ova file can be copied to the ``volatile:`` directory which frees up more space on ``bootflash:``.
Copy the ``guestshell.ova`` file to ``volatile:`` if supported, otherwise copy it to ``bootflash:``
.. code-block:: console
n3xxx# copy scp://admin@1.2.3.4/guestshell.ova volatile: vrf management
guestshell.ova 100% 55MB 10.9MB/s 00:05
Copy complete, now saving to disk (please wait)...
Copy complete.
Use the ``guestshell enable`` command to install and enable guestshell.
.. code-block:: console
n3xxx# guestshell enable package volatile:guestshell.ova
STEP 1b: Enable the Guestshell
------------------------------
The ``guestshell`` container environment is enabled by default on most platforms; however, the default disk and memory resources allotted to guestshell are typically too small to support SaltStack Minion requirements. The resource limits may be increased with the NX-OS CLI ``guestshell resize`` commands as shown below.
.. table:: Resource Requirements
:widths: auto
:align: center
=================== =====================
Resource Recommended
=================== =====================
Disk **1000 MB**
Memory **350 MB**
=================== =====================
``show guestshell detail`` displays the current resource limits:
.. code:: bash
n3k# show guestshell detail
Virtual service guestshell+ detail
State : Activated
...
Resource reservation
Disk : 150 MB
Memory : 128 MB
``guestshell resize rootfs`` sets disk size limits while ``guestshell resize memory`` sets memory limits. The resize commands do not take effect until after the guestshell container is (re)started by ``guestshell reboot`` or ``guestshell enable``.
**Example.** Allocate resources for guestshell by setting new limits to 1000MB disk and 350MB memory.
.. code:: console
n3k# guestshell resize rootfs 1000
n3k# guestshell resize memory 350
n3k# guestshell reboot
Are you sure you want to reboot the guest shell? (y/n) [n] y
STEP 2: Set Up Guestshell Network
---------------------------------
The ``guestshell`` is an independent CentOS container that does not inherit settings from NX-OS.
* Use ``guestshell`` to enter the guestshell environment, then become root.
* *Optional:* Use ``chvrf`` to specify a vrf namespace; e.g. ``sudo chvrf management``
.. code:: bash
n3k# guestshell
[guestshell@guestshell ~]$ sudo su - # Optional: sudo chvrf management
[root@guestshell guestshell]#
**OPTIONAL: Add DNS Configuration**
.. code:: bash
[root@guestshell guestshell]# cat >> /etc/resolv.conf << EOF
nameserver 10.0.0.202
domain mycompany.com
EOF
**OPTIONAL: Define proxy server variables if needed to allow network access to SaltStack package repositories**
.. code:: console
export http_proxy=http://proxy.yourdomain.com:<port>
export https_proxy=https://proxy.yourdomain.com:<port>
STEP 3: Install SaltStack Minion
---------------------------------
Install the ``python3`` and ``python3-pip`` packages.
``[root@guestshell guestshell]# yum install python3 python3-pip``
**OPTIONAL: Upgrade the pip installer**
``[root@guestshell guestshell]# pip3 install --upgrade pip``
Install the ``certifi`` python package.
``[root@guestshell guestshell]# pip3 install certifi``
The most current information on installing the SaltStack Minion in a CentOS 7 environment can be found here_
.. _here: https://repo.saltproject.io/#rhel
Information from the install guide is provided here for convenience.
Run the following commands to install the SaltStack repository and key:
.. code:: bash
[root@guestshell guestshell]# rpm --import https://repo.saltproject.io/py3/redhat/7/x86_64/latest/SALTSTACK-GPG-KEY.pub
[root@guestshell guestshell]# curl -fsSL https://repo.saltproject.io/py3/redhat/7/x86_64/latest.repo | tee /etc/yum.repos.d/salt.repo
Run the following command to force yum to revalidate the cache for each repository.
``[root@guestshell guestshell]# yum clean expire-cache``
Install the Salt Minion.
``[root@guestshell guestshell]# yum install salt-minion``
STEP 4: Configure SaltStack Minion
----------------------------------
Make the following changes to the ``/etc/salt/minion`` configuration file in the NX-OS GuestShell.
Change the ``master:`` directive to point to the SaltStack Master.
.. code:: diff
- #master: salt
+ master: saltmaster.example.com
Change the ``id:`` directive to easily identify the minion running in the GuestShell.
Example:
.. code:: diff
- #id: salt
+ id: n3k-guestshell-minion
Start the Minion in the Guestshell and accept the key on the SaltStack Master.
``[root@guestshell ~]# systemctl start salt-minion``
.. code:: bash
saltmaster: salt-key -L
Accepted Keys:
Denied Keys:
Unaccepted Keys:
n3k-guestshell-minion
Rejected Keys:
.. code:: bash
saltmaster: salt-key -A
The following keys are going to be accepted:
Unaccepted Keys:
n3k-guestshell-minion
Proceed? [n/Y] Y
Key for minion n3k-guestshell-minion accepted.
Ping the SaltStack Minion running in the Guestshell.
.. code:: bash
saltmaster: salt n3k-guestshell-minion nxos.ping
n3k-guestshell-minion:
True
GuestShell Salt Minion Persistence
===================================
This section documents SaltStack Minion persistence in the ``guestshell`` after system restarts and high availability switchovers.
The ``guestshell`` container does not automatically sync filesystem changes from the active processor to the standby processor. This means that SaltStack Minion installation files and related file changes will not be present on the standby until they are manually synced with the following NX-OS exec command:
``guestshell sync``
The ``guestshell`` environment uses **systemd** for service management. The SaltStack Minion provides a generic systemd script when installed, but a slight modification as shown below is needed for nodes that run Salt in the management (or other vrf) namespace:
.. code:: diff
--- /usr/lib/systemd/system/salt-minion.service.old
+++ /usr/lib/systemd/system/salt-minion.service
[Unit]
Description=The Salt Minion
Documentation=man:salt-minion(1) file:///usr/share/doc/salt/html/contents.html
https://docs.saltproject.io/en/latest/contents.html
After=network.target salt-master.service
[Service]
KillMode=process
Type=notify
NotifyAccess=all
LimitNOFILE=8192
- ExecStart=/usr/bin/salt-minion
+ ExecStart=/bin/nsenter --net=/var/run/netns/management -- /usr/bin/salt-minion
[Install]
WantedBy=multi-user.target
Change the ``pidfile:`` directive to point to the ``/run`` ``tmpfs`` location in the GuestShell.
.. code:: diff
- #pidfile: /var/run/salt-minion.pid
+ pidfile: /run/salt-minion.pid
Next, enable the SaltStack Minion systemd service (the ``enable`` command adds it to systemd for autostarting on the next boot) and optionally start it now:
.. code:: bash
systemctl enable salt-minion
systemctl start salt-minion
References
==========
.. table:: Nexus Document References
:widths: auto
:align: center
=================== =====================
References Description
=================== =====================
GuestShell_N9k_ N9k Guestshell Programmability Guide
GuestShell_N3k_ N3k Guestshell Programmability Guide
=================== =====================
.. _Guestshell_N9k: https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus9000/sw/9-x/programmability/guide/b_Cisco_Nexus_9000_Series_NX-OS_Programmability_Guide_9x/b_Cisco_Nexus_9000_Series_NX-OS_Programmability_Guide_9x_chapter_0100.html
.. _GuestShell_N3k: https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus3000/sw/programmability/9_x/b_Cisco_Nexus_3000_Series_NX-OS_Programmability_Guide_9x/b_Cisco_Nexus_3000_Series_NX-OS_Programmability_Guide_9x_chapter_0101.html

64
doc/topics/installation/openbsd.rst
View file

@ -1,64 +0,0 @@
=======
OpenBSD
=======
Salt was added to the OpenBSD ports tree on Aug 10th 2013.
It has been tested on OpenBSD 5.5 onwards.
Salt is dependent on the following additional ports. These will be installed as
dependencies of the ``sysutils/salt`` port:
.. code-block:: text
devel/py3-progressbar
net/py3-msgpack
net/py3-zmq
security/py3-Cryptodome
security/py3-M2Crypto
sysutils/py3-distro
textproc/py3-MarkupSafe
textproc/py3-yaml
www/py3-jinja2
www/py3-requests
Installation
============
To install Salt from the OpenBSD package repo, use the command:
.. code-block:: bash
pkg_add salt
Post-installation tasks
=======================
**Master**
To have the Master start automatically at boot time:
.. code-block:: bash
rcctl enable salt_master
To start the Master:
.. code-block:: bash
rcctl start salt_master
**Minion**
To have the Minion start automatically at boot time:
.. code-block:: bash
rcctl enable salt_minion
To start the Minion:
.. code-block:: bash
rcctl start salt_minion
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

163
doc/topics/installation/osx.rst
View file

@ -1,163 +0,0 @@
.. _macos-installation:
=====
macOS
=====
Installation from the Official SaltStack Repository
===================================================
**Latest stable build from the selected branch**: |osxdownloadpy3|
The output of ``md5 <salt pkg>`` should match the contents of the corresponding
md5 file.
.. note::
- `Earlier builds from supported branches
<https://repo.saltproject.io/osx/>`__
- `Archived builds from unsupported branches
<https://archive.repo.saltproject.io/osx/>`__
To install Salt using the package, download and double-click the downloaded
file. Follow the instructions in the installer.
Configuration
-------------
salt-config cli tool
^^^^^^^^^^^^^^^^^^^^
The Salt Package includes the ``salt-config.sh`` script for configuring Salt
after it has been installed. The script is located in the ``/opt/salt/bin``
directory. A symlink to that file is created in ``/usr/local/sbin``. If
``/usr/local/sbin`` is part of the path you can type the following in a bash
shell to get config options.
.. code-block:: bash
salt-config --help
.. note::
If ``/usr/local/sbin`` is not in the path, you can either add it to the
path, or navigate to ``/usr/local/sbin`` or ``/opt/salt/bin`` to run the
``salt-config`` script.
There are two configuration options that allow you to set the master and minion
ID. They are as follows:
=============== =====================================
Option Description
=============== =====================================
-i, --minion-id The ID to assign this minion
-m, --master The hostname/IP address of the master
-h, --help Display this help message
=============== =====================================
To set the master and minion ID after installation, run the following command:
.. code-block:: bash
sudo salt-config -i mac_minion -m master.apple.com
sudo salt-config --minion-id mac_minion --master 10.10.1.10
sample configs
^^^^^^^^^^^^^^
The installer places sample config files in the ``/etc/salt`` directory named
``master.dist`` and ``minion.dist``. You can make a copy of one of these files,
remove the ``.dist`` file extension, and edit as you see fit. Restart the minion
or master service to pick up the changes.
Detailed configuration options can be found at:
- `Configuring the Salt minion
<https://docs.saltproject.io/en/latest/ref/configuration/minion.html>`__
- `Configuring the Salt master
<https://docs.saltproject.io/en/latest/ref/configuration/master.html>`__
Installation from Homebrew
==========================
.. code-block:: bash
brew install saltstack
It should be noted that Homebrew explicitly discourages the `use of sudo`_:
Homebrew is designed to work without using sudo. You can decide to use it
but we strongly recommend not to do so. If you have used sudo and run into a
bug then it is likely to be the cause. Please don't file a bug report unless
you can reproduce it after reinstalling Homebrew from scratch without using
sudo
.. _use of sudo: https://docs.brew.sh/FAQ#why-does-homebrew-say-sudo-is-bad
Installation from MacPorts
==========================
Macports isolates its dependencies from the OS, and installs Salt in
``/opt/local`` by default, with config files under ``/opt/local/etc/salt``. For
best results, add ``/opt/local/bin`` to your PATH.
.. code-block:: bash
sudo port install salt
Variants allow selection of the python version used to run Salt. Supported
versions are python35, python36, python37, and python38. To install Salt
with Python 3.6, use the python36 variant, for example:
.. code-block:: bash
sudo port install salt @python36
Startup items (for master, minion, and rest-cherrypy API gateway, respectively)
are installed by subport targets. These will register launchd LaunchDaemons as
org.macports.salt-minion, for example, to trigger automatic startup of the
salt-minion through launchd. LaunchDaemons for Salt can be started and stopped
without reboot using the macprots load and unload commands.
.. code-block:: bash
sudo port install salt-master salt-minion salt-api
sudo port load salt-master salt-minion salt-api
Installation from Pip
=====================
When only using the macOS system's pip, install this way:
.. code-block:: bash
sudo pip install salt
Salt-Master Customizations
==========================
.. note::
Salt master on macOS is not tested or supported by SaltStack. See
`SaltStack Platform Support <https://saltstack.com/product-support-lifecycle/>`_
for more information.
To run salt-master on macOS, add this configuration option to the
``/etc/salt/master`` file:
.. code-block:: bash
max_open_files: 8192
Now the salt-master should run without errors:
.. code-block:: bash
sudo salt-master --log-level=all
Post-installation tasks
=======================
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

179
doc/topics/installation/rhel.rst
View file

@ -1,179 +0,0 @@
.. _installation-rhel:
==============================================================
RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux
==============================================================
.. _installation-rhel-repo:
Salt should work properly with all mainstream derivatives of Red Hat Enterprise
Linux, including CentOS, Scientific Linux, Oracle Linux, and Amazon Linux.
Report any bugs or issues on the `issue tracker
<https://github.com/saltstack/salt/issues>`__.
Installation from the Official Salt Project Repository
======================================================
Packages for Redhat, CentOS, and Amazon Linux are available in
the Salt Project Repository.
- `Red Hat / CentOS <https://repo.saltproject.io/#rhel>`_
- `Amazon Linux <https://repo.saltproject.io/#amzn>`_
.. note::
Archived builds from unsupported branches:
**Red Hat / CentOS**
- `Archive 1 <https://archive.repo.saltproject.io/py3/redhat/>`__
- `Archive 2 <https://archive.repo.saltproject.io/yum/redhat/>`__
If looking to use archives, the same directions from the `RHEL/CentOS
install directions <https://repo.saltproject.io/#rhel>`__ can be used by
replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the
archives. Here is an example ``sed`` command:
.. code-block:: bash
# Salt repo configurations are found in the /etc/yum.repos.d/ directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/yum.repos.d/salt*.repo
**Amazon Linux**
- `Archive 1 <https://archive.repo.saltproject.io/py3/amazon/>`__
- `Archive 2 <https://archive.repo.saltproject.io/yum/amazon/>`__
If looking to use archives, the same directions from the `Amazon
install directions <https://repo.saltproject.io/#amzn>`__ can be used by
replacing the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the
archives. Here is an example ``sed`` command:
.. code-block:: bash
# Salt repo configurations are found in the /etc/yum.repos.d/ directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/yum.repos.d/salt*.repo
.. note::
As of 2015.8.0, EPEL repository is no longer required for installing on
RHEL systems. Salt Project repository provides all needed dependencies.
.. warning::
If installing on Red Hat Enterprise Linux 7 with disabled (not subscribed on)
'RHEL Server Releases' or 'RHEL Server Optional Channel' repositories,
append CentOS 7 GPG key URL to Salt Project yum repository configuration to
install required base packages:
.. code-block:: cfg
[saltstack-repo]
name=Salt repo for Red Hat Enterprise Linux $releasever
baseurl=https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest
enabled=1
gpgcheck=1
gpgkey=https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest/SALTSTACK-GPG-KEY.pub
https://repo.saltproject.io/py3/redhat/$releasever/$basearch/latest/base/RPM-GPG-KEY-CentOS-7
.. note::
``systemd`` and ``systemd-python`` are required by Salt, but are not
installed by the Red Hat 7 ``@base`` installation or by the Salt
installation. These dependencies might need to be installed before Salt.
Installation Using pip
======================
Since Salt is on `PyPI`_, it can be installed using pip, though most users
prefer to install using RPM packages (which can be installed by following
the directions in the :ref:`Salt Repository <installation-rhel-repo>`).
Installing from pip has a few additional requirements:
* Install the group 'Development Tools', ``yum groupinstall 'Development Tools'``
* Install the 'zeromq-devel' package if it fails on linking against that
afterwards as well.
A pip install does not make the init scripts or the /etc/salt directory, and you
will need to provide your own systemd service unit.
Installation from pip:
.. _`PyPI`: https://pypi.org/project/salt/
.. code-block:: bash
pip install salt
.. warning::
If installing from pip (or from source using ``setup.py install``), be
advised that the ``yum-utils`` package is needed for Salt to manage
packages. Also, if the Python dependencies are not already installed, then
you will need additional libraries/tools installed to build some of them.
More information on this can be found :ref:`here
<installing-for-development>`.
ZeroMQ 4
========
We recommend using ZeroMQ 4 where available. Salt Project provides ZeroMQ 4.3.1
and ``pyzmq`` 17.0.0 in the :ref:`Salt Repository
<installation-rhel-repo>`.
If this repository is added *before* Salt is installed, then installing either
``salt-master`` or ``salt-minion`` will automatically pull in ZeroMQ 4.3.1, and
additional steps to upgrade ZeroMQ and pyzmq are unnecessary.
Package Management
==================
Salt's interface to :mod:`yum <salt.modules.yumpkg>` makes heavy use of the
**repoquery** utility, from the yum-utils_ package. If salt has
been installed using pip, or a host is being managed using salt-ssh, then as of
version 2014.7.0 yum-utils_ will be installed automatically to satisfy this
dependency.
.. _yum-utils: http://yum.baseurl.org/wiki/YumUtils
Post-installation tasks
=======================
Master
------
To have the Master start automatically at boot time:
**RHEL/CentOS 7 and 8**
.. code-block:: bash
systemctl enable salt-master.service
To start the Master:
**RHEL/CentOS 7 and 8**
.. code-block:: bash
systemctl start salt-master.service
Minion
------
To have the Minion start automatically at boot time:
**RHEL/CentOS 7 and 8**
.. code-block:: bash
systemctl enable salt-minion.service
To start the Minion:
**RHEL/CentOS 7 and 8**
.. code-block:: bash
systemctl start salt-minion.service
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

24
doc/topics/installation/solaris.rst
View file

@ -1,24 +0,0 @@
=======
Solaris
=======
Salt is known to work on Solaris but community packages are unmaintained.
It is possible to install Salt on Solaris by using `setuptools`.
For example, to install the develop version of salt:
.. code-block:: bash
git clone https://github.com/saltstack/salt
cd salt
sudo python setup.py install --force
.. note::
SaltStack does offer commercial support for Solaris which includes packages.
Packages can be found on the
`Downloads page of the Enterprise Installation Guide
<https://enterprise.saltstack.com/docs/downloads.html#aix-solaris-minions>`_
and are downloadable with a *SaltStack Enterprise* account.

135
doc/topics/installation/suse.rst
View file

@ -1,135 +0,0 @@
.. _installation-suse:
====
SUSE
====
Installation from the Official SaltStack Repository
===================================================
The SaltStack Repository has packages available for the following platforms:
- SLES 11 SP4
- SLES 12 / SLES 12 SP1 through SP4
- SLES 15
- openSUSE Leap 15.0, 15.1, 42.2, 42.3
- openSUSE Tumbleweed
Instructions are at https://repo.saltproject.io/#suse.
Installation from the SUSE Repository
=====================================
Since openSUSE 13.2, Salt has been available in the primary repositories.
With the release of SUSE manager 3 a new repository setup has been created.
The new repo will by systemsmanagement:saltstack, which is the source
for newer stable packages. For backward compatibility a linkpackage will be
created to the old devel:language:python repo.
All development of suse packages will be done in systemsmanagement:saltstack:testing.
This will ensure that salt will be in mainline suse repo's, a stable release
repo and a testing repo for further enhancements.
Installation
============
Salt can be installed using ``zypper`` and is available in the standard openSUSE/SLES
repositories.
Stable Release
--------------
Salt is packaged separately for the minion and the master. It is necessary only to
install the appropriate package for the role the machine will play. Typically, there
will be one master and multiple minions.
.. code-block:: bash
zypper install salt-master
zypper install salt-minion
Post-installation tasks openSUSE
================================
**Master**
To have the Master start automatically at boot time:
.. code-block:: bash
systemctl enable salt-master.service
To start the Master:
.. code-block:: bash
systemctl start salt-master.service
**Minion**
To have the Minion start automatically at boot time:
.. code-block:: bash
systemctl enable salt-minion.service
To start the Minion:
.. code-block:: bash
systemctl start salt-minion.service
Post-installation tasks SLES
============================
**Master**
To have the Master start automatically at boot time:
.. code-block:: bash
chkconfig salt-master on
To start the Master:
.. code-block:: bash
rcsalt-master start
**Minion**
To have the Minion start automatically at boot time:
.. code-block:: bash
chkconfig salt-minion on
To start the Minion:
.. code-block:: bash
rcsalt-minion start
Unstable Release
----------------
openSUSE
--------
For openSUSE Leap or Tumbleweed systems, run the following as root:
.. code-block:: bash
zypper install salt salt-minion salt-master
SUSE Linux Enterprise
---------------------
For SLES 15 and above run the following as root:
.. code-block:: bash
zypper install salt salt-minion salt-master
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

56
doc/topics/installation/ubuntu.rst
View file

@ -1,56 +0,0 @@
.. _installation-ubuntu:
======
Ubuntu
======
.. _installation-ubuntu-repo:
Installation from the Official SaltStack Repository
===================================================
Packages for Ubuntu 20.04 (Focal) and 18.04 (Bionic)
are available in the SaltStack repository.
Instructions are at https://repo.saltproject.io/#ubuntu.
.. note::
Archived builds from unsupported branches:
- `Archive 1 <https://archive.repo.saltproject.io/py3/ubuntu/>`__
- `Archive 2 <https://archive.repo.saltproject.io/apt/ubuntu/>`__
If looking to use archives, the same directions from the `Ubuntu install
directions <https://repo.saltproject.io/#ubuntu>`__ can be used by replacing
the URL paths with the appropriate archive location. The
repository configuration endpoint also needs to be adjusted to point to the
archives. Here is an example ``sed`` command:
.. code-block:: bash
# Salt repo configurations are found in the /etc/apt/sources.list.d/salt.list directory
sed -i 's/repo.saltproject.io/archive.repo.saltproject.io/g' /etc/apt/sources.list.d/salt.list
.. _ubuntu-install-pkgs:
Install Packages
================
Install the Salt master, minion or other packages from the repository with
the `apt-get` command. These examples each install one of Salt components, but
more than one package name may be given at a time:
- ``apt-get install salt-api``
- ``apt-get install salt-cloud``
- ``apt-get install salt-master``
- ``apt-get install salt-minion``
- ``apt-get install salt-ssh``
- ``apt-get install salt-syndic``
.. _ubuntu-config:
Post-installation tasks
=======================
Now go to the :ref:`Configuring Salt<configuring-salt>` page.

581
doc/topics/installation/windows.rst
View file

@ -1,581 +0,0 @@
.. _windows:
=======
Windows
=======
Salt has full support for running the Salt minion on Windows. You must connect
Windows Salt minions to a Salt master on a supported operating system to
control your Salt Minions.
Many of the standard Salt modules have been ported to work on Windows and many
of the Salt States currently work on Windows as well.
.. _windows-installer:
Installation from the Official SaltStack Repository
===================================================
**Latest stable build from the selected branch**:
|windownload|
The output of ``md5sum <salt minion exe>`` should match the contents of the
corresponding md5 file.
There are installers available for Python 3. Starting with Salt 3001, only
Python 3 builds of the Windows Salt Minion will be built. Python 2 builds
exist for earlier versions of Salt Minion.
.. note::
- `Earlier builds from supported branches
<https://repo.saltproject.io/windows/>`__
Archived builds from unsupported branches:
- `Archive 1 <https://archive.repo.saltproject.io/windows/>`__
- `Archive 2 <https://archive.repo.saltproject.io/windows/archive/>`__
.. note::
The installation executable installs all dependencies that the Salt minion
requires.
The 64bit and 32bit installers have been tested on Windows 8.1, Windows Server
2012 R2, Windows 10, Windows Server 2016, and Windows Server 2019. 32bit
installers have only been tested on 64bit systems. Please file a bug report on
our GitHub repo if issues for other platforms are found.
Salt Minion Installation
========================
Prerequisites and Checks
------------------------
Before the installation starts the installer does a few checks for prerequisites
and security issues.
Existing Salt Installation check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If Salt is already installed on the system the user will be prompted to remove
the previous installation. Click ``OK`` to remove the Salt binaries and related
files but leave any existing config, cache, and PKI information. Click
``Cancel`` to abort the installation before making any modifications to the
system.
Visual C++ Redistributable check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the system is missing the appropriate version of the Visual C++
Redistributable (vcredist) the user will be prompted to install it. Click ``OK``
to install the vcredist. Click ``Cancel`` to abort the installation without
making modifications to the system.
Insecure configuration check
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since existing configuration that may be present on the system can be used by
the installer to configure the minion we need to make sure it is trusted. This
is done by verifying that the owner of the ``conf`` directory is either System
or Administrators. If an insecure ``conf`` directory is found, a dialog box will
be displayed warning the user that an insecure config directory has been found.
Click ``Yes`` to rename the insecure directory and continue the installation.
Click ``No`` to abort the installation.
Installation
------------
After the Welcome and the License Agreement the user will be prompted to choose
a destination directory. Starting in version 3004, the binary data has been
separated from the configuration data. The user is allowed to choose the install
directory for Salt. The default is ``%ProgramFiles%\Salt Project\salt``. All
Salt binaries will be installed into the installation directory. Configuration
data is stored in the ``root_dir`` which has been changed from ``C:\salt`` to
``%ProgramData\Salt Project\Salt``. The ``root_dir`` can be changed from the
default by setting the ``root_dir`` value in the minion config and then
specifying that config when starting the salt minion using the ``-c`` option.
.. code-block:: bat
salt-minion -c C:\my\custom\root_dir
.. note::
If the installer finds config data in the old location, the user is prompted
to move the ``root_dir`` to the new location. The default is to leave
existing config in place.
Next the installer will gather information needed to configure the minion. There
are three config scenarios handled by the installer:
=============== ===========
Option Description
=============== ===========
Default Config A default config will be laid down and updated from the values
in the Master and Minion Name fields
Custom Config The user is allowed to choose a custom config file which will
be copied to the config directory and updated with the values
in the Master and Minion Name fields
Existing Config An existing config is found and its values are displayed in the
Master and Minion Name fields. The user is not allowed to
modify these options. This option is only present if an
existing config is found on the system.
=============== ===========
If an existing config is found in the old location (``C:\salt``), there is an
additional option to move the ``root_dir`` to the new location
(``%ProgramData%\Salt Project\Salt``). The default is to leave the ``root_dir``
unchanged.
Click the ``Install`` button to install using these settings.
The final page allows you to start the minion service and optionally change its
startup type. By default, the minion is set to ``Automatic``. You can change the
minion start type to ``Automatic (Delayed Start)`` by checking the 'Delayed
Start' checkbox.
.. note::
Highstates that require a reboot may fail after reboot because salt
continues the highstate before Windows has finished the booting process.
This can be fixed by changing the startup type to 'Automatic (Delayed
Start)'. The drawback is that it may increase the time it takes for the
'salt-minion' service to actually start.
The ``salt-minion`` service will appear in the Windows Service Manager and can
be managed there or from the command line like any other Windows service.
.. code-block:: bat
sc start salt-minion
net start salt-minion
Prerequisites
-------------
Most Salt functionality should work just fine right out of the box. A few Salt
modules rely on PowerShell. The minimum version of PowerShell required for Salt
is version 3. If you intend to work with DSC then Powershell version 5 is the
minimum.
.. _windows-installer-options:
Installer Options
=================
The installer can be run silently by providing the ``/S`` option at the command
line. The installer also accepts the following options for configuring the Salt
Minion silently:
========================= =====================================================
Option Description
========================= =====================================================
``/master=`` A string value to set the IP address or hostname of
the master. Default value is 'salt'. You can pass a
single master or a comma-separated list of masters.
Setting the master will cause the installer to use
the default config or a custom config if defined.
``/minion-name=`` A string value to set the minion name. Default value
is 'hostname'. Setting the minion name causes the
installer to use the default config or a custom
config if defined.
``/start-minion=`` Either a 1 or 0. '1' will start the salt-minion
service, '0' will not. Default is to start the
service after installation.
``/start-minion-delayed`` Set the minion start type to
``Automatic (Delayed Start)``.
``/default-config`` Overwrite the existing config if present with the
default config for salt. Default is to use the
existing config if present. If ``/master`` and/or
``/minion-name`` is passed, those values will be used
to update the new default config.
``/custom-config=`` A string value specifying the name of a custom config
file in the same path as the installer or the full
path to a custom config file. If ``/master`` and/or
``/minion-name`` is passed, those values will be used
to update the new custom config.
``/install-dir=`` Specify the installation location for the Salt
binaries. This will be ignored for existing
installations.
``/move-config`` If config is found at ``C:\salt`` it will be moved to
``%ProgramData%\Salt Project\Salt``
``/S`` Runs the installation silently. Uses the above
settings or the defaults.
``/?`` Displays command line help.
========================= =====================================================
.. note::
``/default-config`` and ``/custom-config=`` will backup an existing config
if found. A timestamp and a ``.bak`` extension will be added. That includes
the ``minion`` file and the ``minion.d`` directory.
Here are some examples of using the silent installer:
.. code-block:: bat
# Install the Salt Minion
# Configure the minion and start the service
Salt-Minion-3001-Py3-AMD64-Setup.exe /S /master=yoursaltmaster /minion-name=yourminionname
.. code-block:: bat
# Install the Salt Minion
# Configure the minion but don't start the minion service
Salt-Minion-3001-Py3-AMD64-Setup.exe /S /master=yoursaltmaster /minion-name=yourminionname /start-minion=0
.. code-block:: bat
# Install the Salt Minion
# Configure the minion using a custom config and configuring multimaster
Salt-Minion-3001-Py3-AMD64-Setup.exe /S /custom-config=windows_minion /master=prod_master1,prod_master2
Running the Salt Minion on Windows as an Unprivileged User
==========================================================
Notes:
- These instructions were tested with Windows Server 2008 R2
- They are generalizable to any version of Windows that supports a salt-minion
Create the Unprivileged User that the Salt Minion will Run As
-------------------------------------------------------------
1. Click ``Start`` > ``Control Panel`` > ``User Accounts``.
2. Click ``Add or remove user accounts``.
3. Click ``Create new account``.
4. Enter ``salt-user`` (or a name of your preference) in the ``New account name`` field.
5. Select the ``Standard user`` radio button.
6. Click the ``Create Account`` button.
7. Click on the newly created user account.
8. Click the ``Create a password`` link.
9. In the ``New password`` and ``Confirm new password`` fields, provide
a password (e.g "SuperSecretMinionPassword4Me!").
10. In the ``Type a password hint`` field, provide appropriate text (e.g. "My Salt Password").
11. Click the ``Create password`` button.
12. Close the ``Change an Account`` window.
Add the New User to the Access Control List for the Salt Folder
---------------------------------------------------------------
1. In a File Explorer window, browse to the path where Salt is installed (the default path is ``C:\Salt``).
2. Right-click on the ``Salt`` folder and select ``Properties``.
3. Click on the ``Security`` tab.
4. Click the ``Edit`` button.
5. Click the ``Add`` button.
6. Type the name of your designated Salt user and click the ``OK`` button.
7. Check the box to ``Allow`` the ``Modify`` permission.
8. Click the ``OK`` button.
9. Click the ``OK`` button to close the ``Salt Properties`` window.
Update the Windows Service User for the ``salt-minion`` Service
---------------------------------------------------------------
1. Click ``Start`` > ``Administrative Tools`` > ``Services``.
2. In the Services list, right-click on ``salt-minion`` and select ``Properties``.
3. Click the ``Log On`` tab.
4. Click the ``This account`` radio button.
5. Provide the account credentials created in section A.
6. Click the ``OK`` button.
7. Click the ``OK`` button to the prompt confirming that the user ``has been
granted the Log On As A Service right``.
8. Click the ``OK`` button to the prompt confirming that ``The new logon name
will not take effect until you stop and restart the service``.
9. Right-Click on ``salt-minion`` and select ``Stop``.
10. Right-Click on ``salt-minion`` and select ``Start``.
.. _building-developing-windows:
Building and Developing on Windows
==================================
This document will explain how to set up a development environment for Salt on
Windows. The development environment allows you to work with the source code to
customize or fix bugs. It will also allow you to build your own installation.
There are several scripts to automate creating a Windows installer as well as
setting up an environment that facilitates developing and troubleshooting Salt
code. They are located in the ``pkg\windows`` directory in the Salt repo
`(here) <https://github.com/saltstack/salt/tree/|repo_primary_branch|/pkg/windows>`_.
Scripts:
--------
=================== ===========
Script Description
=================== ===========
``build_env.ps1`` A PowerShell script that sets up a Python 3 build
environment
``build_pkg.bat`` A batch file that builds a Windows installer based on the
contents of the ``C:\Python3`` directory
``build.bat`` A batch file that fully automates the building of the
Windows installer using the above two scripts
=================== ===========
.. note::
The ``build.bat`` and ``build_pkg.bat`` scripts both accept a parameter to
specify the version of Salt that will be displayed in the Windows installer.
If no version is passed, the version will be determined using git.
Prerequisite Software
---------------------
The only prerequisite is `Git for Windows <https://git-scm.com/download/win/>`_.
.. _create-build-environment:
Create a Build Environment
--------------------------
1. Working Directory
^^^^^^^^^^^^^^^^^^^^
Create a ``Salt-Dev`` directory on the root of ``C:``. This will be our working
directory. Navigate to ``Salt-Dev`` and clone the
`Salt <https://github.com/saltstack/salt/>`_ repo from GitHub.
Open a command line and type:
.. code-block:: bat
cd \
md Salt-Dev
cd Salt-Dev
git clone https://github.com/saltstack/salt
Go into the ``salt`` directory and checkout the version of salt to work with
(2016.3 or higher).
.. code-block:: bat
cd salt
git checkout 3004
2. Setup the Python Environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Navigate to the ``pkg\windows`` directory and execute the **build_env.ps1**
PowerShell script.
.. code-block:: bat
cd pkg\windows
powershell -file build_env.ps1
.. note::
You can also do this from Explorer by navigating to the ``pkg\windows``
directory, right clicking the **build_env.ps1** powershell script and
selecting **Run with PowerShell**
This will download and install Python with all the dependencies needed to
develop and build Salt.
.. note::
If you get an error or the script fails to run you may need to change the
execution policy. Open a powershell window and type the following command:
.. code-block:: powershell
Set-ExecutionPolicy RemoteSigned
3. Salt in Editable Mode
^^^^^^^^^^^^^^^^^^^^^^^^
Editable mode allows you to more easily modify and test the source code. For
more information see the `Pip documentation
<https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_.
Navigate to the root of the ``salt`` directory and install Salt in editable mode
with ``pip``
.. code-block:: bat
cd \Salt-Dev\salt
pip install -e .
.. note::
The ``.`` is important
.. note::
If ``pip`` is not recognized, you may need to restart your shell to get the
updated path
.. note::
If ``pip`` is still not recognized make sure that the Python Scripts folder
is in the System ``%PATH%``. (``C:\Python3\Scripts``)
4. Setup Salt Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Salt requires a minion configuration file and a few other directories. The
default config file is named ``minion`` located in
``%ProgramData%\Salt Project\Salt\conf``. The easiest way to set this up is to
copy the contents of the ``salt\pkg\windows\buildenv`` directory to
``%ProgramData%\Salt Project\Salt``.
.. code-block:: bat
cd \
md salt
xcopy /s /e \Salt-Dev\salt\pkg\windows\buildenv\* "%ProgramData%\Salt Project\Salt"
Now go into the ``%ProgramData%\Salt Project\Salt\conf`` directory and edit the
minion config file named ``minion`` (no extension). You need to configure the
master and id parameters in this file. Edit the following lines:
.. code-block:: bat
master: <ip or name of your master>
id: <name of your minion>
.. _create-windows-installer:
Create a Windows Installer
==========================
To create a Windows installer, follow steps 1 and 2 from
:ref:`Create a Build Environment <create-build-environment>` above. Then proceed
to 3 below:
3. Install Salt
---------------
To create the installer for Window we install Salt using Python instead of pip.
Navigate to the root ``salt`` directory and install Salt.
.. code-block:: bat
cd \Salt-Dev\salt
python setup.py install
4. Create the Windows Installer
-------------------------------
Navigate to the ``pkg\windows`` directory and run the ``build_pkg.bat``
with the build version (3004) and the Python version as parameters.
.. code-block:: bat
cd pkg\windows
build_pkg.bat 3004
.. note::
If no version is passed, the ``build_pkg.bat`` will guess the version number
using git.
.. _create-windows-installer-easy:
Creating a Windows Installer: Alternate Method (Easier)
=======================================================
Clone the `Salt <https://github.com/saltstack/salt/>`_ repo from GitHub into the
directory of your choice. We're going to use ``Salt-Dev``.
.. code-block:: bat
cd \
md Salt-Dev
cd Salt-Dev
git clone https://github.com/saltstack/salt
Go into the ``salt`` directory and checkout the version of Salt you want to
build.
.. code-block:: bat
cd salt
git checkout 3004
Then navigate to ``pkg\windows`` and run the ``build.bat`` script with the
version you're building.
.. code-block:: bat
cd pkg\windows
build.bat 3004
This will install everything needed to build a Windows installer for Salt using
Python 3. The binary will be in the ``salt\pkg\windows\installer`` directory.
.. _test-salt-minion:
Testing the Salt minion
=======================
1. Create the directory ``%ProgramData\Salt Project\Salt`` (if it doesn't exist already)
2. Copy the example ``conf`` and ``var`` directories from
``pkg\windows\buildenv`` into ``%ProgramData\Salt Project\Salt``
3. Edit ``%ProgramData\Salt Project\Salt\conf\minion``
.. code-block:: bash
master: ipaddress or hostname of your salt-master
4. Start the salt-minion
.. code-block:: bash
cd C:\Python3\Scripts
python salt-minion -l debug
5. On the salt-master accept the new minion's key
.. code-block:: bash
sudo salt-key -A
This accepts all unaccepted keys. If you're concerned about security just
accept the key for this specific minion.
6. Test that your minion is responding
On the salt-master run:
.. code-block:: bash
sudo salt '*' test.version
You should get the following response: ``{'your minion hostname': True}``
Packages Management Under Windows 2003
======================================
Windows Server 2003 and Windows XP have both reached End of Support. Though Salt
is not officially supported on operating systems that are EoL, some
functionality may continue to work.
On Windows Server 2003, you need to install optional component "WMI Windows
Installer Provider" to get a full list of installed packages. If you don't have
this, salt-minion can't report some installed software.