From f0de1236ec95e997dc6eed27ce069943c19e59b8 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 21:58:11 -0500 Subject: [PATCH 01/12] Move the tables of virtual modules to individual documentation pages --- doc/ref/modules/all/salt.modules.group.rst | 24 ++++ doc/ref/modules/all/salt.modules.pkg.rst | 45 +++++-- doc/ref/modules/all/salt.modules.service.rst | 35 +++++- doc/ref/modules/all/salt.modules.shadow.rst | 22 +++- doc/ref/modules/all/salt.modules.user.rst | 24 ++++ doc/ref/states/providers.rst | 119 +------------------ 6 files changed, 140 insertions(+), 129 deletions(-) create mode 100644 doc/ref/modules/all/salt.modules.group.rst create mode 100644 doc/ref/modules/all/salt.modules.user.rst diff --git a/doc/ref/modules/all/salt.modules.group.rst b/doc/ref/modules/all/salt.modules.group.rst new file mode 100644 index 000000000000..f95ebf64cfec --- /dev/null +++ b/doc/ref/modules/all/salt.modules.group.rst @@ -0,0 +1,24 @@ +.. _virtual-group: + +================== +salt.modules.group +================== + +.. py:module:: salt.modules.group + :synopsis: A virtual module for group management + +``group`` is a virtual module that is fulfilled by one of the following +modules: + +====================================== ======================================== +Execution Module Used for +====================================== ======================================== +:py:mod:`~salt.modules.groupadd` Linux, NetBSD, and OpenBSD systems using + ``groupadd(8)``, ``groupdel(8)``, and + ``groupmod(8)`` +:py:mod:`~salt.modules.pw_group` FreeBSD-based OSes using ``pw(8)`` +:py:mod:`~salt.modules.solaris_group` Solaris-based OSes using + ``groupadd(1M)``, ``groupdel(1M)``, and + ``groupmod(1M)`` +:py:mod:`~salt.modules.win_groupadd` Windows +====================================== ======================================== diff --git a/doc/ref/modules/all/salt.modules.pkg.rst b/doc/ref/modules/all/salt.modules.pkg.rst index fd5b62740d3a..9488336e60d2 100644 --- a/doc/ref/modules/all/salt.modules.pkg.rst +++ b/doc/ref/modules/all/salt.modules.pkg.rst @@ -1,3 +1,5 @@ +.. _virtual-pkg: + ================ salt.modules.pkg ================ @@ -7,16 +9,33 @@ salt.modules.pkg ``pkg`` is a virtual module that is fulfilled by one of the following modules: -* :mod:`salt.modules.aptpkg` -* :mod:`salt.modules.brew` -* :mod:`salt.modules.ebuild` -* :mod:`salt.modules.freebsdpkg` -* :mod:`salt.modules.openbsdpkg` -* :mod:`salt.modules.pacman` -* :mod:`salt.modules.pkgin` -* :mod:`salt.modules.pkgng` -* :mod:`salt.modules.pkgutil` -* :mod:`salt.modules.solarispkg` -* :mod:`salt.modules.win_pkg` -* :mod:`salt.modules.yumpkg` -* :mod:`salt.modules.zypper` \ No newline at end of file +====================================== ======================================== +Execution Module Used for +====================================== ======================================== +:py:mod:`~salt.modules.aptpkg` Debian/Ubuntu-based distros which use + ``apt-get(8)`` for package management +:py:mod:`~salt.modules.brew` Mac OS software management using + `Homebrew`_ +:py:mod:`~salt.modules.ebuild` Gentoo-based systems (utilizes the + ``portage`` python module as well as + ``emerge(1)``) +:py:mod:`~salt.modules.freebsdpkg` FreeBSD-based OSes using ``pkg_add(1)`` +:py:mod:`~salt.modules.openbsdpkg` OpenBSD-based OSes using ``pkg_add(1)`` +:py:mod:`~salt.modules.pacman` Arch Linux-based distros using + ``pacman(8)`` +:py:mod:`~salt.modules.pkgin` NetBSD-based OSes using ``pkgin(1)`` +:py:mod:`~salt.modules.pkgng` FreeBSD-based OSes using ``pkg(8)`` +:py:mod:`~salt.modules.pkgutil` Solaris-based OSes using `OpenCSW`_'s + ``pkgutil(1)`` +:py:mod:`~salt.modules.solarispkg` Solaris-based OSes using ``pkgadd(1M)`` +:py:mod:`~salt.modules.solarisips` Solaris-based OSes using IPS ``pkg(1)`` +:py:mod:`~salt.modules.win_pkg` Salt's :ref:`Windows Package Manager + ` function, -taking care to sanitize any sensitive information. - -Below are tables that should help with deciding which provider to use if one -needs to be overridden. - - -Provider: ``pkg`` -***************** - -======================= ======================================================= -Execution Module Used for -======================= ======================================================= -apt Debian/Ubuntu-based distros which use ``apt-get(8)`` - for package management -brew Mac OS software management using `Homebrew`_ -ebuild Gentoo-based systems (utilizes the ``portage`` python - module as well as ``emerge(1)``) -freebsdpkg FreeBSD-based OSes using ``pkg_add(1)`` -openbsdpkg OpenBSD-based OSes using ``pkg_add(1)`` -pacman Arch Linux-based distros using ``pacman(8)`` -pkgin NetBSD-based OSes using ``pkgin(1)`` -pkgng FreeBSD-based OSes using ``pkg(8)`` -pkgutil Solaris-based OSes using `OpenCSW`_'s ``pkgutil(1)`` -solarispkg Solaris-based OSes using ``pkgadd(1M)`` -solarisips Solaris-based OSes using IPS ``pkg(1)`` -win_pkg Windows -yumpkg RedHat-based distros and derivatives (wraps ``yum(8)``) -zypper SUSE-based distros using ``zypper(8)`` -======================= ======================================================= - -.. _Homebrew: http://brew.sh/ -.. _OpenCSW: http://www.opencsw.org/ - - -Provider: ``service`` -********************* - -======================= ======================================================= -Execution Module Used for -======================= ======================================================= -debian_service Debian (non-systemd) -freebsdservice FreeBSD-based OSes using ``service(8)`` -gentoo_service Gentoo Linux using :program:`sysvinit` and - ``rc-update(8)`` -launchctl Mac OS hosts using ``launchctl(1)`` -netbsdservice NetBSD-based OSes -openbsdservice OpenBSD-based OSes -rh_service RedHat-based distros and derivatives using - ``service(8)`` and ``chkconfig(8)``. Supports both - pure sysvinit and mixed sysvinit/upstart systems. -service Fallback which simply wraps sysvinit scripts -smf Solaris-based OSes which use SMF -systemd Linux distros which use systemd -upstart Ubuntu-based distros using upstart -win_service Windows -======================= ======================================================= - - -Provider: ``user`` -****************** - -======================= ======================================================= -Execution Module Used for -======================= ======================================================= -useradd Linux, NetBSD, and OpenBSD systems using - ``useradd(8)``, ``userdel(8)``, and ``usermod(8)`` -pw_user FreeBSD-based OSes using ``pw(8)`` -solaris_user Solaris-based OSes using ``useradd(1M)``, - ``userdel(1M)``, and ``usermod(1M)`` -win_useradd Windows -======================= ======================================================= - - -Provider: ``group`` -******************* - -======================= ======================================================= -Execution Module Used for -======================= ======================================================= -groupadd Linux, NetBSD, and OpenBSD systems using - ``groupadd(8)``, ``groupdel(8)``, and ``groupmod(8)`` -pw_group FreeBSD-based OSes using ``pw(8)`` -solaris_group Solaris-based OSes using ``groupadd(1M)``, - ``groupdel(1M)``, and ``groupmod(1M)`` -win_groupadd Windows -======================= ======================================================= - +described :ref:`here `. Arbitrary Module Redirects ========================== @@ -155,4 +46,4 @@ In this example, the state is being instructed to use a custom module to invoke commands. Arbitrary module redirects can be used to dramatically change the behavior of a -given state. \ No newline at end of file +given state. From e7fa21438c84ae28a5d65343c6e2dfdce811e976 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 21:59:21 -0500 Subject: [PATCH 02/12] Add new doc pages to toctree --- doc/ref/modules/all/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/ref/modules/all/index.rst b/doc/ref/modules/all/index.rst index 03f71ee8b02b..f6120cc76f10 100644 --- a/doc/ref/modules/all/index.rst +++ b/doc/ref/modules/all/index.rst @@ -103,6 +103,7 @@ Full list of builtin execution modules gnomedesktop gpg grains + group groupadd grub_legacy guestfs @@ -268,6 +269,7 @@ Full list of builtin execution modules tomcat twilio_notify upstart + user useradd uwsgi varnish From 1948920674ee1f0fee773c0bb06f1c13e2d8a17e Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 22:00:06 -0500 Subject: [PATCH 03/12] Add external ref to windows package manager docs --- doc/topics/windows/windows-package-manager.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/topics/windows/windows-package-manager.rst b/doc/topics/windows/windows-package-manager.rst index 7b7e23450054..2d35211e2413 100644 --- a/doc/topics/windows/windows-package-manager.rst +++ b/doc/topics/windows/windows-package-manager.rst @@ -1,3 +1,5 @@ +.. _windows-package-manager: + =========================== Windows Software Repository =========================== @@ -169,7 +171,7 @@ project's wiki_: uninstaller: '{23170F69-40C1-2702-0920-000001000000}' uninstall_flags: '/qn /norestart' -Alternatively the ``uninstaller`` can also simply repeat the URL of the msi file. +Alternatively the ``uninstaller`` can also simply repeat the URL of the msi file. .. code-block:: yaml From 0bc6c97a6373d95743d4fb89ba1645d504da7056 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 22:00:56 -0500 Subject: [PATCH 04/12] Improve docstrings --- salt/modules/service.py | 3 +-- salt/modules/shadow.py | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/salt/modules/service.py b/salt/modules/service.py index f5b0d160bfc1..008adf2c9fe3 100644 --- a/salt/modules/service.py +++ b/salt/modules/service.py @@ -1,7 +1,6 @@ # -*- coding: utf-8 -*- ''' -The default service module, if not otherwise specified salt will fall back -to this basic module +If Salt's OS detection does not identify a different virtual service module, the minion will fall back to using this basic module, which simply wraps sysvinit scripts. ''' from __future__ import absolute_import diff --git a/salt/modules/shadow.py b/salt/modules/shadow.py index 97731f322076..5a37c5442642 100644 --- a/salt/modules/shadow.py +++ b/salt/modules/shadow.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- ''' -Manage the shadow file +Manage the shadow file on Linux systems ''' from __future__ import absolute_import From af24c82ab0ae903ac9d3d75dadba16c57f177692 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 22:01:14 -0500 Subject: [PATCH 05/12] Add documentation on virtual module provider overrides to the module docs --- doc/ref/modules/index.rst | 63 +++++++++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 13 deletions(-) diff --git a/doc/ref/modules/index.rst b/doc/ref/modules/index.rst index 639e03b291c0..b4d08ff30da2 100644 --- a/doc/ref/modules/index.rst +++ b/doc/ref/modules/index.rst @@ -130,8 +130,8 @@ Outputter. .. code-block:: python __outputter__ = { - 'run': 'txt' - } + 'run': 'txt' + } This will ensure that the text outputter is used. @@ -170,8 +170,8 @@ Since ``__virtual__`` is called before the module is loaded, ``__salt__`` will b unavailable as it will not have been packed into the module at this point in time. .. note:: - Modules which return a string from ``__virtual__`` that is already used by a module that - ships with Salt will _override_ the stock module. + Modules which return a string from ``__virtual__`` that is already used by + a module that ships with Salt will _override_ the stock module. .. _modules-error-info: @@ -180,21 +180,58 @@ Returning Error Information from ``__virtual__`` Optionally, modules may additionally return a list of reasons that a module could not be loaded. For example, if a dependency for 'my_mod' was not met, a -__virtual__ function could do as follows: +``__virtual__`` function could do as follows: - return False, ['My Module must be installed before this module can be - used.'] +.. code-block:: python + + return False, 'My Module must be installed before this module can be used.' Examples -------- -The package manager modules are among the best examples of using the ``__virtual__`` -function. Some examples: +The package manager modules are among the best examples of using the +``__virtual__`` function. A table of all the virtual ``pkg`` modules can be +found :ref:`here `. + +.. _module-provider-override: + +Overriding Virtual Module Providers +----------------------------------- + +Salt often uses OS grains (``os``, ``osrelease``, ``os_family``, etc.) to +determine which module should be loaded as the virtual module for ``pkg``, +``service``, etc. Sometimes this OS detection is incomplete, with new distros +popping up, existing distros changing init systems, etc. The virtual modules +likely to be affected by this are in the list below (click each item for more +information): + +- :ref:`pkg ` +- :ref:`service ` +- :ref:`user ` +- :ref:`shadow ` +- :ref:`group ` + +If Salt is using the wrong module for one of these, first of all, please +`report it on the issue tracker`__, so that this issue can be resolved for a +future release. To make it easier to troubleshoot, please also provide the +:py:mod:`grains.items ` output, taking care to +redact any sensitive information. + +Then, while waiting for the SaltStack development team to fix the issue, Salt +can be made to use the correct module using the :conf_minion:`providers` option +in the minion config file: + +.. code-block:: yaml + + providers: + service: systemd + pkg: aptpkg + +The above example will force the minion to use the :py:mod:`systemd +` module to provide service mangement, and the +:py:mod:`aptpkg ` module to provide package management. -- :blob:`pacman.py ` -- :blob:`yumpkg.py ` -- :blob:`aptpkg.py ` -- :blob:`at.py ` +.. __: https://github.com/saltstack/salt/issues/new .. _modules-virtual-name: From f9306347cc4779b738ef5a082bcd8bfff6711a62 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 22:05:36 -0500 Subject: [PATCH 06/12] Clarify the scope of the provider param in states. --- doc/ref/states/providers.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/ref/states/providers.rst b/doc/ref/states/providers.rst index df0e26ae460b..227719bda8b2 100644 --- a/doc/ref/states/providers.rst +++ b/doc/ref/states/providers.rst @@ -24,9 +24,13 @@ In this instance, the basic :py:mod:`~salt.modules.service` module (which manages :program:`sysvinit`-based services) will replace the :py:mod:`~salt.modules.systemd` module which is used by default on Arch Linux. -However, if it is necessary to make this override for most or every service, -it is better to just override the provider in the minion config file, as -described :ref:`here `. +This change only affects this one state though. If it is necessary to make this +override for most or every service, it is better to just override the provider +in the minion config file, as described :ref:`here `. + +Also, keep in mind that this only works for states with an identically-named +virtual module (:py:mod:`~salt.states.pkg`, :py:mod:`~salt.states.service`, +etc.). Arbitrary Module Redirects ========================== From 736f2befc9966d0adce18e4e503feaa8356bd0ed Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 22:58:08 -0500 Subject: [PATCH 07/12] Add link to provider override docs to all package providers --- salt/modules/aptpkg.py | 7 ++++++- salt/modules/brew.py | 6 ++++++ salt/modules/ebuild.py | 6 ++++++ salt/modules/freebsdpkg.py | 6 ++++++ salt/modules/openbsdpkg.py | 6 ++++++ salt/modules/pacman.py | 6 ++++++ salt/modules/pkgin.py | 6 ++++++ salt/modules/pkgng.py | 6 ++++++ salt/modules/pkgutil.py | 6 ++++++ salt/modules/solarisips.py | 6 ++++++ salt/modules/solarispkg.py | 6 ++++++ salt/modules/win_pkg.py | 6 ++++++ salt/modules/yumpkg.py | 6 ++++++ salt/modules/zypper.py | 6 ++++++ 14 files changed, 84 insertions(+), 1 deletion(-) diff --git a/salt/modules/aptpkg.py b/salt/modules/aptpkg.py index f6cdf846cb9b..f32054c72450 100644 --- a/salt/modules/aptpkg.py +++ b/salt/modules/aptpkg.py @@ -2,8 +2,13 @@ ''' Support for APT (Advanced Packaging Tool) -.. note:: +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. +.. note:: For virtual package support, either the ``python-apt`` or ``dctrl-tools`` package must be installed. diff --git a/salt/modules/brew.py b/salt/modules/brew.py index 423406025940..5251059c7255 100644 --- a/salt/modules/brew.py +++ b/salt/modules/brew.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Homebrew for Mac OS X + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/ebuild.py b/salt/modules/ebuild.py index f160e862fc17..9255ed104fe1 100644 --- a/salt/modules/ebuild.py +++ b/salt/modules/ebuild.py @@ -2,6 +2,12 @@ ''' Support for Portage +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + :optdepends: - portage Python adapter For now all package names *MUST* include the package category, diff --git a/salt/modules/freebsdpkg.py b/salt/modules/freebsdpkg.py index 090b1d1f9760..6ea682173f79 100644 --- a/salt/modules/freebsdpkg.py +++ b/salt/modules/freebsdpkg.py @@ -2,6 +2,12 @@ ''' Remote package support using ``pkg_add(1)`` +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + .. warning:: This module has been completely rewritten. Up to and including version diff --git a/salt/modules/openbsdpkg.py b/salt/modules/openbsdpkg.py index ad24d78fa1aa..eb0e26a4ee6d 100644 --- a/salt/modules/openbsdpkg.py +++ b/salt/modules/openbsdpkg.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Package support for OpenBSD + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/pacman.py b/salt/modules/pacman.py index 1ce0c6fd5972..bc4331b52ba4 100644 --- a/salt/modules/pacman.py +++ b/salt/modules/pacman.py @@ -2,6 +2,12 @@ ''' A module to wrap pacman calls, since Arch is the best (https://wiki.archlinux.org/index.php/Arch_is_the_best) + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/pkgin.py b/salt/modules/pkgin.py index 943a3997ef8f..7c85d3de2810 100644 --- a/salt/modules/pkgin.py +++ b/salt/modules/pkgin.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Package support for pkgin based systems, inspired from freebsdpkg module + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/pkgng.py b/salt/modules/pkgng.py index e0037470a935..a490d12bae14 100644 --- a/salt/modules/pkgng.py +++ b/salt/modules/pkgng.py @@ -2,6 +2,12 @@ ''' Support for ``pkgng``, the new package manager for FreeBSD +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + .. warning:: This module has been completely rewritten. Up to and including version diff --git a/salt/modules/pkgutil.py b/salt/modules/pkgutil.py index 189a5c14f859..91f103a488e4 100644 --- a/salt/modules/pkgutil.py +++ b/salt/modules/pkgutil.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Pkgutil support for Solaris + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/solarisips.py b/salt/modules/solarisips.py index 25c094f3114a..45f58ce4294b 100644 --- a/salt/modules/solarisips.py +++ b/salt/modules/solarisips.py @@ -2,6 +2,12 @@ ''' IPS pkg support for Solaris +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + This module provides support for Solaris 11 new package management - IPS (Image Packaging System). This is the default pkg module for Solaris 11 (and later). diff --git a/salt/modules/solarispkg.py b/salt/modules/solarispkg.py index a3cac7fe49ec..283c7593fd25 100644 --- a/salt/modules/solarispkg.py +++ b/salt/modules/solarispkg.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Package support for Solaris + +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/win_pkg.py b/salt/modules/win_pkg.py index fc1aadb291a1..3dbe56207e3f 100644 --- a/salt/modules/win_pkg.py +++ b/salt/modules/win_pkg.py @@ -2,6 +2,12 @@ ''' A module to manage software on Windows +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + :depends: - win32com - win32con - win32api diff --git a/salt/modules/yumpkg.py b/salt/modules/yumpkg.py index 78924987e9e6..0f6f7ac80060 100644 --- a/salt/modules/yumpkg.py +++ b/salt/modules/yumpkg.py @@ -2,6 +2,12 @@ ''' Support for YUM/DNF +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + .. note:: This module makes use of the **repoquery** utility, from the yum-utils_ package. This package will be installed as a dependency if salt is diff --git a/salt/modules/zypper.py b/salt/modules/zypper.py index 9ddd8ce92686..348d4a03eb1b 100644 --- a/salt/modules/zypper.py +++ b/salt/modules/zypper.py @@ -2,6 +2,12 @@ ''' Package support for openSUSE via the zypper package manager +.. important:: + If you feel that Salt should be using this module to manage packages on a + minion, and it is using a different module (or gives an error similar to + *'pkg.install' is not available*), see :ref:`here + `. + :depends: - ``zypp`` Python module. Install with ``zypper install python-zypp`` ''' from __future__ import absolute_import From 5c1c1dda5955a8d1fce5ac8404c68bb3524f7fb2 Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 23:04:14 -0500 Subject: [PATCH 08/12] Add link to provider override docs to all service providers --- salt/modules/debian_service.py | 6 ++++++ salt/modules/freebsdservice.py | 6 ++++++ salt/modules/gentoo_service.py | 6 ++++++ salt/modules/launchctl.py | 6 ++++++ salt/modules/netbsdservice.py | 6 ++++++ salt/modules/openbsdservice.py | 6 ++++++ salt/modules/rh_service.py | 6 ++++++ salt/modules/smf.py | 6 ++++++ salt/modules/systemd.py | 6 ++++++ salt/modules/upstart.py | 6 ++++++ 10 files changed, 60 insertions(+) diff --git a/salt/modules/debian_service.py b/salt/modules/debian_service.py index 1d26e48e0dda..94bbe0771e97 100644 --- a/salt/modules/debian_service.py +++ b/salt/modules/debian_service.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Service support for Debian systems (uses update-rc.d and /sbin/service) + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/freebsdservice.py b/salt/modules/freebsdservice.py index 4431e01fce52..a2ce0e776f4e 100644 --- a/salt/modules/freebsdservice.py +++ b/salt/modules/freebsdservice.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' The service module for FreeBSD + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/gentoo_service.py b/salt/modules/gentoo_service.py index bb42c5f14dd7..e23bdfd82abe 100644 --- a/salt/modules/gentoo_service.py +++ b/salt/modules/gentoo_service.py @@ -2,6 +2,12 @@ ''' Top level package command wrapper, used to translate the os detected by grains to the correct service manager + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' # Define the module's virtual name diff --git a/salt/modules/launchctl.py b/salt/modules/launchctl.py index 62f01259304c..2e5ef0bb6bf8 100644 --- a/salt/modules/launchctl.py +++ b/salt/modules/launchctl.py @@ -2,6 +2,12 @@ ''' Module for the management of MacOS systems that use launchd/launchctl +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. + :depends: - plistlib Python module ''' from __future__ import absolute_import diff --git a/salt/modules/netbsdservice.py b/salt/modules/netbsdservice.py index 9949c6254c51..805bc79e8939 100644 --- a/salt/modules/netbsdservice.py +++ b/salt/modules/netbsdservice.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' The service module for NetBSD + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/openbsdservice.py b/salt/modules/openbsdservice.py index 90832c383199..8e1891cee5c1 100644 --- a/salt/modules/openbsdservice.py +++ b/salt/modules/openbsdservice.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' The service module for OpenBSD + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/rh_service.py b/salt/modules/rh_service.py index e3539f40e08c..18332b463081 100644 --- a/salt/modules/rh_service.py +++ b/salt/modules/rh_service.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Service support for RHEL-based systems, including support for both upstart and sysvinit + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/smf.py b/salt/modules/smf.py index 229e49d97bce..2be7dd831983 100644 --- a/salt/modules/smf.py +++ b/salt/modules/smf.py @@ -2,6 +2,12 @@ ''' Service support for Solaris 10 and 11, should work with other systems that use SMF also. (e.g. SmartOS) + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' __func_alias__ = { diff --git a/salt/modules/systemd.py b/salt/modules/systemd.py index 4b2ffc9c7f8f..bb6e754b3291 100644 --- a/salt/modules/systemd.py +++ b/salt/modules/systemd.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Provide the service module for systemd + +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. ''' # Import python libs from __future__ import absolute_import diff --git a/salt/modules/upstart.py b/salt/modules/upstart.py index 95c91a7d2240..da8f1e0325f5 100644 --- a/salt/modules/upstart.py +++ b/salt/modules/upstart.py @@ -3,6 +3,12 @@ Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting. +.. important:: + If you feel that Salt should be using this module to manage services on a + minion, and it is using a different module (or gives an error similar to + *'service.start' is not available*), see :ref:`here + `. + Currently (as of Ubuntu 12.04) there is no tool available to disable Upstart services (like update-rc.d). This[1] is the recommended way to disable an Upstart service. So we assume that all Upstart services From c5fe38789d835baa4305b5361d3e2bdaaa5f5c8d Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 23:32:41 -0500 Subject: [PATCH 09/12] Add link to provider override docs to all user providers --- salt/modules/mac_user.py | 6 ++++++ salt/modules/pw_user.py | 6 ++++++ salt/modules/solaris_user.py | 6 ++++++ salt/modules/useradd.py | 6 ++++++ salt/modules/win_useradd.py | 6 ++++++ 5 files changed, 30 insertions(+) diff --git a/salt/modules/mac_user.py b/salt/modules/mac_user.py index 9fb6449b0855..481483ca13d1 100644 --- a/salt/modules/mac_user.py +++ b/salt/modules/mac_user.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage users on Mac OS 10.7+ + +.. important:: + If you feel that Salt should be using this module to manage users on a + minion, and it is using a different module (or gives an error similar to + *'user.info' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/pw_user.py b/salt/modules/pw_user.py index 89eb8374bfd4..8eb4e754fe1d 100644 --- a/salt/modules/pw_user.py +++ b/salt/modules/pw_user.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage users with the useradd command + +.. important:: + If you feel that Salt should be using this module to manage users on a + minion, and it is using a different module (or gives an error similar to + *'user.info' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/solaris_user.py b/salt/modules/solaris_user.py index 8a82c5a1f493..278dead37c21 100644 --- a/salt/modules/solaris_user.py +++ b/salt/modules/solaris_user.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage users with the useradd command + +.. important:: + If you feel that Salt should be using this module to manage users on a + minion, and it is using a different module (or gives an error similar to + *'user.info' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/useradd.py b/salt/modules/useradd.py index 8b3e5c0ca63d..cdf98cfffee7 100644 --- a/salt/modules/useradd.py +++ b/salt/modules/useradd.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage users with the useradd command + +.. important:: + If you feel that Salt should be using this module to manage users on a + minion, and it is using a different module (or gives an error similar to + *'user.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/win_useradd.py b/salt/modules/win_useradd.py index 3c885dc76242..b1747412313a 100644 --- a/salt/modules/win_useradd.py +++ b/salt/modules/win_useradd.py @@ -2,6 +2,12 @@ ''' Module for managing Windows Users +.. important:: + If you feel that Salt should be using this module to manage users on a + minion, and it is using a different module (or gives an error similar to + *'user.info' is not available*), see :ref:`here + `. + :depends: - pywintypes - win32api From 83ca01f620a91133f27a1be6a211f7bc8ccc661c Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 23:34:31 -0500 Subject: [PATCH 10/12] dd link to provider override docs to all shadow providers --- salt/modules/bsd_shadow.py | 6 ++++++ salt/modules/shadow.py | 6 ++++++ salt/modules/solaris_shadow.py | 6 ++++++ salt/modules/win_shadow.py | 6 ++++++ 4 files changed, 24 insertions(+) diff --git a/salt/modules/bsd_shadow.py b/salt/modules/bsd_shadow.py index 78cdfdf9602c..9faf6b70d6c3 100644 --- a/salt/modules/bsd_shadow.py +++ b/salt/modules/bsd_shadow.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage the password database on BSD systems + +.. important:: + If you feel that Salt should be using this module to manage passwords on a + minion, and it is using a different module (or gives an error similar to + *'shadow.info' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/shadow.py b/salt/modules/shadow.py index 5a37c5442642..06f6c2c04227 100644 --- a/salt/modules/shadow.py +++ b/salt/modules/shadow.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage the shadow file on Linux systems + +.. important:: + If you feel that Salt should be using this module to manage passwords on a + minion, and it is using a different module (or gives an error similar to + *'shadow.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/solaris_shadow.py b/salt/modules/solaris_shadow.py index 0c8a337635b0..d62c343070eb 100644 --- a/salt/modules/solaris_shadow.py +++ b/salt/modules/solaris_shadow.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage the password database on Solaris systems + +.. important:: + If you feel that Salt should be using this module to manage passwords on a + minion, and it is using a different module (or gives an error similar to + *'shadow.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/win_shadow.py b/salt/modules/win_shadow.py index 167b28787f0b..6ce6ccb9336c 100644 --- a/salt/modules/win_shadow.py +++ b/salt/modules/win_shadow.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage the shadow file + +.. important:: + If you feel that Salt should be using this module to manage passwords on a + minion, and it is using a different module (or gives an error similar to + *'shadow.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import From 500d3ebbaaf9ff34e5aa83fa51f7a17ed2485d1c Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Fri, 8 Apr 2016 23:36:02 -0500 Subject: [PATCH 11/12] Add link to provider override docs to all group providers --- salt/modules/groupadd.py | 6 ++++++ salt/modules/pw_group.py | 6 ++++++ salt/modules/solaris_group.py | 6 ++++++ salt/modules/win_groupadd.py | 6 ++++++ 4 files changed, 24 insertions(+) diff --git a/salt/modules/groupadd.py b/salt/modules/groupadd.py index 61238f6046c8..dd51f11ce268 100644 --- a/salt/modules/groupadd.py +++ b/salt/modules/groupadd.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage groups on Linux, OpenBSD and NetBSD + +.. important:: + If you feel that Salt should be using this module to manage groups on a + minion, and it is using a different module (or gives an error similar to + *'group.info' is not available*), see :ref:`here + `. ''' # Import python libs diff --git a/salt/modules/pw_group.py b/salt/modules/pw_group.py index 430f2ff8ad3e..ba0443db3592 100644 --- a/salt/modules/pw_group.py +++ b/salt/modules/pw_group.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage groups on FreeBSD + +.. important:: + If you feel that Salt should be using this module to manage groups on a + minion, and it is using a different module (or gives an error similar to + *'group.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/solaris_group.py b/salt/modules/solaris_group.py index 656b58f237c0..f1ad305ffe11 100644 --- a/salt/modules/solaris_group.py +++ b/salt/modules/solaris_group.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage groups on Solaris + +.. important:: + If you feel that Salt should be using this module to manage groups on a + minion, and it is using a different module (or gives an error similar to + *'group.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import diff --git a/salt/modules/win_groupadd.py b/salt/modules/win_groupadd.py index 31abfc8b64ef..ea1a80c8159c 100644 --- a/salt/modules/win_groupadd.py +++ b/salt/modules/win_groupadd.py @@ -1,6 +1,12 @@ # -*- coding: utf-8 -*- ''' Manage groups on Windows + +.. important:: + If you feel that Salt should be using this module to manage groups on a + minion, and it is using a different module (or gives an error similar to + *'group.info' is not available*), see :ref:`here + `. ''' from __future__ import absolute_import From 29333e533e97077cf164703b8f740610df4049e5 Mon Sep 17 00:00:00 2001 From: Nicole Thomas Date: Mon, 11 Apr 2016 10:49:52 -0600 Subject: [PATCH 12/12] Add documentation for some master/minion configs (#32454) Refs #32400 Adds docs for: - cli_summary - event_return_queue - event_return_whitelist - event_return_blacklist - file_recv_max_size - fileserver_followsymlinks - fileserver_ignoresymlinks - fileserver_limit_traversal --- conf/master | 10 ++- conf/minion | 16 ++++ doc/ref/configuration/master.rst | 137 +++++++++++++++++++++++++++++++ doc/ref/configuration/minion.rst | 69 ++++++++++++++++ 4 files changed, 230 insertions(+), 2 deletions(-) diff --git a/conf/master b/conf/master index f5cc2a6e627d..ce5f262bc6fe 100644 --- a/conf/master +++ b/conf/master @@ -111,6 +111,12 @@ # (true by default). # strip_colors: False +# To display a summary of the number of minions targeted, the number of +# minions returned, and the number of minions that did not return, set the +# cli_summary value to True. (False by default.) +# +#cli_summary: False + # Set the directory used to hold unix sockets: #sock_dir: /var/run/salt/master @@ -141,12 +147,12 @@ # By default, events are not queued. #event_return_queue: 0 -# Only events returns matching tags in a whitelist +# Only return events matching tags in a whitelist, # event_return_whitelist: # - salt/master/a_tag # - salt/master/another_tag -# Store all event returns _except_ the tags in a blacklist +# Store all event returns _except_ the tags in a blacklist. # event_return_blacklist: # - salt/master/not_this_tag # - salt/master/or_this_one diff --git a/conf/minion b/conf/minion index c0ee67f238d9..c095795fac27 100644 --- a/conf/minion +++ b/conf/minion @@ -432,6 +432,18 @@ # base: # - /srv/salt +# Uncomment the line below if you do not want the file_server to follow +# symlinks when walking the filesystem tree. This is set to True +# by default. Currently this only applies to the default roots +# fileserver_backend. +#fileserver_followsymlinks: False +# +# Uncomment the line below if you do not want symlinks to be +# treated as the files they are pointing to. By default this is set to +# False. By uncommenting the line below, any detected symlink while listing +# files on the Master will not be returned to the Minion. +#fileserver_ignoresymlinks: True +# # By default, the Salt fileserver recurses fully into all defined environments # to attempt to find files. To limit this behavior so that the fileserver only # traverses directories with SLS files and special Salt directories like _modules, @@ -454,6 +466,10 @@ #pillar_roots: # base: # - /srv/pillar + +# Set a hard-limit on the size of the files that can be pushed to the master. +# It will be interpreted as megabytes. Default: 100 +#file_recv_max_size: 100 # # ###### Security settings ##### diff --git a/doc/ref/configuration/master.rst b/doc/ref/configuration/master.rst index db44fa5e9021..232b6426b217 100644 --- a/doc/ref/configuration/master.rst +++ b/doc/ref/configuration/master.rst @@ -322,6 +322,21 @@ to False. color: False +.. conf_master:: cli_summary + +``cli_summary`` +--------------- + +Default: ``False`` + +When set to ``True``, displays a summary of the number of minions targeted, +the number of minions returned, and the number of minions that did not +return. + +.. code-block:: yaml + + cli_summary: False + .. conf_master:: sock_dir ``sock_dir`` @@ -414,6 +429,58 @@ configuration requirements. Read the returner's documentation. event_return: cassandra_cql +.. conf_master:: event_return_queue + +``event_return_queue`` +---------------------- + +.. versionadded:: 2015.5.0 + +Default: ``0`` + +On busy systems, enabling event_returns can cause a considerable load on +the storage system for returners. Events can be queued on the master and +stored in a batched fashion using a single transaction for multiple events. +By default, events are not queued. + +.. code-block:: yaml + + event_return_queue: 0 + +.. conf_master:: event_return_whitelist + +``event_return_whitelist`` +-------------------------- + +.. versionadded:: 2015.5.0 + +Default: ``[]`` + +Only return events matching tags in a whitelist. + +.. code-block:: yaml + + event_return_whitelist: + - salt/master/a_tag + - salt/master/another_tag + +.. conf_master:: event_return_blacklist + +``event_return_blacklist`` +-------------------------- + +.. versionadded:: 2015.5.0 + +Default: ``[]`` + +Store all event returns _except_ the tags in a blacklist. + +.. code-block:: yaml + + event_return_blacklist: + - salt/master/not_this_tag + - salt/master/or_this_one + .. conf_master:: master_job_cache ``master_job_cache`` @@ -696,6 +763,22 @@ security purposes. file_recv: False +.. conf_master:: file_recv_max_size + +``file_recv_max_size`` +---------------------- + +.. versionadded:: 2014.7.0 + +Default: ``100`` + +Set a hard-limit on the size of the files that can be pushed to the master. +It will be interpreted as megabytes. + +.. code-block:: yaml + + file_recv_max_size: 100 + .. conf_master:: master_sign_pubkey ``master_sign_pubkey`` @@ -1001,6 +1084,60 @@ Example: - roots - git +.. conf_master:: fileserver_followsymlinks + +``fileserver_followsymlinks`` +----------------------------- + +.. versionadded:: 2014.1.0 + +Default: ``True`` + +By default, the file_server follows symlinks when walking the filesystem tree. +Currently this only applies to the default roots fileserver_backend. + +.. code-block:: yaml + + fileserver_followsymlinks: True + +.. conf_master:: fileserver_ignoresymlinks + +``fileserver_ignoresymlinks`` +----------------------------- + +.. versionadded:: 2014.1.0 + +Default: ``False`` + +If you do not want symlinks to be treated as the files they are pointing to, +set ``fileserver_ignoresymlinks`` to ``True``. By default this is set to +False. When set to ``True``, any detected symlink while listing files on the +Master will not be returned to the Minion. + +.. code-block:: yaml + + fileserver_ignoresymlinks: False + +.. conf_master:: fileserver_limit_traversal + +``fileserver_limit_traversal`` +------------------------------ + +.. versionadded:: 2014.1.0 + +Default: ``False`` + +By default, the Salt fileserver recurses fully into all defined environments +to attempt to find files. To limit this behavior so that the fileserver only +traverses directories with SLS files and special Salt directories like _modules, +set ``fileserver_limit_traversal`` to ``True``. This might be useful for +installations where a file root has a very large number of files and performance +is impacted. + +.. code-block:: yaml + + fileserver_limit_traversal: False + .. conf_master:: hash_type ``hash_type`` diff --git a/doc/ref/configuration/minion.rst b/doc/ref/configuration/minion.rst index 7b194cd7bf00..02324f2772f9 100644 --- a/doc/ref/configuration/minion.rst +++ b/doc/ref/configuration/minion.rst @@ -852,6 +852,60 @@ the fileserver's environments. This parameter operates identically to the - /srv/salt/prod/services - /srv/salt/prod/states +.. conf_minion:: fileserver_followsymlinks + +``fileserver_followsymlinks`` +----------------------------- + +.. versionadded:: 2014.1.0 + +Default: ``True`` + +By default, the file_server follows symlinks when walking the filesystem tree. +Currently this only applies to the default roots fileserver_backend. + +.. code-block:: yaml + + fileserver_followsymlinks: True + +.. conf_minion:: fileserver_ignoresymlinks + +``fileserver_ignoresymlinks`` +----------------------------- + +.. versionadded:: 2014.1.0 + +Default: ``False`` + +If you do not want symlinks to be treated as the files they are pointing to, +set ``fileserver_ignoresymlinks`` to ``True``. By default this is set to +False. When set to ``True``, any detected symlink while listing files on the +Master will not be returned to the Minion. + +.. code-block:: yaml + + fileserver_ignoresymlinks: False + +.. conf_minion:: fileserver_limit_traversal + +``fileserver_limit_traversal`` +------------------------------ + +.. versionadded:: 2014.1.0 + +Default: ``False`` + +By default, the Salt fileserver recurses fully into all defined environments +to attempt to find files. To limit this behavior so that the fileserver only +traverses directories with SLS files and special Salt directories like _modules, +set ``fileserver_limit_traversal`` to ``True``. This might be useful for +installations where a file root has a very large number of files and performance +is impacted. + +.. code-block:: yaml + + fileserver_limit_traversal: False + .. conf_minion:: hash_type ``hash_type`` @@ -892,6 +946,21 @@ the pillar environments. prod: - /srv/pillar/prod +.. conf_minion:: file_recv_max_size + +``file_recv_max_size`` +---------------------- + +.. versionadded:: 2014.7.0 + +Default: ``100`` + +Set a hard-limit on the size of the files that can be pushed to the master. +It will be interpreted as megabytes. + +.. code-block:: yaml + + file_recv_max_size: 100 Security Settings