From f15ce62ceab97e27d6c3f21427448b80fc45198a Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Wed, 21 Aug 2013 16:49:25 -0600 Subject: [PATCH] Add more information on overriding providers As noted in IRC, if you are using a custom linux spin or derivative, it may not be apparent which provider to use when overriding providers in the minion config file. This commit adds a massive table for the pkg, service, user, and group providers which explains how they are used, to help guide the user to the correct decision when specifying a provider override. --- doc/ref/states/providers.rst | 121 +++++++++++++++++++++++++-- doc/topics/tutorials/walkthrough.rst | 6 ++ 2 files changed, 120 insertions(+), 7 deletions(-) diff --git a/doc/ref/states/providers.rst b/doc/ref/states/providers.rst index 467d3b2a8f..63fe925630 100644 --- a/doc/ref/states/providers.rst +++ b/doc/ref/states/providers.rst @@ -20,15 +20,122 @@ revert to the default service module: - enable: True - provider: service -In this instance, the basic :py:mod:`~salt.modules.service` module will replace -the :py:mod:`~salt.modules.systemd` module which is used by default on Arch -Linux, and the :program:`httpd` service will be managed using -:program:`sysvinit`. +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. -.. note:: +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 in the section below. + +Setting a Provider in the Minion Config File +============================================ + +.. _`issue tracker`: https://github.com/saltstack/salt/issues + +Sometimes, when running Salt on custom Linux spins, or distros that are derived +from other distros, Salt does not successfully detect providers. The providers +which are most likely to be affected by this are: + +- pkg +- service +- user +- group + +When something like this happens, rather than specifying the provider manually +in each state, it easier to use the :conf_minion:`providers` parameter in the +minion config file to set the provider. + +If you end up needing to override a provider because it was not detected, +please let us know! File an issue on the `issue tracker`_, and provide the +output from the :mod:`grains.items ` 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)`` +win_pkg Windows +yumpkg RedHat-based distros and derivatives (utilizes the + ``yum`` and ``rpmUtils`` modules) +yumpkg5 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 Linux (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 +openbsdservice +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_user Solaris-based OSes using ``groupadd(1M)`` +win_groupadd Windows +======================= ======================================================= - You can also set a provider globally in the minion config - :conf_minion:`providers`. Arbitrary Module Redirects ========================== diff --git a/doc/topics/tutorials/walkthrough.rst b/doc/topics/tutorials/walkthrough.rst index 887f83508d..1251feef2b 100644 --- a/doc/topics/tutorials/walkthrough.rst +++ b/doc/topics/tutorials/walkthrough.rst @@ -331,6 +331,12 @@ yum on Red Hat based systems, apt on Debian systems, etc.: salt '*' pkg.install vim +.. note:: + Some custom Linux spins and derivatives of other distros are not properly + detected by Salt. If the above command returns an error message saying that + ``pkg.install`` is not available, then you may need to override the pkg + provider. This process is explained :doc:`here `. + The :mod:`network.interfaces ` function will list all interfaces on a minion, along with their IP addresses, netmasks, MAC addresses, etc: