fPaste.me

A free, anonymous, minimalist and open source paste tool.


Untitled
16-06-2021 08:57:19
Anonymous
[Trace - 08:51:54 AM] Sending notification 'textDocument/didChange'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls",
"version": 20
},
"contentChanges": [
{
"range": {
"start": {
"line": 11,
"character": 6
},
"end": {
"line": 11,
"character": 7
}
},
"rangeLength": 1,
"text": ""
}
]
}


[Trace - 08:51:55 AM] Sending request 'textDocument/documentSymbol - (36)'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls"
}
}


[Trace - 08:51:55 AM] Received response 'textDocument/documentSymbol - (36)' in 19ms.
Result: [
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 2
},
"start": {
"character": 4,
"line": 2
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 4,
"line": 2
}
},
"kind": 19,
"name": "pkgs"
}
],
"detail": "Ensure that the package is installed, and that it is the correct version\n(if specified).\n\nNote:\n Any argument which is either a) not explicitly defined for this state,\n or b) not a global state argument like ``saltenv``, or\n ``reload_modules``, will be passed through to the call to\n ``pkg.install`` to install the package(s). For example, you can include\n a ``disablerepo`` argument on platforms that use yum/dnf to disable\n that repo:\n\n mypkg:\n pkg.installed:\n - disablerepo: base,updates\n\n To see what is supported, check :ref:`this page <virtual-pkg>` to find\n the documentation for your platform's ``pkg`` module, then look at the\n documentation for the ``install`` function.\n\n Any argument that is passed through to the ``install`` function, which\n is not defined for that function, will be silently ignored.\n\n:param str name:\n The name of the package to be installed. This parameter is ignored if\n either \"pkgs\" or \"sources\" is used. Additionally, please note that this\n option can only be used to install packages from a software repository.\n To install a package file manually, use the \"sources\" option detailed\n below.\n\n:param str version:\n Install a specific version of a package. This option is ignored if\n \"sources\" is used. Currently, this option is supported\n for the following pkg providers: :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`pkgin <salt.modules.pkgin>`,\n :mod:`win_pkg <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`. The version number includes the\n release designation where applicable, to allow Salt to target a\n specific release of a given version. When in doubt, using the\n ``pkg.latest_version`` function for an uninstalled package will tell\n you the version available.\n\n # salt myminion pkg.latest_version vim-enhanced\n myminion:\n 2:7.4.160-1.el7\n\n .. important::\n As of version 2015.8.7, for distros which use yum/dnf, packages\n which have a version with a nonzero epoch (that is, versions which\n start with a number followed by a colon like in the\n ``pkg.latest_version`` output above) must have the epoch included\n when specifying the version number. For example:\n\n vim-enhanced:\n pkg.installed:\n - version: 2:7.4.160-1.el7\n\n In version 2015.8.9, an **ignore_epoch** argument has been added to\n :py:mod:`pkg.installed <salt.states.pkg.installed>`,\n :py:mod:`pkg.removed <salt.states.pkg.removed>`, and\n :py:mod:`pkg.purged <salt.states.pkg.purged>` states, which\n causes the epoch to be disregarded when the state checks to see if\n the desired version was installed.\n\n Also, while this function is not yet implemented for all pkg frontends,\n :mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` will\n show all versions available in the various repositories for a given\n package, irrespective of whether or not it is installed.\n\n # salt myminion pkg.list_repo_pkgs bash\n myminion:\n ----------\n bash:\n - 4.2.46-21.el7_3\n - 4.2.46-20.el7_2\n\n This function was first added for :mod:`pkg.list_repo_pkgs\n <salt.modules.yumpkg.list_repo_pkgs>` in 2014.1.0, and was expanded to\n :py:func:`Debian/Ubuntu <salt.modules.aptpkg.list_repo_pkgs>` and\n :py:func:`Arch Linux <salt.modules.pacman.list_repo_pkgs>`-based\n distros in the 2017.7.0 release.\n\n The version strings returned by either of these functions can be used\n as version specifiers in pkg states.\n\n You can install a specific version when using the ``pkgs`` argument by\n including the version after the package:\n\n common_packages:\n pkg.installed:\n - pkgs:\n - unzip\n - dos2unix\n - salt-minion: 2015.8.5-1.el6\n\n If the version given is the string ``latest``, the latest available\n package version will be installed à la ``pkg.latest``.\n\n **WILDCARD VERSIONS**\n\n As of the 2017.7.0 release, this state now supports wildcards in\n package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu,\n RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be\n useful for packages where the release name is built into the version in\n some way, such as for RHEL/CentOS which typically has version numbers\n like ``1.2.34-5.el7``. An example of the usage for this would be:\n\n mypkg:\n pkg.installed:\n - version: '1.2.34*'\n\n Keep in mind that using wildcard versions will result in a slower state\n run since Salt must gather the available versions of the specified\n packages and figure out which of them match the specified wildcard\n expression.\n\n:param bool refresh:\n This parameter controls whether or not the package repo database is\n updated prior to installing the requested package(s).\n\n If ``True``, the package database will be refreshed (``apt-get\n update`` or equivalent, depending on platform) before installing.\n\n If ``False``, the package database will *not* be refreshed before\n installing.\n\n If unset, then Salt treats package database refreshes differently\n depending on whether or not a ``pkg`` state has been executed already\n during the current Salt run. Once a refresh has been performed in a\n ``pkg`` state, for the remainder of that Salt run no other refreshes\n will be performed for ``pkg`` states which do not explicitly set\n ``refresh`` to ``True``. This prevents needless additional refreshes\n from slowing down the Salt run.\n\n:param str cache_valid_time:\n\n New in version 2016.11.0\n\n This parameter sets the value in seconds after which the cache is\n marked as invalid, and a cache update is necessary. This overwrites\n the ``refresh`` parameter's default behavior.\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - cache_valid_time: 300\n - allow_updates: True\n - hold: False\n\n In this case, a refresh will not take place for 5 minutes since the last\n ``apt-get update`` was executed on the system.\n\n Note:\n\n This parameter is available only on Debian based distributions and\n has no effect on the rest.\n\n:param str fromrepo:\n Specify a repository from which to install\n\n Note:\n\n Distros which use APT (Debian, Ubuntu, etc.) do not have a concept\n of repositories, in the same way as YUM-based distros do. When a\n source is added, it is assigned to a given release. Consider the\n following source configuration:\n\n deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main\n\n The packages provided by this source would be made available via\n the ``precise`` release, therefore ``fromrepo`` would need to be\n set to ``precise`` for Salt to install the package from this\n source.\n\n Having multiple sources in the same release may result in the\n default install candidate being newer than what is desired. If this\n is the case, the desired version must be specified using the\n ``version`` parameter.\n\n If the ``pkgs`` parameter is being used to install multiple\n packages in the same state, then instead of using ``version``,\n use the method of version specification described in the **Multiple\n Package Installation Options** section below.\n\n Running the shell command ``apt-cache policy pkgname`` on a minion\n can help elucidate the APT configuration and aid in properly\n configuring states:\n\n root@saltmaster:~# salt ubuntu01 cmd.run 'apt-cache policy ffmpeg'\n ubuntu01:\n ffmpeg:\n Installed: (none)\n Candidate: 7:0.10.11-1~precise1\n Version table:\n 7:0.10.11-1~precise1 0\n 500 http://ppa.launchpad.net/jon-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages\n 4:0.8.10-0ubuntu0.12.04.1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main amd64 Packages\n 500 http://security.ubuntu.com/ubuntu/ precise-security/main amd64 Packages\n 4:0.8.1-0ubuntu1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages\n\n The release is located directly after the source's URL. The actual\n release name is the part before the slash, so to install version\n **4:0.8.10-0ubuntu0.12.04.1** either ``precise-updates`` or\n ``precise-security`` could be used for the ``fromrepo`` value.\n\n:param bool skip_verify:\n Skip the GPG verification check for the package to be installed\n\n:param bool skip_suggestions:\n Force strict package naming. Disables lookup of package alternatives.\n\n New in version 2014.1.1\n\n:param bool resolve_capabilities:\n Turn on resolving capabilities. This allow one to name \"provides\" or alias names for packages.\n\n New in version 2018.3.0\n\n:param bool allow_updates:\n Allow the package to be updated outside Salt's control (e.g. auto\n updates on Windows). This means a package on the Minion can have a\n newer version than the latest available in the repository without\n enforcing a re-installation of the package.\n\n New in version 2014.7.0\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - allow_updates: True\n - hold: False\n\n:param bool pkg_verify:\n\n New in version 2014.7.0\n\n For requested packages that are already installed and would not be\n targeted for upgrade or downgrade, use pkg.verify to determine if any\n of the files installed by the package have been altered. If files have\n been altered, the reinstall option of pkg.install is used to force a\n reinstall. Types to ignore can be passed to pkg.verify. Additionally,\n ``verify_options`` can be used to modify further the behavior of\n pkg.verify. See examples below. Currently, this option is supported\n for the following pkg providers: :mod:`yumpkg <salt.modules.yumpkg>`.\n\n Examples:\n\n httpd:\n pkg.installed:\n - version: 2.2.15-30.el6.centos\n - pkg_verify: True\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n - verify_options:\n - nodeps\n - nofiledigest\n\n:param list ignore_types:\n List of types to ignore when verifying the package\n\n New in version 2014.7.0\n\n:param list verify_options:\n List of additional options to pass when verifying the package. These\n options will be added to the ``rpm -V`` command, prepended with ``--``\n (for example, when ``nodeps`` is passed in this option, ``rpm -V`` will\n be run with ``--nodeps``).\n\n New in version 2016.11.0\n\n:param bool normalize:\n Normalize the package name by removing the architecture, if the\n architecture of the package is different from the architecture of the\n operating system. The ability to disable this behavior is useful for\n poorly-created packages which include the architecture as an actual\n part of the name, such as kernel modules which match a specific kernel\n version.\n\n New in version 2014.7.0\n\n Example:\n\n gpfs.gplbin-2.6.32-279.31.1.el6.x86_64:\n pkg.installed:\n - normalize: False\n\n:param bool ignore_epoch:\n If this option is not explicitly set, and there is no epoch in the\n desired package version, the epoch will be implicitly ignored. Set this\n argument to ``True`` to explicitly ignore the epoch, and ``False`` to\n strictly enforce it.\n\n New in version 2015.8.9\n\n Changed in version 3001\n In prior releases, the default behavior was to strictly enforce\n epochs unless this argument was set to ``True``.\n\n|\n\n**MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)**\n\n:param list pkgs:\n A list of packages to install from a software repository. All packages\n listed under ``pkgs`` will be installed via a single command.\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar\n - baz\n - hold: True\n\n ``NOTE:`` For :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`winrepo <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`,\n version numbers can be specified\n in the ``pkgs`` argument. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n\n Additionally, :mod:`ebuild <salt.modules.ebuild>`, :mod:`pacman\n <salt.modules.pacman>`, :mod:`zypper <salt.modules.zypper>`,\n :mod:`yum/dnf <salt.modules.yumpkg>`, and :mod:`apt\n <salt.modules.aptpkg>` support the ``<``, ``<=``, ``>=``, and ``>``\n operators for more control over what versions will be installed. For\n example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: '>=1.2.3-4'\n - baz\n\n ``NOTE:`` When using comparison operators, the expression must be enclosed\n in quotes to avoid a YAML render error.\n\n With :mod:`ebuild <salt.modules.ebuild>` is also possible to specify a\n use flag list and/or if the given packages should be in\n package.accept_keywords file and/or the overlay from which you want the\n package to be installed. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo: '~'\n - bar: '~>=1.2:slot::overlay[use,-otheruse]'\n - baz\n\n:param list sources:\n A list of packages to install, along with the source URI or local path\n from which to install each package. In the example below, ``foo``,\n ``bar``, ``baz``, etc. refer to the name of the package, as it would\n appear in the output of the ``pkg.version`` or ``pkg.list_pkgs`` salt\n CLI commands.\n\n mypkgs:\n pkg.installed:\n - sources:\n - foo: salt://rpms/foo.rpm\n - bar: http://somesite.org/bar.rpm\n - baz: ftp://someothersite.org/baz.rpm\n - qux: /minion/path/to/qux.rpm\n\n**PLATFORM-SPECIFIC ARGUMENTS**\n\nThese are specific to each OS. If it does not apply to the execution\nmodule for your OS, it is ignored.\n\n:param bool hold:\n Force the package to be held at the current installed version.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2014.7.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param bool update_holds:\n If ``True``, and this function would update the package version, any\n packages which are being held will be temporarily unheld so that they\n can be updated. Otherwise, if this function attempts to update a held\n package, the held package(s) will be skipped and the state will fail.\n By default, this parameter is set to ``False``.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2016.11.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param list names:\n A list of packages to install from a software repository. Each package\n will be installed individually by the package manager.\n\n Warning:\n\n Unlike ``pkgs``, the ``names`` parameter cannot specify a version.\n In addition, it makes a separate call to the package management\n frontend to install each package, whereas ``pkgs`` makes just a\n single call. It is therefore recommended to use ``pkgs`` instead of\n ``names`` to install multiple packages, both for the additional\n features and the performance improvement that it brings.\n\n:param bool install_recommends:\n Whether to install the packages marked as recommended. Default is\n ``True``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - install_recommends: False\n\n:param bool only_upgrade:\n Only upgrade the packages, if they are already installed. Default is\n ``False``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - only_upgrade: True\n\n Note:\n If this parameter is set to True and the package is not already\n installed, the state will fail.\n\n:param bool report_reboot_exit_codes:\n If the installer exits with a recognized exit code indicating that\n a reboot is required, the module function\n\n *win_system.set_reboot_required_witnessed*\n\n will be called, preserving the knowledge of this event\n for the remainder of the current boot session. For the time being,\n ``3010`` is the only recognized exit code,\n but this is subject to future refinement.\n The value of this param\n defaults to ``True``. This parameter has no effect\n on non-Windows systems.\n\n New in version 2016.11.0\n\n ms vcpp installed:\n pkg.installed:\n - name: ms-vcpp\n - version: 10.0.40219\n - report_reboot_exit_codes: False\n\n:return:\n A dictionary containing the state of the software installation\n:rtype dict:\n\nNote:\n\n The ``pkg.installed`` state supports the usage of ``reload_modules``.\n This functionality allows you to force Salt to reload all modules. In\n many cases, Salt is clever enough to transparently reload the modules.\n For example, if you install a package, Salt reloads modules because some\n other module or state might require the package which was installed.\n However, there are some edge cases where this may not be the case, which\n is what ``reload_modules`` is meant to resolve.\n\n You should only use ``reload_modules`` if your ``pkg.installed`` does some\n sort of installation where if you do not reload the modules future items\n in your state which rely on the software being installed will fail. Please\n see the :ref:`Reloading Modules <reloading-modules>` documentation for more\n information.\n\n.. seealso:: unless and onlyif\n\n If running pkg commands together with :ref:`aggregate <mod-aggregate-state>`\n isn't an option, you can use the :ref:`creates <creates-requisite>`,\n :ref:`unless <unless-requisite>`, or :ref:`onlyif <onlyif-requisite>`\n syntax to skip a full package run. This can be helpful in large environments\n with multiple states that include requisites for packages to be installed.\n\n # Using creates for a simple single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - creates:\n - /etc/nginx/nginx.conf\n\n # Using file.file_exists for a single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.file_exists\n args:\n - /etc/nginx/nginx.conf\n\n # Using unless with a shell test\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless: test -f /etc/nginx/nginx.conf\n\n # Using file.search for a two-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.search\n args:\n - /etc/nginx/nginx.conf\n - 'user www-data;'\n\n The above examples use different methods to reasonably ensure\n that a package has already been installed. First, with checking for a\n file that would be created with the package. Second, by checking for\n specific text within a file that would be created or managed by salt.\n With these requisists satisfied, creates/unless will return ``True`` and the\n ``pkg.installed`` state will be skipped.\n\n # Example of state run without unless used\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: All specified packages are already installed\n Started: 20:11:56.388331\n Duration: 4290.0 ms\n Changes:\n\n # Example of state run using unless requisite\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: unless condition is true\n Started: 20:10:50.659215\n Duration: 1530.0 ms\n Changes:\n\n The result is a reduction of almost 3 seconds. In larger environments,\n small reductions in waiting time can add up.\n\n :ref:`Unless Requisite <unless-requisite>`",
"selectionRange": {
"end": {
"character": 15,
"line": 1
},
"start": {
"character": 2,
"line": 1
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 2,
"line": 1
}
},
"kind": 19,
"name": "pkg.installed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 19,
"line": 0
},
"start": {
"character": 0,
"line": 0
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 0,
"line": 0
}
},
"kind": 19,
"name": "saltmaster.packages"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 7
},
"start": {
"character": 4,
"line": 7
}
},
"range": {
"end": {
"character": 4,
"line": 8
},
"start": {
"character": 4,
"line": 7
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 8
},
"start": {
"character": 4,
"line": 8
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 4,
"line": 8
}
},
"kind": 19,
"name": "minute"
}
],
"detail": "Verifies that the specified cron job is present for the specified user.\nIt is recommended to use `identifier`. Otherwise the cron job is installed\ntwice if you change the name.\nFor more advanced information about what exactly can be set in the cron\ntiming parameters, check your cron system's documentation. Most Unix-like\nsystems' cron documentation can be found via the crontab man page:\n``man 5 crontab``.\n\nname\n The command that should be executed by the cron job.\n\nuser\n The name of the user whose crontab needs to be modified, defaults to\n the root user\n\nminute\n The information to be set into the minute section, this can be any\n string supported by your cron system's the minute field. Default is\n ``*``\n\nhour\n The information to be set in the hour section. Default is ``*``\n\ndaymonth\n The information to be set in the day of month section. Default is ``*``\n\nmonth\n The information to be set in the month section. Default is ``*``\n\ndayweek\n The information to be set in the day of week section. Default is ``*``\n\ncomment\n User comment to be added on line previous the cron job\n\ncommented\n The cron job is set commented (prefixed with ``#DISABLED#``).\n Defaults to False.\n\n New in version 2016.3.0\n\nidentifier\n Custom-defined identifier for tracking the cron line for future crontab\n edits. This defaults to the state name\n\nspecial\n A special keyword to specify periodicity (eg. @reboot, @hourly...).\n Quotes must be used, otherwise PyYAML will strip the '@' sign.\n\n New in version 2016.3.0",
"selectionRange": {
"end": {
"character": 14,
"line": 6
},
"start": {
"character": 2,
"line": 6
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 2,
"line": 6
}
},
"kind": 19,
"name": "cron.present"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 5
},
"start": {
"character": 0,
"line": 5
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 0,
"line": 5
}
},
"kind": 19,
"name": "git -C /srv/salt pull -q"
},
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 17,
"line": 11
},
"start": {
"character": 2,
"line": 11
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 2,
"line": 11
}
},
"kind": 19,
"name": "file - target"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 20,
"line": 10
},
"start": {
"character": 0,
"line": 10
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 0,
"line": 10
}
},
"kind": 19,
"name": "/srv/git/salt-states"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 15
},
"start": {
"character": 4,
"line": 15
}
},
"range": {
"end": {
"character": 4,
"line": 16
},
"start": {
"character": 4,
"line": 15
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 16
},
"start": {
"character": 4,
"line": 16
}
},
"range": {
"end": {
"character": 4,
"line": 17
},
"start": {
"character": 4,
"line": 16
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 17
},
"start": {
"character": 4,
"line": 17
}
},
"range": {
"end": {
"character": 4,
"line": 18
},
"start": {
"character": 4,
"line": 17
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 18
},
"start": {
"character": 4,
"line": 18
}
},
"range": {
"end": {
"character": 4,
"line": 19
},
"start": {
"character": 4,
"line": 18
}
},
"kind": 19,
"name": "source"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 12,
"line": 19
},
"start": {
"character": 4,
"line": 19
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 4,
"line": 19
}
},
"kind": 19,
"name": "template"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 14
},
"start": {
"character": 2,
"line": 14
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 2,
"line": 14
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 46,
"line": 13
},
"start": {
"character": 0,
"line": 13
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 0,
"line": 13
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.service"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 23
},
"start": {
"character": 4,
"line": 23
}
},
"range": {
"end": {
"character": 4,
"line": 24
},
"start": {
"character": 4,
"line": 23
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 24
},
"start": {
"character": 4,
"line": 24
}
},
"range": {
"end": {
"character": 4,
"line": 25
},
"start": {
"character": 4,
"line": 24
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 25
},
"start": {
"character": 4,
"line": 25
}
},
"range": {
"end": {
"character": 4,
"line": 26
},
"start": {
"character": 4,
"line": 25
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 26
},
"start": {
"character": 4,
"line": 26
}
},
"range": {
"end": {
"character": 4,
"line": 27
},
"start": {
"character": 4,
"line": 26
}
},
"kind": 19,
"name": "source"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 28
},
"start": {
"character": 6,
"line": 28
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 6,
"line": 28
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 27
},
"start": {
"character": 4,
"line": 27
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 4,
"line": 27
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 22
},
"start": {
"character": 2,
"line": 22
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 2,
"line": 22
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 44,
"line": 21
},
"start": {
"character": 0,
"line": 21
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 0,
"line": 21
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.timer"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 32
},
"start": {
"character": 4,
"line": 32
}
},
"range": {
"end": {
"character": 4,
"line": 33
},
"start": {
"character": 4,
"line": 32
}
},
"kind": 19,
"name": "enable"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 34
},
"start": {
"character": 6,
"line": 34
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 6,
"line": 34
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 33
},
"start": {
"character": 4,
"line": 33
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 4,
"line": 33
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Ensure that the service is running\n\nname\n The name of the init or rc script used to manage the service\n\nenable\n Set the service to be enabled at boot time, ``True`` sets the service\n to be enabled, ``False`` sets the named service to be disabled. The\n default is ``None``, which does not enable or disable anything.\n\nsig\n The string to search for when looking for the service process with ps\n\ninit_delay\n Some services may not be truly available for a short period after their\n startup script indicates to the system that they are. Provide an\n 'init_delay' to specify that this state should wait an additional given\n number of seconds after a service has started before returning. Useful\n for requisite states wherein a dependent state might assume a service\n has started but is not yet fully initialized.\n\nno_block : False\n **For systemd minions only.** Starts the service using ``--no-block``.\n\n New in version 2017.7.0\n\ntimeout\n **For Windows minions only.**\n\n The time in seconds to wait for the service to start before returning.\n Default is the default for :py:func:`win_service.start\n <salt.modules.win_service.start>`.\n\n New in version 2017.7.9,2018.3.4\n\nunmask : False\n **For systemd minions only.** Set to ``True`` to remove an indefinite\n mask before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nunmask_runtime : False\n **For systemd minions only.** Set to ``True`` to remove a runtime mask\n before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nwait : 3\n **For systemd minions only.** Passed through when using\n :py:func:`service.status <salt.modules.systemd_service.status>` to\n determine whether the service is running or not.\n\n New in version 2019.2.3\n\nNote:\n ``watch`` can be used with service.running to restart a service when\n another state changes ( example: a file.managed state that creates the\n service's config file ). More details regarding ``watch`` can be found\n in the :ref:`Requisites <requisites>` documentation.",
"selectionRange": {
"end": {
"character": 17,
"line": 31
},
"start": {
"character": 2,
"line": 31
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 2,
"line": 31
}
},
"kind": 19,
"name": "service.running"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 30
},
"start": {
"character": 0,
"line": 30
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 0,
"line": 30
}
},
"kind": 19,
"name": "rootco-salt-backup.timer"
}
]


[Trace - 08:51:55 AM] Sending notification 'textDocument/didChange'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls",
"version": 21
},
"contentChanges": [
{
"range": {
"start": {
"line": 11,
"character": 6
},
"end": {
"line": 11,
"character": 6
}
},
"rangeLength": 0,
"text": "."
}
]
}


[Trace - 08:51:56 AM] Sending request 'textDocument/documentSymbol - (37)'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls"
}
}


[Trace - 08:51:56 AM] Received response 'textDocument/documentSymbol - (37)' in 19ms.
Result: [
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 2
},
"start": {
"character": 4,
"line": 2
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 4,
"line": 2
}
},
"kind": 19,
"name": "pkgs"
}
],
"detail": "Ensure that the package is installed, and that it is the correct version\n(if specified).\n\nNote:\n Any argument which is either a) not explicitly defined for this state,\n or b) not a global state argument like ``saltenv``, or\n ``reload_modules``, will be passed through to the call to\n ``pkg.install`` to install the package(s). For example, you can include\n a ``disablerepo`` argument on platforms that use yum/dnf to disable\n that repo:\n\n mypkg:\n pkg.installed:\n - disablerepo: base,updates\n\n To see what is supported, check :ref:`this page <virtual-pkg>` to find\n the documentation for your platform's ``pkg`` module, then look at the\n documentation for the ``install`` function.\n\n Any argument that is passed through to the ``install`` function, which\n is not defined for that function, will be silently ignored.\n\n:param str name:\n The name of the package to be installed. This parameter is ignored if\n either \"pkgs\" or \"sources\" is used. Additionally, please note that this\n option can only be used to install packages from a software repository.\n To install a package file manually, use the \"sources\" option detailed\n below.\n\n:param str version:\n Install a specific version of a package. This option is ignored if\n \"sources\" is used. Currently, this option is supported\n for the following pkg providers: :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`pkgin <salt.modules.pkgin>`,\n :mod:`win_pkg <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`. The version number includes the\n release designation where applicable, to allow Salt to target a\n specific release of a given version. When in doubt, using the\n ``pkg.latest_version`` function for an uninstalled package will tell\n you the version available.\n\n # salt myminion pkg.latest_version vim-enhanced\n myminion:\n 2:7.4.160-1.el7\n\n .. important::\n As of version 2015.8.7, for distros which use yum/dnf, packages\n which have a version with a nonzero epoch (that is, versions which\n start with a number followed by a colon like in the\n ``pkg.latest_version`` output above) must have the epoch included\n when specifying the version number. For example:\n\n vim-enhanced:\n pkg.installed:\n - version: 2:7.4.160-1.el7\n\n In version 2015.8.9, an **ignore_epoch** argument has been added to\n :py:mod:`pkg.installed <salt.states.pkg.installed>`,\n :py:mod:`pkg.removed <salt.states.pkg.removed>`, and\n :py:mod:`pkg.purged <salt.states.pkg.purged>` states, which\n causes the epoch to be disregarded when the state checks to see if\n the desired version was installed.\n\n Also, while this function is not yet implemented for all pkg frontends,\n :mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` will\n show all versions available in the various repositories for a given\n package, irrespective of whether or not it is installed.\n\n # salt myminion pkg.list_repo_pkgs bash\n myminion:\n ----------\n bash:\n - 4.2.46-21.el7_3\n - 4.2.46-20.el7_2\n\n This function was first added for :mod:`pkg.list_repo_pkgs\n <salt.modules.yumpkg.list_repo_pkgs>` in 2014.1.0, and was expanded to\n :py:func:`Debian/Ubuntu <salt.modules.aptpkg.list_repo_pkgs>` and\n :py:func:`Arch Linux <salt.modules.pacman.list_repo_pkgs>`-based\n distros in the 2017.7.0 release.\n\n The version strings returned by either of these functions can be used\n as version specifiers in pkg states.\n\n You can install a specific version when using the ``pkgs`` argument by\n including the version after the package:\n\n common_packages:\n pkg.installed:\n - pkgs:\n - unzip\n - dos2unix\n - salt-minion: 2015.8.5-1.el6\n\n If the version given is the string ``latest``, the latest available\n package version will be installed à la ``pkg.latest``.\n\n **WILDCARD VERSIONS**\n\n As of the 2017.7.0 release, this state now supports wildcards in\n package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu,\n RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be\n useful for packages where the release name is built into the version in\n some way, such as for RHEL/CentOS which typically has version numbers\n like ``1.2.34-5.el7``. An example of the usage for this would be:\n\n mypkg:\n pkg.installed:\n - version: '1.2.34*'\n\n Keep in mind that using wildcard versions will result in a slower state\n run since Salt must gather the available versions of the specified\n packages and figure out which of them match the specified wildcard\n expression.\n\n:param bool refresh:\n This parameter controls whether or not the package repo database is\n updated prior to installing the requested package(s).\n\n If ``True``, the package database will be refreshed (``apt-get\n update`` or equivalent, depending on platform) before installing.\n\n If ``False``, the package database will *not* be refreshed before\n installing.\n\n If unset, then Salt treats package database refreshes differently\n depending on whether or not a ``pkg`` state has been executed already\n during the current Salt run. Once a refresh has been performed in a\n ``pkg`` state, for the remainder of that Salt run no other refreshes\n will be performed for ``pkg`` states which do not explicitly set\n ``refresh`` to ``True``. This prevents needless additional refreshes\n from slowing down the Salt run.\n\n:param str cache_valid_time:\n\n New in version 2016.11.0\n\n This parameter sets the value in seconds after which the cache is\n marked as invalid, and a cache update is necessary. This overwrites\n the ``refresh`` parameter's default behavior.\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - cache_valid_time: 300\n - allow_updates: True\n - hold: False\n\n In this case, a refresh will not take place for 5 minutes since the last\n ``apt-get update`` was executed on the system.\n\n Note:\n\n This parameter is available only on Debian based distributions and\n has no effect on the rest.\n\n:param str fromrepo:\n Specify a repository from which to install\n\n Note:\n\n Distros which use APT (Debian, Ubuntu, etc.) do not have a concept\n of repositories, in the same way as YUM-based distros do. When a\n source is added, it is assigned to a given release. Consider the\n following source configuration:\n\n deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main\n\n The packages provided by this source would be made available via\n the ``precise`` release, therefore ``fromrepo`` would need to be\n set to ``precise`` for Salt to install the package from this\n source.\n\n Having multiple sources in the same release may result in the\n default install candidate being newer than what is desired. If this\n is the case, the desired version must be specified using the\n ``version`` parameter.\n\n If the ``pkgs`` parameter is being used to install multiple\n packages in the same state, then instead of using ``version``,\n use the method of version specification described in the **Multiple\n Package Installation Options** section below.\n\n Running the shell command ``apt-cache policy pkgname`` on a minion\n can help elucidate the APT configuration and aid in properly\n configuring states:\n\n root@saltmaster:~# salt ubuntu01 cmd.run 'apt-cache policy ffmpeg'\n ubuntu01:\n ffmpeg:\n Installed: (none)\n Candidate: 7:0.10.11-1~precise1\n Version table:\n 7:0.10.11-1~precise1 0\n 500 http://ppa.launchpad.net/jon-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages\n 4:0.8.10-0ubuntu0.12.04.1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main amd64 Packages\n 500 http://security.ubuntu.com/ubuntu/ precise-security/main amd64 Packages\n 4:0.8.1-0ubuntu1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages\n\n The release is located directly after the source's URL. The actual\n release name is the part before the slash, so to install version\n **4:0.8.10-0ubuntu0.12.04.1** either ``precise-updates`` or\n ``precise-security`` could be used for the ``fromrepo`` value.\n\n:param bool skip_verify:\n Skip the GPG verification check for the package to be installed\n\n:param bool skip_suggestions:\n Force strict package naming. Disables lookup of package alternatives.\n\n New in version 2014.1.1\n\n:param bool resolve_capabilities:\n Turn on resolving capabilities. This allow one to name \"provides\" or alias names for packages.\n\n New in version 2018.3.0\n\n:param bool allow_updates:\n Allow the package to be updated outside Salt's control (e.g. auto\n updates on Windows). This means a package on the Minion can have a\n newer version than the latest available in the repository without\n enforcing a re-installation of the package.\n\n New in version 2014.7.0\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - allow_updates: True\n - hold: False\n\n:param bool pkg_verify:\n\n New in version 2014.7.0\n\n For requested packages that are already installed and would not be\n targeted for upgrade or downgrade, use pkg.verify to determine if any\n of the files installed by the package have been altered. If files have\n been altered, the reinstall option of pkg.install is used to force a\n reinstall. Types to ignore can be passed to pkg.verify. Additionally,\n ``verify_options`` can be used to modify further the behavior of\n pkg.verify. See examples below. Currently, this option is supported\n for the following pkg providers: :mod:`yumpkg <salt.modules.yumpkg>`.\n\n Examples:\n\n httpd:\n pkg.installed:\n - version: 2.2.15-30.el6.centos\n - pkg_verify: True\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n - verify_options:\n - nodeps\n - nofiledigest\n\n:param list ignore_types:\n List of types to ignore when verifying the package\n\n New in version 2014.7.0\n\n:param list verify_options:\n List of additional options to pass when verifying the package. These\n options will be added to the ``rpm -V`` command, prepended with ``--``\n (for example, when ``nodeps`` is passed in this option, ``rpm -V`` will\n be run with ``--nodeps``).\n\n New in version 2016.11.0\n\n:param bool normalize:\n Normalize the package name by removing the architecture, if the\n architecture of the package is different from the architecture of the\n operating system. The ability to disable this behavior is useful for\n poorly-created packages which include the architecture as an actual\n part of the name, such as kernel modules which match a specific kernel\n version.\n\n New in version 2014.7.0\n\n Example:\n\n gpfs.gplbin-2.6.32-279.31.1.el6.x86_64:\n pkg.installed:\n - normalize: False\n\n:param bool ignore_epoch:\n If this option is not explicitly set, and there is no epoch in the\n desired package version, the epoch will be implicitly ignored. Set this\n argument to ``True`` to explicitly ignore the epoch, and ``False`` to\n strictly enforce it.\n\n New in version 2015.8.9\n\n Changed in version 3001\n In prior releases, the default behavior was to strictly enforce\n epochs unless this argument was set to ``True``.\n\n|\n\n**MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)**\n\n:param list pkgs:\n A list of packages to install from a software repository. All packages\n listed under ``pkgs`` will be installed via a single command.\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar\n - baz\n - hold: True\n\n ``NOTE:`` For :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`winrepo <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`,\n version numbers can be specified\n in the ``pkgs`` argument. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n\n Additionally, :mod:`ebuild <salt.modules.ebuild>`, :mod:`pacman\n <salt.modules.pacman>`, :mod:`zypper <salt.modules.zypper>`,\n :mod:`yum/dnf <salt.modules.yumpkg>`, and :mod:`apt\n <salt.modules.aptpkg>` support the ``<``, ``<=``, ``>=``, and ``>``\n operators for more control over what versions will be installed. For\n example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: '>=1.2.3-4'\n - baz\n\n ``NOTE:`` When using comparison operators, the expression must be enclosed\n in quotes to avoid a YAML render error.\n\n With :mod:`ebuild <salt.modules.ebuild>` is also possible to specify a\n use flag list and/or if the given packages should be in\n package.accept_keywords file and/or the overlay from which you want the\n package to be installed. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo: '~'\n - bar: '~>=1.2:slot::overlay[use,-otheruse]'\n - baz\n\n:param list sources:\n A list of packages to install, along with the source URI or local path\n from which to install each package. In the example below, ``foo``,\n ``bar``, ``baz``, etc. refer to the name of the package, as it would\n appear in the output of the ``pkg.version`` or ``pkg.list_pkgs`` salt\n CLI commands.\n\n mypkgs:\n pkg.installed:\n - sources:\n - foo: salt://rpms/foo.rpm\n - bar: http://somesite.org/bar.rpm\n - baz: ftp://someothersite.org/baz.rpm\n - qux: /minion/path/to/qux.rpm\n\n**PLATFORM-SPECIFIC ARGUMENTS**\n\nThese are specific to each OS. If it does not apply to the execution\nmodule for your OS, it is ignored.\n\n:param bool hold:\n Force the package to be held at the current installed version.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2014.7.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param bool update_holds:\n If ``True``, and this function would update the package version, any\n packages which are being held will be temporarily unheld so that they\n can be updated. Otherwise, if this function attempts to update a held\n package, the held package(s) will be skipped and the state will fail.\n By default, this parameter is set to ``False``.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2016.11.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param list names:\n A list of packages to install from a software repository. Each package\n will be installed individually by the package manager.\n\n Warning:\n\n Unlike ``pkgs``, the ``names`` parameter cannot specify a version.\n In addition, it makes a separate call to the package management\n frontend to install each package, whereas ``pkgs`` makes just a\n single call. It is therefore recommended to use ``pkgs`` instead of\n ``names`` to install multiple packages, both for the additional\n features and the performance improvement that it brings.\n\n:param bool install_recommends:\n Whether to install the packages marked as recommended. Default is\n ``True``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - install_recommends: False\n\n:param bool only_upgrade:\n Only upgrade the packages, if they are already installed. Default is\n ``False``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - only_upgrade: True\n\n Note:\n If this parameter is set to True and the package is not already\n installed, the state will fail.\n\n:param bool report_reboot_exit_codes:\n If the installer exits with a recognized exit code indicating that\n a reboot is required, the module function\n\n *win_system.set_reboot_required_witnessed*\n\n will be called, preserving the knowledge of this event\n for the remainder of the current boot session. For the time being,\n ``3010`` is the only recognized exit code,\n but this is subject to future refinement.\n The value of this param\n defaults to ``True``. This parameter has no effect\n on non-Windows systems.\n\n New in version 2016.11.0\n\n ms vcpp installed:\n pkg.installed:\n - name: ms-vcpp\n - version: 10.0.40219\n - report_reboot_exit_codes: False\n\n:return:\n A dictionary containing the state of the software installation\n:rtype dict:\n\nNote:\n\n The ``pkg.installed`` state supports the usage of ``reload_modules``.\n This functionality allows you to force Salt to reload all modules. In\n many cases, Salt is clever enough to transparently reload the modules.\n For example, if you install a package, Salt reloads modules because some\n other module or state might require the package which was installed.\n However, there are some edge cases where this may not be the case, which\n is what ``reload_modules`` is meant to resolve.\n\n You should only use ``reload_modules`` if your ``pkg.installed`` does some\n sort of installation where if you do not reload the modules future items\n in your state which rely on the software being installed will fail. Please\n see the :ref:`Reloading Modules <reloading-modules>` documentation for more\n information.\n\n.. seealso:: unless and onlyif\n\n If running pkg commands together with :ref:`aggregate <mod-aggregate-state>`\n isn't an option, you can use the :ref:`creates <creates-requisite>`,\n :ref:`unless <unless-requisite>`, or :ref:`onlyif <onlyif-requisite>`\n syntax to skip a full package run. This can be helpful in large environments\n with multiple states that include requisites for packages to be installed.\n\n # Using creates for a simple single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - creates:\n - /etc/nginx/nginx.conf\n\n # Using file.file_exists for a single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.file_exists\n args:\n - /etc/nginx/nginx.conf\n\n # Using unless with a shell test\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless: test -f /etc/nginx/nginx.conf\n\n # Using file.search for a two-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.search\n args:\n - /etc/nginx/nginx.conf\n - 'user www-data;'\n\n The above examples use different methods to reasonably ensure\n that a package has already been installed. First, with checking for a\n file that would be created with the package. Second, by checking for\n specific text within a file that would be created or managed by salt.\n With these requisists satisfied, creates/unless will return ``True`` and the\n ``pkg.installed`` state will be skipped.\n\n # Example of state run without unless used\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: All specified packages are already installed\n Started: 20:11:56.388331\n Duration: 4290.0 ms\n Changes:\n\n # Example of state run using unless requisite\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: unless condition is true\n Started: 20:10:50.659215\n Duration: 1530.0 ms\n Changes:\n\n The result is a reduction of almost 3 seconds. In larger environments,\n small reductions in waiting time can add up.\n\n :ref:`Unless Requisite <unless-requisite>`",
"selectionRange": {
"end": {
"character": 15,
"line": 1
},
"start": {
"character": 2,
"line": 1
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 2,
"line": 1
}
},
"kind": 19,
"name": "pkg.installed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 19,
"line": 0
},
"start": {
"character": 0,
"line": 0
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 0,
"line": 0
}
},
"kind": 19,
"name": "saltmaster.packages"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 7
},
"start": {
"character": 4,
"line": 7
}
},
"range": {
"end": {
"character": 4,
"line": 8
},
"start": {
"character": 4,
"line": 7
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 8
},
"start": {
"character": 4,
"line": 8
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 4,
"line": 8
}
},
"kind": 19,
"name": "minute"
}
],
"detail": "Verifies that the specified cron job is present for the specified user.\nIt is recommended to use `identifier`. Otherwise the cron job is installed\ntwice if you change the name.\nFor more advanced information about what exactly can be set in the cron\ntiming parameters, check your cron system's documentation. Most Unix-like\nsystems' cron documentation can be found via the crontab man page:\n``man 5 crontab``.\n\nname\n The command that should be executed by the cron job.\n\nuser\n The name of the user whose crontab needs to be modified, defaults to\n the root user\n\nminute\n The information to be set into the minute section, this can be any\n string supported by your cron system's the minute field. Default is\n ``*``\n\nhour\n The information to be set in the hour section. Default is ``*``\n\ndaymonth\n The information to be set in the day of month section. Default is ``*``\n\nmonth\n The information to be set in the month section. Default is ``*``\n\ndayweek\n The information to be set in the day of week section. Default is ``*``\n\ncomment\n User comment to be added on line previous the cron job\n\ncommented\n The cron job is set commented (prefixed with ``#DISABLED#``).\n Defaults to False.\n\n New in version 2016.3.0\n\nidentifier\n Custom-defined identifier for tracking the cron line for future crontab\n edits. This defaults to the state name\n\nspecial\n A special keyword to specify periodicity (eg. @reboot, @hourly...).\n Quotes must be used, otherwise PyYAML will strip the '@' sign.\n\n New in version 2016.3.0",
"selectionRange": {
"end": {
"character": 14,
"line": 6
},
"start": {
"character": 2,
"line": 6
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 2,
"line": 6
}
},
"kind": 19,
"name": "cron.present"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 5
},
"start": {
"character": 0,
"line": 5
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 0,
"line": 5
}
},
"kind": 19,
"name": "git -C /srv/salt pull -q"
},
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 18,
"line": 11
},
"start": {
"character": 2,
"line": 11
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 2,
"line": 11
}
},
"kind": 19,
"name": "file. - target"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 20,
"line": 10
},
"start": {
"character": 0,
"line": 10
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 0,
"line": 10
}
},
"kind": 19,
"name": "/srv/git/salt-states"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 15
},
"start": {
"character": 4,
"line": 15
}
},
"range": {
"end": {
"character": 4,
"line": 16
},
"start": {
"character": 4,
"line": 15
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 16
},
"start": {
"character": 4,
"line": 16
}
},
"range": {
"end": {
"character": 4,
"line": 17
},
"start": {
"character": 4,
"line": 16
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 17
},
"start": {
"character": 4,
"line": 17
}
},
"range": {
"end": {
"character": 4,
"line": 18
},
"start": {
"character": 4,
"line": 17
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 18
},
"start": {
"character": 4,
"line": 18
}
},
"range": {
"end": {
"character": 4,
"line": 19
},
"start": {
"character": 4,
"line": 18
}
},
"kind": 19,
"name": "source"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 12,
"line": 19
},
"start": {
"character": 4,
"line": 19
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 4,
"line": 19
}
},
"kind": 19,
"name": "template"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 14
},
"start": {
"character": 2,
"line": 14
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 2,
"line": 14
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 46,
"line": 13
},
"start": {
"character": 0,
"line": 13
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 0,
"line": 13
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.service"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 23
},
"start": {
"character": 4,
"line": 23
}
},
"range": {
"end": {
"character": 4,
"line": 24
},
"start": {
"character": 4,
"line": 23
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 24
},
"start": {
"character": 4,
"line": 24
}
},
"range": {
"end": {
"character": 4,
"line": 25
},
"start": {
"character": 4,
"line": 24
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 25
},
"start": {
"character": 4,
"line": 25
}
},
"range": {
"end": {
"character": 4,
"line": 26
},
"start": {
"character": 4,
"line": 25
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 26
},
"start": {
"character": 4,
"line": 26
}
},
"range": {
"end": {
"character": 4,
"line": 27
},
"start": {
"character": 4,
"line": 26
}
},
"kind": 19,
"name": "source"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 28
},
"start": {
"character": 6,
"line": 28
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 6,
"line": 28
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 27
},
"start": {
"character": 4,
"line": 27
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 4,
"line": 27
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 22
},
"start": {
"character": 2,
"line": 22
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 2,
"line": 22
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 44,
"line": 21
},
"start": {
"character": 0,
"line": 21
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 0,
"line": 21
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.timer"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 32
},
"start": {
"character": 4,
"line": 32
}
},
"range": {
"end": {
"character": 4,
"line": 33
},
"start": {
"character": 4,
"line": 32
}
},
"kind": 19,
"name": "enable"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 34
},
"start": {
"character": 6,
"line": 34
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 6,
"line": 34
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 33
},
"start": {
"character": 4,
"line": 33
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 4,
"line": 33
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Ensure that the service is running\n\nname\n The name of the init or rc script used to manage the service\n\nenable\n Set the service to be enabled at boot time, ``True`` sets the service\n to be enabled, ``False`` sets the named service to be disabled. The\n default is ``None``, which does not enable or disable anything.\n\nsig\n The string to search for when looking for the service process with ps\n\ninit_delay\n Some services may not be truly available for a short period after their\n startup script indicates to the system that they are. Provide an\n 'init_delay' to specify that this state should wait an additional given\n number of seconds after a service has started before returning. Useful\n for requisite states wherein a dependent state might assume a service\n has started but is not yet fully initialized.\n\nno_block : False\n **For systemd minions only.** Starts the service using ``--no-block``.\n\n New in version 2017.7.0\n\ntimeout\n **For Windows minions only.**\n\n The time in seconds to wait for the service to start before returning.\n Default is the default for :py:func:`win_service.start\n <salt.modules.win_service.start>`.\n\n New in version 2017.7.9,2018.3.4\n\nunmask : False\n **For systemd minions only.** Set to ``True`` to remove an indefinite\n mask before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nunmask_runtime : False\n **For systemd minions only.** Set to ``True`` to remove a runtime mask\n before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nwait : 3\n **For systemd minions only.** Passed through when using\n :py:func:`service.status <salt.modules.systemd_service.status>` to\n determine whether the service is running or not.\n\n New in version 2019.2.3\n\nNote:\n ``watch`` can be used with service.running to restart a service when\n another state changes ( example: a file.managed state that creates the\n service's config file ). More details regarding ``watch`` can be found\n in the :ref:`Requisites <requisites>` documentation.",
"selectionRange": {
"end": {
"character": 17,
"line": 31
},
"start": {
"character": 2,
"line": 31
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 2,
"line": 31
}
},
"kind": 19,
"name": "service.running"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 30
},
"start": {
"character": 0,
"line": 30
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 0,
"line": 30
}
},
"kind": 19,
"name": "rootco-salt-backup.timer"
}
]


[Trace - 08:52:36 AM] Sending notification 'textDocument/didChange'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls",
"version": 22
},
"contentChanges": [
{
"range": {
"start": {
"line": 11,
"character": 6
},
"end": {
"line": 11,
"character": 7
}
},
"rangeLength": 1,
"text": ""
}
]
}


[Trace - 08:52:36 AM] Sending request 'textDocument/documentSymbol - (38)'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls"
}
}


[Trace - 08:52:36 AM] Sending notification 'textDocument/didChange'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls",
"version": 23
},
"contentChanges": [
{
"range": {
"start": {
"line": 11,
"character": 6
},
"end": {
"line": 11,
"character": 6
}
},
"rangeLength": 0,
"text": "."
}
]
}


[Trace - 08:52:36 AM] Received response 'textDocument/documentSymbol - (38)' in 37ms.
Result: [
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 2
},
"start": {
"character": 4,
"line": 2
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 4,
"line": 2
}
},
"kind": 19,
"name": "pkgs"
}
],
"detail": "Ensure that the package is installed, and that it is the correct version\n(if specified).\n\nNote:\n Any argument which is either a) not explicitly defined for this state,\n or b) not a global state argument like ``saltenv``, or\n ``reload_modules``, will be passed through to the call to\n ``pkg.install`` to install the package(s). For example, you can include\n a ``disablerepo`` argument on platforms that use yum/dnf to disable\n that repo:\n\n mypkg:\n pkg.installed:\n - disablerepo: base,updates\n\n To see what is supported, check :ref:`this page <virtual-pkg>` to find\n the documentation for your platform's ``pkg`` module, then look at the\n documentation for the ``install`` function.\n\n Any argument that is passed through to the ``install`` function, which\n is not defined for that function, will be silently ignored.\n\n:param str name:\n The name of the package to be installed. This parameter is ignored if\n either \"pkgs\" or \"sources\" is used. Additionally, please note that this\n option can only be used to install packages from a software repository.\n To install a package file manually, use the \"sources\" option detailed\n below.\n\n:param str version:\n Install a specific version of a package. This option is ignored if\n \"sources\" is used. Currently, this option is supported\n for the following pkg providers: :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`pkgin <salt.modules.pkgin>`,\n :mod:`win_pkg <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`. The version number includes the\n release designation where applicable, to allow Salt to target a\n specific release of a given version. When in doubt, using the\n ``pkg.latest_version`` function for an uninstalled package will tell\n you the version available.\n\n # salt myminion pkg.latest_version vim-enhanced\n myminion:\n 2:7.4.160-1.el7\n\n .. important::\n As of version 2015.8.7, for distros which use yum/dnf, packages\n which have a version with a nonzero epoch (that is, versions which\n start with a number followed by a colon like in the\n ``pkg.latest_version`` output above) must have the epoch included\n when specifying the version number. For example:\n\n vim-enhanced:\n pkg.installed:\n - version: 2:7.4.160-1.el7\n\n In version 2015.8.9, an **ignore_epoch** argument has been added to\n :py:mod:`pkg.installed <salt.states.pkg.installed>`,\n :py:mod:`pkg.removed <salt.states.pkg.removed>`, and\n :py:mod:`pkg.purged <salt.states.pkg.purged>` states, which\n causes the epoch to be disregarded when the state checks to see if\n the desired version was installed.\n\n Also, while this function is not yet implemented for all pkg frontends,\n :mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` will\n show all versions available in the various repositories for a given\n package, irrespective of whether or not it is installed.\n\n # salt myminion pkg.list_repo_pkgs bash\n myminion:\n ----------\n bash:\n - 4.2.46-21.el7_3\n - 4.2.46-20.el7_2\n\n This function was first added for :mod:`pkg.list_repo_pkgs\n <salt.modules.yumpkg.list_repo_pkgs>` in 2014.1.0, and was expanded to\n :py:func:`Debian/Ubuntu <salt.modules.aptpkg.list_repo_pkgs>` and\n :py:func:`Arch Linux <salt.modules.pacman.list_repo_pkgs>`-based\n distros in the 2017.7.0 release.\n\n The version strings returned by either of these functions can be used\n as version specifiers in pkg states.\n\n You can install a specific version when using the ``pkgs`` argument by\n including the version after the package:\n\n common_packages:\n pkg.installed:\n - pkgs:\n - unzip\n - dos2unix\n - salt-minion: 2015.8.5-1.el6\n\n If the version given is the string ``latest``, the latest available\n package version will be installed à la ``pkg.latest``.\n\n **WILDCARD VERSIONS**\n\n As of the 2017.7.0 release, this state now supports wildcards in\n package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu,\n RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be\n useful for packages where the release name is built into the version in\n some way, such as for RHEL/CentOS which typically has version numbers\n like ``1.2.34-5.el7``. An example of the usage for this would be:\n\n mypkg:\n pkg.installed:\n - version: '1.2.34*'\n\n Keep in mind that using wildcard versions will result in a slower state\n run since Salt must gather the available versions of the specified\n packages and figure out which of them match the specified wildcard\n expression.\n\n:param bool refresh:\n This parameter controls whether or not the package repo database is\n updated prior to installing the requested package(s).\n\n If ``True``, the package database will be refreshed (``apt-get\n update`` or equivalent, depending on platform) before installing.\n\n If ``False``, the package database will *not* be refreshed before\n installing.\n\n If unset, then Salt treats package database refreshes differently\n depending on whether or not a ``pkg`` state has been executed already\n during the current Salt run. Once a refresh has been performed in a\n ``pkg`` state, for the remainder of that Salt run no other refreshes\n will be performed for ``pkg`` states which do not explicitly set\n ``refresh`` to ``True``. This prevents needless additional refreshes\n from slowing down the Salt run.\n\n:param str cache_valid_time:\n\n New in version 2016.11.0\n\n This parameter sets the value in seconds after which the cache is\n marked as invalid, and a cache update is necessary. This overwrites\n the ``refresh`` parameter's default behavior.\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - cache_valid_time: 300\n - allow_updates: True\n - hold: False\n\n In this case, a refresh will not take place for 5 minutes since the last\n ``apt-get update`` was executed on the system.\n\n Note:\n\n This parameter is available only on Debian based distributions and\n has no effect on the rest.\n\n:param str fromrepo:\n Specify a repository from which to install\n\n Note:\n\n Distros which use APT (Debian, Ubuntu, etc.) do not have a concept\n of repositories, in the same way as YUM-based distros do. When a\n source is added, it is assigned to a given release. Consider the\n following source configuration:\n\n deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main\n\n The packages provided by this source would be made available via\n the ``precise`` release, therefore ``fromrepo`` would need to be\n set to ``precise`` for Salt to install the package from this\n source.\n\n Having multiple sources in the same release may result in the\n default install candidate being newer than what is desired. If this\n is the case, the desired version must be specified using the\n ``version`` parameter.\n\n If the ``pkgs`` parameter is being used to install multiple\n packages in the same state, then instead of using ``version``,\n use the method of version specification described in the **Multiple\n Package Installation Options** section below.\n\n Running the shell command ``apt-cache policy pkgname`` on a minion\n can help elucidate the APT configuration and aid in properly\n configuring states:\n\n root@saltmaster:~# salt ubuntu01 cmd.run 'apt-cache policy ffmpeg'\n ubuntu01:\n ffmpeg:\n Installed: (none)\n Candidate: 7:0.10.11-1~precise1\n Version table:\n 7:0.10.11-1~precise1 0\n 500 http://ppa.launchpad.net/jon-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages\n 4:0.8.10-0ubuntu0.12.04.1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main amd64 Packages\n 500 http://security.ubuntu.com/ubuntu/ precise-security/main amd64 Packages\n 4:0.8.1-0ubuntu1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages\n\n The release is located directly after the source's URL. The actual\n release name is the part before the slash, so to install version\n **4:0.8.10-0ubuntu0.12.04.1** either ``precise-updates`` or\n ``precise-security`` could be used for the ``fromrepo`` value.\n\n:param bool skip_verify:\n Skip the GPG verification check for the package to be installed\n\n:param bool skip_suggestions:\n Force strict package naming. Disables lookup of package alternatives.\n\n New in version 2014.1.1\n\n:param bool resolve_capabilities:\n Turn on resolving capabilities. This allow one to name \"provides\" or alias names for packages.\n\n New in version 2018.3.0\n\n:param bool allow_updates:\n Allow the package to be updated outside Salt's control (e.g. auto\n updates on Windows). This means a package on the Minion can have a\n newer version than the latest available in the repository without\n enforcing a re-installation of the package.\n\n New in version 2014.7.0\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - allow_updates: True\n - hold: False\n\n:param bool pkg_verify:\n\n New in version 2014.7.0\n\n For requested packages that are already installed and would not be\n targeted for upgrade or downgrade, use pkg.verify to determine if any\n of the files installed by the package have been altered. If files have\n been altered, the reinstall option of pkg.install is used to force a\n reinstall. Types to ignore can be passed to pkg.verify. Additionally,\n ``verify_options`` can be used to modify further the behavior of\n pkg.verify. See examples below. Currently, this option is supported\n for the following pkg providers: :mod:`yumpkg <salt.modules.yumpkg>`.\n\n Examples:\n\n httpd:\n pkg.installed:\n - version: 2.2.15-30.el6.centos\n - pkg_verify: True\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n - verify_options:\n - nodeps\n - nofiledigest\n\n:param list ignore_types:\n List of types to ignore when verifying the package\n\n New in version 2014.7.0\n\n:param list verify_options:\n List of additional options to pass when verifying the package. These\n options will be added to the ``rpm -V`` command, prepended with ``--``\n (for example, when ``nodeps`` is passed in this option, ``rpm -V`` will\n be run with ``--nodeps``).\n\n New in version 2016.11.0\n\n:param bool normalize:\n Normalize the package name by removing the architecture, if the\n architecture of the package is different from the architecture of the\n operating system. The ability to disable this behavior is useful for\n poorly-created packages which include the architecture as an actual\n part of the name, such as kernel modules which match a specific kernel\n version.\n\n New in version 2014.7.0\n\n Example:\n\n gpfs.gplbin-2.6.32-279.31.1.el6.x86_64:\n pkg.installed:\n - normalize: False\n\n:param bool ignore_epoch:\n If this option is not explicitly set, and there is no epoch in the\n desired package version, the epoch will be implicitly ignored. Set this\n argument to ``True`` to explicitly ignore the epoch, and ``False`` to\n strictly enforce it.\n\n New in version 2015.8.9\n\n Changed in version 3001\n In prior releases, the default behavior was to strictly enforce\n epochs unless this argument was set to ``True``.\n\n|\n\n**MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)**\n\n:param list pkgs:\n A list of packages to install from a software repository. All packages\n listed under ``pkgs`` will be installed via a single command.\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar\n - baz\n - hold: True\n\n ``NOTE:`` For :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`winrepo <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`,\n version numbers can be specified\n in the ``pkgs`` argument. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n\n Additionally, :mod:`ebuild <salt.modules.ebuild>`, :mod:`pacman\n <salt.modules.pacman>`, :mod:`zypper <salt.modules.zypper>`,\n :mod:`yum/dnf <salt.modules.yumpkg>`, and :mod:`apt\n <salt.modules.aptpkg>` support the ``<``, ``<=``, ``>=``, and ``>``\n operators for more control over what versions will be installed. For\n example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: '>=1.2.3-4'\n - baz\n\n ``NOTE:`` When using comparison operators, the expression must be enclosed\n in quotes to avoid a YAML render error.\n\n With :mod:`ebuild <salt.modules.ebuild>` is also possible to specify a\n use flag list and/or if the given packages should be in\n package.accept_keywords file and/or the overlay from which you want the\n package to be installed. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo: '~'\n - bar: '~>=1.2:slot::overlay[use,-otheruse]'\n - baz\n\n:param list sources:\n A list of packages to install, along with the source URI or local path\n from which to install each package. In the example below, ``foo``,\n ``bar``, ``baz``, etc. refer to the name of the package, as it would\n appear in the output of the ``pkg.version`` or ``pkg.list_pkgs`` salt\n CLI commands.\n\n mypkgs:\n pkg.installed:\n - sources:\n - foo: salt://rpms/foo.rpm\n - bar: http://somesite.org/bar.rpm\n - baz: ftp://someothersite.org/baz.rpm\n - qux: /minion/path/to/qux.rpm\n\n**PLATFORM-SPECIFIC ARGUMENTS**\n\nThese are specific to each OS. If it does not apply to the execution\nmodule for your OS, it is ignored.\n\n:param bool hold:\n Force the package to be held at the current installed version.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2014.7.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param bool update_holds:\n If ``True``, and this function would update the package version, any\n packages which are being held will be temporarily unheld so that they\n can be updated. Otherwise, if this function attempts to update a held\n package, the held package(s) will be skipped and the state will fail.\n By default, this parameter is set to ``False``.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2016.11.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param list names:\n A list of packages to install from a software repository. Each package\n will be installed individually by the package manager.\n\n Warning:\n\n Unlike ``pkgs``, the ``names`` parameter cannot specify a version.\n In addition, it makes a separate call to the package management\n frontend to install each package, whereas ``pkgs`` makes just a\n single call. It is therefore recommended to use ``pkgs`` instead of\n ``names`` to install multiple packages, both for the additional\n features and the performance improvement that it brings.\n\n:param bool install_recommends:\n Whether to install the packages marked as recommended. Default is\n ``True``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - install_recommends: False\n\n:param bool only_upgrade:\n Only upgrade the packages, if they are already installed. Default is\n ``False``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - only_upgrade: True\n\n Note:\n If this parameter is set to True and the package is not already\n installed, the state will fail.\n\n:param bool report_reboot_exit_codes:\n If the installer exits with a recognized exit code indicating that\n a reboot is required, the module function\n\n *win_system.set_reboot_required_witnessed*\n\n will be called, preserving the knowledge of this event\n for the remainder of the current boot session. For the time being,\n ``3010`` is the only recognized exit code,\n but this is subject to future refinement.\n The value of this param\n defaults to ``True``. This parameter has no effect\n on non-Windows systems.\n\n New in version 2016.11.0\n\n ms vcpp installed:\n pkg.installed:\n - name: ms-vcpp\n - version: 10.0.40219\n - report_reboot_exit_codes: False\n\n:return:\n A dictionary containing the state of the software installation\n:rtype dict:\n\nNote:\n\n The ``pkg.installed`` state supports the usage of ``reload_modules``.\n This functionality allows you to force Salt to reload all modules. In\n many cases, Salt is clever enough to transparently reload the modules.\n For example, if you install a package, Salt reloads modules because some\n other module or state might require the package which was installed.\n However, there are some edge cases where this may not be the case, which\n is what ``reload_modules`` is meant to resolve.\n\n You should only use ``reload_modules`` if your ``pkg.installed`` does some\n sort of installation where if you do not reload the modules future items\n in your state which rely on the software being installed will fail. Please\n see the :ref:`Reloading Modules <reloading-modules>` documentation for more\n information.\n\n.. seealso:: unless and onlyif\n\n If running pkg commands together with :ref:`aggregate <mod-aggregate-state>`\n isn't an option, you can use the :ref:`creates <creates-requisite>`,\n :ref:`unless <unless-requisite>`, or :ref:`onlyif <onlyif-requisite>`\n syntax to skip a full package run. This can be helpful in large environments\n with multiple states that include requisites for packages to be installed.\n\n # Using creates for a simple single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - creates:\n - /etc/nginx/nginx.conf\n\n # Using file.file_exists for a single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.file_exists\n args:\n - /etc/nginx/nginx.conf\n\n # Using unless with a shell test\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless: test -f /etc/nginx/nginx.conf\n\n # Using file.search for a two-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.search\n args:\n - /etc/nginx/nginx.conf\n - 'user www-data;'\n\n The above examples use different methods to reasonably ensure\n that a package has already been installed. First, with checking for a\n file that would be created with the package. Second, by checking for\n specific text within a file that would be created or managed by salt.\n With these requisists satisfied, creates/unless will return ``True`` and the\n ``pkg.installed`` state will be skipped.\n\n # Example of state run without unless used\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: All specified packages are already installed\n Started: 20:11:56.388331\n Duration: 4290.0 ms\n Changes:\n\n # Example of state run using unless requisite\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: unless condition is true\n Started: 20:10:50.659215\n Duration: 1530.0 ms\n Changes:\n\n The result is a reduction of almost 3 seconds. In larger environments,\n small reductions in waiting time can add up.\n\n :ref:`Unless Requisite <unless-requisite>`",
"selectionRange": {
"end": {
"character": 15,
"line": 1
},
"start": {
"character": 2,
"line": 1
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 2,
"line": 1
}
},
"kind": 19,
"name": "pkg.installed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 19,
"line": 0
},
"start": {
"character": 0,
"line": 0
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 0,
"line": 0
}
},
"kind": 19,
"name": "saltmaster.packages"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 7
},
"start": {
"character": 4,
"line": 7
}
},
"range": {
"end": {
"character": 4,
"line": 8
},
"start": {
"character": 4,
"line": 7
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 8
},
"start": {
"character": 4,
"line": 8
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 4,
"line": 8
}
},
"kind": 19,
"name": "minute"
}
],
"detail": "Verifies that the specified cron job is present for the specified user.\nIt is recommended to use `identifier`. Otherwise the cron job is installed\ntwice if you change the name.\nFor more advanced information about what exactly can be set in the cron\ntiming parameters, check your cron system's documentation. Most Unix-like\nsystems' cron documentation can be found via the crontab man page:\n``man 5 crontab``.\n\nname\n The command that should be executed by the cron job.\n\nuser\n The name of the user whose crontab needs to be modified, defaults to\n the root user\n\nminute\n The information to be set into the minute section, this can be any\n string supported by your cron system's the minute field. Default is\n ``*``\n\nhour\n The information to be set in the hour section. Default is ``*``\n\ndaymonth\n The information to be set in the day of month section. Default is ``*``\n\nmonth\n The information to be set in the month section. Default is ``*``\n\ndayweek\n The information to be set in the day of week section. Default is ``*``\n\ncomment\n User comment to be added on line previous the cron job\n\ncommented\n The cron job is set commented (prefixed with ``#DISABLED#``).\n Defaults to False.\n\n New in version 2016.3.0\n\nidentifier\n Custom-defined identifier for tracking the cron line for future crontab\n edits. This defaults to the state name\n\nspecial\n A special keyword to specify periodicity (eg. @reboot, @hourly...).\n Quotes must be used, otherwise PyYAML will strip the '@' sign.\n\n New in version 2016.3.0",
"selectionRange": {
"end": {
"character": 14,
"line": 6
},
"start": {
"character": 2,
"line": 6
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 2,
"line": 6
}
},
"kind": 19,
"name": "cron.present"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 5
},
"start": {
"character": 0,
"line": 5
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 0,
"line": 5
}
},
"kind": 19,
"name": "git -C /srv/salt pull -q"
},
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 17,
"line": 11
},
"start": {
"character": 2,
"line": 11
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 2,
"line": 11
}
},
"kind": 19,
"name": "file - target"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 20,
"line": 10
},
"start": {
"character": 0,
"line": 10
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 0,
"line": 10
}
},
"kind": 19,
"name": "/srv/git/salt-states"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 15
},
"start": {
"character": 4,
"line": 15
}
},
"range": {
"end": {
"character": 4,
"line": 16
},
"start": {
"character": 4,
"line": 15
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 16
},
"start": {
"character": 4,
"line": 16
}
},
"range": {
"end": {
"character": 4,
"line": 17
},
"start": {
"character": 4,
"line": 16
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 17
},
"start": {
"character": 4,
"line": 17
}
},
"range": {
"end": {
"character": 4,
"line": 18
},
"start": {
"character": 4,
"line": 17
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 18
},
"start": {
"character": 4,
"line": 18
}
},
"range": {
"end": {
"character": 4,
"line": 19
},
"start": {
"character": 4,
"line": 18
}
},
"kind": 19,
"name": "source"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 12,
"line": 19
},
"start": {
"character": 4,
"line": 19
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 4,
"line": 19
}
},
"kind": 19,
"name": "template"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 14
},
"start": {
"character": 2,
"line": 14
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 2,
"line": 14
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 46,
"line": 13
},
"start": {
"character": 0,
"line": 13
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 0,
"line": 13
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.service"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 23
},
"start": {
"character": 4,
"line": 23
}
},
"range": {
"end": {
"character": 4,
"line": 24
},
"start": {
"character": 4,
"line": 23
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 24
},
"start": {
"character": 4,
"line": 24
}
},
"range": {
"end": {
"character": 4,
"line": 25
},
"start": {
"character": 4,
"line": 24
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 25
},
"start": {
"character": 4,
"line": 25
}
},
"range": {
"end": {
"character": 4,
"line": 26
},
"start": {
"character": 4,
"line": 25
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 26
},
"start": {
"character": 4,
"line": 26
}
},
"range": {
"end": {
"character": 4,
"line": 27
},
"start": {
"character": 4,
"line": 26
}
},
"kind": 19,
"name": "source"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 28
},
"start": {
"character": 6,
"line": 28
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 6,
"line": 28
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 27
},
"start": {
"character": 4,
"line": 27
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 4,
"line": 27
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 22
},
"start": {
"character": 2,
"line": 22
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 2,
"line": 22
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 44,
"line": 21
},
"start": {
"character": 0,
"line": 21
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 0,
"line": 21
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.timer"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 32
},
"start": {
"character": 4,
"line": 32
}
},
"range": {
"end": {
"character": 4,
"line": 33
},
"start": {
"character": 4,
"line": 32
}
},
"kind": 19,
"name": "enable"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 34
},
"start": {
"character": 6,
"line": 34
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 6,
"line": 34
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 33
},
"start": {
"character": 4,
"line": 33
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 4,
"line": 33
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Ensure that the service is running\n\nname\n The name of the init or rc script used to manage the service\n\nenable\n Set the service to be enabled at boot time, ``True`` sets the service\n to be enabled, ``False`` sets the named service to be disabled. The\n default is ``None``, which does not enable or disable anything.\n\nsig\n The string to search for when looking for the service process with ps\n\ninit_delay\n Some services may not be truly available for a short period after their\n startup script indicates to the system that they are. Provide an\n 'init_delay' to specify that this state should wait an additional given\n number of seconds after a service has started before returning. Useful\n for requisite states wherein a dependent state might assume a service\n has started but is not yet fully initialized.\n\nno_block : False\n **For systemd minions only.** Starts the service using ``--no-block``.\n\n New in version 2017.7.0\n\ntimeout\n **For Windows minions only.**\n\n The time in seconds to wait for the service to start before returning.\n Default is the default for :py:func:`win_service.start\n <salt.modules.win_service.start>`.\n\n New in version 2017.7.9,2018.3.4\n\nunmask : False\n **For systemd minions only.** Set to ``True`` to remove an indefinite\n mask before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nunmask_runtime : False\n **For systemd minions only.** Set to ``True`` to remove a runtime mask\n before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nwait : 3\n **For systemd minions only.** Passed through when using\n :py:func:`service.status <salt.modules.systemd_service.status>` to\n determine whether the service is running or not.\n\n New in version 2019.2.3\n\nNote:\n ``watch`` can be used with service.running to restart a service when\n another state changes ( example: a file.managed state that creates the\n service's config file ). More details regarding ``watch`` can be found\n in the :ref:`Requisites <requisites>` documentation.",
"selectionRange": {
"end": {
"character": 17,
"line": 31
},
"start": {
"character": 2,
"line": 31
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 2,
"line": 31
}
},
"kind": 19,
"name": "service.running"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 30
},
"start": {
"character": 0,
"line": 30
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 0,
"line": 30
}
},
"kind": 19,
"name": "rootco-salt-backup.timer"
}
]


[Trace - 08:52:37 AM] Sending request 'textDocument/documentSymbol - (39)'.
Params: {
"textDocument": {
"uri": "file:///home/dan/packages/github.com/sysrich/salt-states/salt/master.sls"
}
}


[Trace - 08:52:37 AM] Received response 'textDocument/documentSymbol - (39)' in 19ms.
Result: [
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 2
},
"start": {
"character": 4,
"line": 2
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 4,
"line": 2
}
},
"kind": 19,
"name": "pkgs"
}
],
"detail": "Ensure that the package is installed, and that it is the correct version\n(if specified).\n\nNote:\n Any argument which is either a) not explicitly defined for this state,\n or b) not a global state argument like ``saltenv``, or\n ``reload_modules``, will be passed through to the call to\n ``pkg.install`` to install the package(s). For example, you can include\n a ``disablerepo`` argument on platforms that use yum/dnf to disable\n that repo:\n\n mypkg:\n pkg.installed:\n - disablerepo: base,updates\n\n To see what is supported, check :ref:`this page <virtual-pkg>` to find\n the documentation for your platform's ``pkg`` module, then look at the\n documentation for the ``install`` function.\n\n Any argument that is passed through to the ``install`` function, which\n is not defined for that function, will be silently ignored.\n\n:param str name:\n The name of the package to be installed. This parameter is ignored if\n either \"pkgs\" or \"sources\" is used. Additionally, please note that this\n option can only be used to install packages from a software repository.\n To install a package file manually, use the \"sources\" option detailed\n below.\n\n:param str version:\n Install a specific version of a package. This option is ignored if\n \"sources\" is used. Currently, this option is supported\n for the following pkg providers: :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`pkgin <salt.modules.pkgin>`,\n :mod:`win_pkg <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`. The version number includes the\n release designation where applicable, to allow Salt to target a\n specific release of a given version. When in doubt, using the\n ``pkg.latest_version`` function for an uninstalled package will tell\n you the version available.\n\n # salt myminion pkg.latest_version vim-enhanced\n myminion:\n 2:7.4.160-1.el7\n\n .. important::\n As of version 2015.8.7, for distros which use yum/dnf, packages\n which have a version with a nonzero epoch (that is, versions which\n start with a number followed by a colon like in the\n ``pkg.latest_version`` output above) must have the epoch included\n when specifying the version number. For example:\n\n vim-enhanced:\n pkg.installed:\n - version: 2:7.4.160-1.el7\n\n In version 2015.8.9, an **ignore_epoch** argument has been added to\n :py:mod:`pkg.installed <salt.states.pkg.installed>`,\n :py:mod:`pkg.removed <salt.states.pkg.removed>`, and\n :py:mod:`pkg.purged <salt.states.pkg.purged>` states, which\n causes the epoch to be disregarded when the state checks to see if\n the desired version was installed.\n\n Also, while this function is not yet implemented for all pkg frontends,\n :mod:`pkg.list_repo_pkgs <salt.modules.yumpkg.list_repo_pkgs>` will\n show all versions available in the various repositories for a given\n package, irrespective of whether or not it is installed.\n\n # salt myminion pkg.list_repo_pkgs bash\n myminion:\n ----------\n bash:\n - 4.2.46-21.el7_3\n - 4.2.46-20.el7_2\n\n This function was first added for :mod:`pkg.list_repo_pkgs\n <salt.modules.yumpkg.list_repo_pkgs>` in 2014.1.0, and was expanded to\n :py:func:`Debian/Ubuntu <salt.modules.aptpkg.list_repo_pkgs>` and\n :py:func:`Arch Linux <salt.modules.pacman.list_repo_pkgs>`-based\n distros in the 2017.7.0 release.\n\n The version strings returned by either of these functions can be used\n as version specifiers in pkg states.\n\n You can install a specific version when using the ``pkgs`` argument by\n including the version after the package:\n\n common_packages:\n pkg.installed:\n - pkgs:\n - unzip\n - dos2unix\n - salt-minion: 2015.8.5-1.el6\n\n If the version given is the string ``latest``, the latest available\n package version will be installed à la ``pkg.latest``.\n\n **WILDCARD VERSIONS**\n\n As of the 2017.7.0 release, this state now supports wildcards in\n package versions for SUSE SLES/Leap/Tumbleweed, Debian/Ubuntu,\n RHEL/CentOS, Arch Linux, and their derivatives. Using wildcards can be\n useful for packages where the release name is built into the version in\n some way, such as for RHEL/CentOS which typically has version numbers\n like ``1.2.34-5.el7``. An example of the usage for this would be:\n\n mypkg:\n pkg.installed:\n - version: '1.2.34*'\n\n Keep in mind that using wildcard versions will result in a slower state\n run since Salt must gather the available versions of the specified\n packages and figure out which of them match the specified wildcard\n expression.\n\n:param bool refresh:\n This parameter controls whether or not the package repo database is\n updated prior to installing the requested package(s).\n\n If ``True``, the package database will be refreshed (``apt-get\n update`` or equivalent, depending on platform) before installing.\n\n If ``False``, the package database will *not* be refreshed before\n installing.\n\n If unset, then Salt treats package database refreshes differently\n depending on whether or not a ``pkg`` state has been executed already\n during the current Salt run. Once a refresh has been performed in a\n ``pkg`` state, for the remainder of that Salt run no other refreshes\n will be performed for ``pkg`` states which do not explicitly set\n ``refresh`` to ``True``. This prevents needless additional refreshes\n from slowing down the Salt run.\n\n:param str cache_valid_time:\n\n New in version 2016.11.0\n\n This parameter sets the value in seconds after which the cache is\n marked as invalid, and a cache update is necessary. This overwrites\n the ``refresh`` parameter's default behavior.\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - cache_valid_time: 300\n - allow_updates: True\n - hold: False\n\n In this case, a refresh will not take place for 5 minutes since the last\n ``apt-get update`` was executed on the system.\n\n Note:\n\n This parameter is available only on Debian based distributions and\n has no effect on the rest.\n\n:param str fromrepo:\n Specify a repository from which to install\n\n Note:\n\n Distros which use APT (Debian, Ubuntu, etc.) do not have a concept\n of repositories, in the same way as YUM-based distros do. When a\n source is added, it is assigned to a given release. Consider the\n following source configuration:\n\n deb http://ppa.launchpad.net/saltstack/salt/ubuntu precise main\n\n The packages provided by this source would be made available via\n the ``precise`` release, therefore ``fromrepo`` would need to be\n set to ``precise`` for Salt to install the package from this\n source.\n\n Having multiple sources in the same release may result in the\n default install candidate being newer than what is desired. If this\n is the case, the desired version must be specified using the\n ``version`` parameter.\n\n If the ``pkgs`` parameter is being used to install multiple\n packages in the same state, then instead of using ``version``,\n use the method of version specification described in the **Multiple\n Package Installation Options** section below.\n\n Running the shell command ``apt-cache policy pkgname`` on a minion\n can help elucidate the APT configuration and aid in properly\n configuring states:\n\n root@saltmaster:~# salt ubuntu01 cmd.run 'apt-cache policy ffmpeg'\n ubuntu01:\n ffmpeg:\n Installed: (none)\n Candidate: 7:0.10.11-1~precise1\n Version table:\n 7:0.10.11-1~precise1 0\n 500 http://ppa.launchpad.net/jon-severinsson/ffmpeg/ubuntu/ precise/main amd64 Packages\n 4:0.8.10-0ubuntu0.12.04.1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise-updates/main amd64 Packages\n 500 http://security.ubuntu.com/ubuntu/ precise-security/main amd64 Packages\n 4:0.8.1-0ubuntu1 0\n 500 http://us.archive.ubuntu.com/ubuntu/ precise/main amd64 Packages\n\n The release is located directly after the source's URL. The actual\n release name is the part before the slash, so to install version\n **4:0.8.10-0ubuntu0.12.04.1** either ``precise-updates`` or\n ``precise-security`` could be used for the ``fromrepo`` value.\n\n:param bool skip_verify:\n Skip the GPG verification check for the package to be installed\n\n:param bool skip_suggestions:\n Force strict package naming. Disables lookup of package alternatives.\n\n New in version 2014.1.1\n\n:param bool resolve_capabilities:\n Turn on resolving capabilities. This allow one to name \"provides\" or alias names for packages.\n\n New in version 2018.3.0\n\n:param bool allow_updates:\n Allow the package to be updated outside Salt's control (e.g. auto\n updates on Windows). This means a package on the Minion can have a\n newer version than the latest available in the repository without\n enforcing a re-installation of the package.\n\n New in version 2014.7.0\n\n Example:\n\n httpd:\n pkg.installed:\n - fromrepo: mycustomrepo\n - skip_verify: True\n - skip_suggestions: True\n - version: 2.0.6~ubuntu3\n - refresh: True\n - allow_updates: True\n - hold: False\n\n:param bool pkg_verify:\n\n New in version 2014.7.0\n\n For requested packages that are already installed and would not be\n targeted for upgrade or downgrade, use pkg.verify to determine if any\n of the files installed by the package have been altered. If files have\n been altered, the reinstall option of pkg.install is used to force a\n reinstall. Types to ignore can be passed to pkg.verify. Additionally,\n ``verify_options`` can be used to modify further the behavior of\n pkg.verify. See examples below. Currently, this option is supported\n for the following pkg providers: :mod:`yumpkg <salt.modules.yumpkg>`.\n\n Examples:\n\n httpd:\n pkg.installed:\n - version: 2.2.15-30.el6.centos\n - pkg_verify: True\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n - pkg_verify:\n - ignore_types:\n - config\n - doc\n - verify_options:\n - nodeps\n - nofiledigest\n\n:param list ignore_types:\n List of types to ignore when verifying the package\n\n New in version 2014.7.0\n\n:param list verify_options:\n List of additional options to pass when verifying the package. These\n options will be added to the ``rpm -V`` command, prepended with ``--``\n (for example, when ``nodeps`` is passed in this option, ``rpm -V`` will\n be run with ``--nodeps``).\n\n New in version 2016.11.0\n\n:param bool normalize:\n Normalize the package name by removing the architecture, if the\n architecture of the package is different from the architecture of the\n operating system. The ability to disable this behavior is useful for\n poorly-created packages which include the architecture as an actual\n part of the name, such as kernel modules which match a specific kernel\n version.\n\n New in version 2014.7.0\n\n Example:\n\n gpfs.gplbin-2.6.32-279.31.1.el6.x86_64:\n pkg.installed:\n - normalize: False\n\n:param bool ignore_epoch:\n If this option is not explicitly set, and there is no epoch in the\n desired package version, the epoch will be implicitly ignored. Set this\n argument to ``True`` to explicitly ignore the epoch, and ``False`` to\n strictly enforce it.\n\n New in version 2015.8.9\n\n Changed in version 3001\n In prior releases, the default behavior was to strictly enforce\n epochs unless this argument was set to ``True``.\n\n|\n\n**MULTIPLE PACKAGE INSTALLATION OPTIONS: (not supported in pkgng)**\n\n:param list pkgs:\n A list of packages to install from a software repository. All packages\n listed under ``pkgs`` will be installed via a single command.\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar\n - baz\n - hold: True\n\n ``NOTE:`` For :mod:`apt <salt.modules.aptpkg>`,\n :mod:`ebuild <salt.modules.ebuild>`,\n :mod:`pacman <salt.modules.pacman>`,\n :mod:`winrepo <salt.modules.win_pkg>`,\n :mod:`yumpkg <salt.modules.yumpkg>`, and\n :mod:`zypper <salt.modules.zypper>`,\n version numbers can be specified\n in the ``pkgs`` argument. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: 1.2.3-4\n - baz\n\n Additionally, :mod:`ebuild <salt.modules.ebuild>`, :mod:`pacman\n <salt.modules.pacman>`, :mod:`zypper <salt.modules.zypper>`,\n :mod:`yum/dnf <salt.modules.yumpkg>`, and :mod:`apt\n <salt.modules.aptpkg>` support the ``<``, ``<=``, ``>=``, and ``>``\n operators for more control over what versions will be installed. For\n example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo\n - bar: '>=1.2.3-4'\n - baz\n\n ``NOTE:`` When using comparison operators, the expression must be enclosed\n in quotes to avoid a YAML render error.\n\n With :mod:`ebuild <salt.modules.ebuild>` is also possible to specify a\n use flag list and/or if the given packages should be in\n package.accept_keywords file and/or the overlay from which you want the\n package to be installed. For example:\n\n mypkgs:\n pkg.installed:\n - pkgs:\n - foo: '~'\n - bar: '~>=1.2:slot::overlay[use,-otheruse]'\n - baz\n\n:param list sources:\n A list of packages to install, along with the source URI or local path\n from which to install each package. In the example below, ``foo``,\n ``bar``, ``baz``, etc. refer to the name of the package, as it would\n appear in the output of the ``pkg.version`` or ``pkg.list_pkgs`` salt\n CLI commands.\n\n mypkgs:\n pkg.installed:\n - sources:\n - foo: salt://rpms/foo.rpm\n - bar: http://somesite.org/bar.rpm\n - baz: ftp://someothersite.org/baz.rpm\n - qux: /minion/path/to/qux.rpm\n\n**PLATFORM-SPECIFIC ARGUMENTS**\n\nThese are specific to each OS. If it does not apply to the execution\nmodule for your OS, it is ignored.\n\n:param bool hold:\n Force the package to be held at the current installed version.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2014.7.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param bool update_holds:\n If ``True``, and this function would update the package version, any\n packages which are being held will be temporarily unheld so that they\n can be updated. Otherwise, if this function attempts to update a held\n package, the held package(s) will be skipped and the state will fail.\n By default, this parameter is set to ``False``.\n\n Supported on YUM/DNF & APT based systems.\n\n New in version 2016.11.0\n\n Supported on Zypper-based systems.\n\n New in version 3003\n\n:param list names:\n A list of packages to install from a software repository. Each package\n will be installed individually by the package manager.\n\n Warning:\n\n Unlike ``pkgs``, the ``names`` parameter cannot specify a version.\n In addition, it makes a separate call to the package management\n frontend to install each package, whereas ``pkgs`` makes just a\n single call. It is therefore recommended to use ``pkgs`` instead of\n ``names`` to install multiple packages, both for the additional\n features and the performance improvement that it brings.\n\n:param bool install_recommends:\n Whether to install the packages marked as recommended. Default is\n ``True``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - install_recommends: False\n\n:param bool only_upgrade:\n Only upgrade the packages, if they are already installed. Default is\n ``False``. Currently only works with APT-based systems.\n\n New in version 2015.5.0\n\n httpd:\n pkg.installed:\n - only_upgrade: True\n\n Note:\n If this parameter is set to True and the package is not already\n installed, the state will fail.\n\n:param bool report_reboot_exit_codes:\n If the installer exits with a recognized exit code indicating that\n a reboot is required, the module function\n\n *win_system.set_reboot_required_witnessed*\n\n will be called, preserving the knowledge of this event\n for the remainder of the current boot session. For the time being,\n ``3010`` is the only recognized exit code,\n but this is subject to future refinement.\n The value of this param\n defaults to ``True``. This parameter has no effect\n on non-Windows systems.\n\n New in version 2016.11.0\n\n ms vcpp installed:\n pkg.installed:\n - name: ms-vcpp\n - version: 10.0.40219\n - report_reboot_exit_codes: False\n\n:return:\n A dictionary containing the state of the software installation\n:rtype dict:\n\nNote:\n\n The ``pkg.installed`` state supports the usage of ``reload_modules``.\n This functionality allows you to force Salt to reload all modules. In\n many cases, Salt is clever enough to transparently reload the modules.\n For example, if you install a package, Salt reloads modules because some\n other module or state might require the package which was installed.\n However, there are some edge cases where this may not be the case, which\n is what ``reload_modules`` is meant to resolve.\n\n You should only use ``reload_modules`` if your ``pkg.installed`` does some\n sort of installation where if you do not reload the modules future items\n in your state which rely on the software being installed will fail. Please\n see the :ref:`Reloading Modules <reloading-modules>` documentation for more\n information.\n\n.. seealso:: unless and onlyif\n\n If running pkg commands together with :ref:`aggregate <mod-aggregate-state>`\n isn't an option, you can use the :ref:`creates <creates-requisite>`,\n :ref:`unless <unless-requisite>`, or :ref:`onlyif <onlyif-requisite>`\n syntax to skip a full package run. This can be helpful in large environments\n with multiple states that include requisites for packages to be installed.\n\n # Using creates for a simple single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - creates:\n - /etc/nginx/nginx.conf\n\n # Using file.file_exists for a single-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.file_exists\n args:\n - /etc/nginx/nginx.conf\n\n # Using unless with a shell test\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless: test -f /etc/nginx/nginx.conf\n\n # Using file.search for a two-factor check\n install_nginx:\n pkg.installed:\n - name: nginx\n - unless:\n - fun: file.search\n args:\n - /etc/nginx/nginx.conf\n - 'user www-data;'\n\n The above examples use different methods to reasonably ensure\n that a package has already been installed. First, with checking for a\n file that would be created with the package. Second, by checking for\n specific text within a file that would be created or managed by salt.\n With these requisists satisfied, creates/unless will return ``True`` and the\n ``pkg.installed`` state will be skipped.\n\n # Example of state run without unless used\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: All specified packages are already installed\n Started: 20:11:56.388331\n Duration: 4290.0 ms\n Changes:\n\n # Example of state run using unless requisite\n salt 'saltdev' state.apply nginx\n saltdev:\n ----------\n ID: install_nginx\n Function: pkg.installed\n Name: nginx\n Result: True\n Comment: unless condition is true\n Started: 20:10:50.659215\n Duration: 1530.0 ms\n Changes:\n\n The result is a reduction of almost 3 seconds. In larger environments,\n small reductions in waiting time can add up.\n\n :ref:`Unless Requisite <unless-requisite>`",
"selectionRange": {
"end": {
"character": 15,
"line": 1
},
"start": {
"character": 2,
"line": 1
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 2,
"line": 1
}
},
"kind": 19,
"name": "pkg.installed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 19,
"line": 0
},
"start": {
"character": 0,
"line": 0
}
},
"range": {
"end": {
"character": 0,
"line": 5
},
"start": {
"character": 0,
"line": 0
}
},
"kind": 19,
"name": "saltmaster.packages"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 7
},
"start": {
"character": 4,
"line": 7
}
},
"range": {
"end": {
"character": 4,
"line": 8
},
"start": {
"character": 4,
"line": 7
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 8
},
"start": {
"character": 4,
"line": 8
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 4,
"line": 8
}
},
"kind": 19,
"name": "minute"
}
],
"detail": "Verifies that the specified cron job is present for the specified user.\nIt is recommended to use `identifier`. Otherwise the cron job is installed\ntwice if you change the name.\nFor more advanced information about what exactly can be set in the cron\ntiming parameters, check your cron system's documentation. Most Unix-like\nsystems' cron documentation can be found via the crontab man page:\n``man 5 crontab``.\n\nname\n The command that should be executed by the cron job.\n\nuser\n The name of the user whose crontab needs to be modified, defaults to\n the root user\n\nminute\n The information to be set into the minute section, this can be any\n string supported by your cron system's the minute field. Default is\n ``*``\n\nhour\n The information to be set in the hour section. Default is ``*``\n\ndaymonth\n The information to be set in the day of month section. Default is ``*``\n\nmonth\n The information to be set in the month section. Default is ``*``\n\ndayweek\n The information to be set in the day of week section. Default is ``*``\n\ncomment\n User comment to be added on line previous the cron job\n\ncommented\n The cron job is set commented (prefixed with ``#DISABLED#``).\n Defaults to False.\n\n New in version 2016.3.0\n\nidentifier\n Custom-defined identifier for tracking the cron line for future crontab\n edits. This defaults to the state name\n\nspecial\n A special keyword to specify periodicity (eg. @reboot, @hourly...).\n Quotes must be used, otherwise PyYAML will strip the '@' sign.\n\n New in version 2016.3.0",
"selectionRange": {
"end": {
"character": 14,
"line": 6
},
"start": {
"character": 2,
"line": 6
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 2,
"line": 6
}
},
"kind": 19,
"name": "cron.present"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 5
},
"start": {
"character": 0,
"line": 5
}
},
"range": {
"end": {
"character": 0,
"line": 10
},
"start": {
"character": 0,
"line": 5
}
},
"kind": 19,
"name": "git -C /srv/salt pull -q"
},
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 18,
"line": 11
},
"start": {
"character": 2,
"line": 11
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 2,
"line": 11
}
},
"kind": 19,
"name": "file. - target"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 20,
"line": 10
},
"start": {
"character": 0,
"line": 10
}
},
"range": {
"end": {
"character": 0,
"line": 13
},
"start": {
"character": 0,
"line": 10
}
},
"kind": 19,
"name": "/srv/git/salt-states"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 15
},
"start": {
"character": 4,
"line": 15
}
},
"range": {
"end": {
"character": 4,
"line": 16
},
"start": {
"character": 4,
"line": 15
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 16
},
"start": {
"character": 4,
"line": 16
}
},
"range": {
"end": {
"character": 4,
"line": 17
},
"start": {
"character": 4,
"line": 16
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 17
},
"start": {
"character": 4,
"line": 17
}
},
"range": {
"end": {
"character": 4,
"line": 18
},
"start": {
"character": 4,
"line": 17
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 18
},
"start": {
"character": 4,
"line": 18
}
},
"range": {
"end": {
"character": 4,
"line": 19
},
"start": {
"character": 4,
"line": 18
}
},
"kind": 19,
"name": "source"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 12,
"line": 19
},
"start": {
"character": 4,
"line": 19
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 4,
"line": 19
}
},
"kind": 19,
"name": "template"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 14
},
"start": {
"character": 2,
"line": 14
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 2,
"line": 14
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 46,
"line": 13
},
"start": {
"character": 0,
"line": 13
}
},
"range": {
"end": {
"character": 0,
"line": 21
},
"start": {
"character": 0,
"line": 13
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.service"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 23
},
"start": {
"character": 4,
"line": 23
}
},
"range": {
"end": {
"character": 4,
"line": 24
},
"start": {
"character": 4,
"line": 23
}
},
"kind": 19,
"name": "user"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 9,
"line": 24
},
"start": {
"character": 4,
"line": 24
}
},
"range": {
"end": {
"character": 4,
"line": 25
},
"start": {
"character": 4,
"line": 24
}
},
"kind": 19,
"name": "group"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 8,
"line": 25
},
"start": {
"character": 4,
"line": 25
}
},
"range": {
"end": {
"character": 4,
"line": 26
},
"start": {
"character": 4,
"line": 25
}
},
"kind": 19,
"name": "mode"
},
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 26
},
"start": {
"character": 4,
"line": 26
}
},
"range": {
"end": {
"character": 4,
"line": 27
},
"start": {
"character": 4,
"line": 26
}
},
"kind": 19,
"name": "source"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 28
},
"start": {
"character": 6,
"line": 28
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 6,
"line": 28
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 27
},
"start": {
"character": 4,
"line": 27
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 4,
"line": 27
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Manage a given file, this function allows for a file to be downloaded from\nthe salt master and potentially run through a templating system.\n\nname\n The location of the file to manage, as an absolute path.\n\nsource\n The source file to download to the minion, this source file can be\n hosted on either the salt master server (``salt://``), the salt minion\n local file system (``/``), or on an HTTP or FTP server (``http(s)://``,\n ``ftp://``).\n\n Both HTTPS and HTTP are supported as well as downloading directly\n from Amazon S3 compatible URLs with both pre-configured and automatic\n IAM credentials. (see s3.get state documentation)\n File retrieval from Openstack Swift object storage is supported via\n swift://container/object_path URLs, see swift.get documentation.\n For files hosted on the salt file server, if the file is located on\n the master in the directory named spam, and is called eggs, the source\n string is salt://spam/eggs. If source is left blank or None\n (use ~ in YAML), the file will be created as an empty file and\n the content will not be managed. This is also the case when a file\n already exists and the source is undefined; the contents of the file\n will not be changed or managed. If source is left blank or None, please\n also set replaced to False to make your intention explicit.\n\n\n If the file is hosted on a HTTP or FTP server then the source_hash\n argument is also required.\n\n A list of sources can also be passed in to provide a default source and\n a set of fallbacks. The first source in the list that is found to exist\n will be used and subsequent entries in the list will be ignored. Source\n list functionality only supports local files and remote files hosted on\n the salt master server or retrievable via HTTP, HTTPS, or FTP.\n\n file_override_example:\n file.managed:\n - source:\n - salt://file_that_does_not_exist\n - salt://file_that_exists\n\nsource_hash\n This can be one of the following:\n 1. a source hash string\n 2. the URI of a file that contains source hash strings\n\n The function accepts the first encountered long unbroken alphanumeric\n string of correct length as a valid hash, in order from most secure to\n least secure:\n\n Type Length\n ====== ======\n sha512 128\n sha384 96\n sha256 64\n sha224 56\n sha1 40\n md5 32\n\n **Using a Source Hash File**\n The file can contain several checksums for several files. Each line\n must contain both the file name and the hash. If no file name is\n matched, the first hash encountered will be used, otherwise the most\n secure hash with the correct source file name will be used.\n\n When using a source hash file the source_hash argument needs to be a\n url, the standard download urls are supported, ftp, http, salt etc:\n\n Example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.hash\n\n The following lines are all supported formats:\n\n /etc/rc.conf ef6e82e4006dee563d98ada2a2a80a27\n sha254c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a /etc/resolv.conf\n ead48423703509d37c4a90e6a0d53e143b6fc268\n\n Debian file type ``*.dsc`` files are also supported.\n\n **Inserting the Source Hash in the SLS Data**\n\n The source_hash can be specified as a simple checksum, like so:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: 79eef25f9b0b2c642c62b7f737d4f53f\n\n Note:\n Releases prior to 2016.11.0 must also include the hash type, like\n in the below example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: md5=79eef25f9b0b2c642c62b7f737d4f53f\n\n Known issues:\n If the remote server URL has the hash file as an apparent\n sub-directory of the source file, the module will discover that it\n has already cached a directory where a file should be cached. For\n example:\n\n tomdroid-src-0.7.3.tar.gz:\n file.managed:\n - name: /tmp/tomdroid-src-0.7.3.tar.gz\n - source: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz\n - source_hash: https://launchpad.net/tomdroid/beta/0.7.3/+download/tomdroid-src-0.7.3.tar.gz/+md5\n\nsource_hash_name\n When ``source_hash`` refers to a hash file, Salt will try to find the\n correct hash by matching the filename/URI associated with that hash. By\n default, Salt will look for the filename being managed. When managing a\n file at path ``/tmp/foo.txt``, then the following line in a hash file\n would match:\n\n acbd18db4cc2f85cedef654fccc4a4d8 foo.txt\n\n However, sometimes a hash file will include multiple similar paths:\n\n 37b51d194a7513e45b56f6524f2d51f2 ./dir1/foo.txt\n acbd18db4cc2f85cedef654fccc4a4d8 ./dir2/foo.txt\n 73feffa4b7f6bb68e44cf984c85f6e88 ./dir3/foo.txt\n\n In cases like this, Salt may match the incorrect hash. This argument\n can be used to tell Salt which filename to match, to ensure that the\n correct hash is identified. For example:\n\n /tmp/foo.txt:\n file.managed:\n - source: https://mydomain.tld/dir2/foo.txt\n - source_hash: https://mydomain.tld/hashes\n - source_hash_name: ./dir2/foo.txt\n\n Note:\n This argument must contain the full filename entry from the\n checksum file, as this argument is meant to disambiguate matches\n for multiple files that have the same basename. So, in the\n example above, simply using ``foo.txt`` would not match.\n\n New in version 2016.3.5\n\nkeep_source : True\n Set to ``False`` to discard the cached copy of the source file once the\n state completes. This can be useful for larger files to keep them from\n taking up space in minion cache. However, keep in mind that discarding\n the source file will result in the state needing to re-download the\n source file if the state is run again.\n\n New in version 2017.7.3\n\nuser\n The user to own the file, this defaults to the user salt is running as\n on the minion\n\ngroup\n The group ownership set for the file, this defaults to the group salt\n is running as on the minion. On Windows, this is ignored\n\nmode\n The permissions to set on this file, e.g. ``644``, ``0775``, or\n ``4664``.\n\n The default mode for new files and directories corresponds to the\n umask of the salt process. The mode of existing files and directories\n will only be changed if ``mode`` is specified.\n\n Note:\n This option is **not** supported on Windows.\n\n Changed in version 2016.11.0\n This option can be set to ``keep``, and Salt will keep the mode\n from the Salt fileserver. This is only supported when the\n ``source`` URL begins with ``salt://``, or for files local to the\n minion. Because the ``source`` option cannot be used with any of\n the ``contents`` options, setting the ``mode`` to ``keep`` is also\n incompatible with the ``contents`` options.\n\n Note: keep does not work with salt-ssh.\n\n As a consequence of how the files are transferred to the minion, and\n the inability to connect back to the master with salt-ssh, salt is\n unable to stat the file as it exists on the fileserver and thus\n cannot mirror the mode on the salt-ssh minion\n\nattrs\n The attributes to have on this file, e.g. ``a``, ``i``. The attributes\n can be any or a combination of the following characters:\n ``aAcCdDeijPsStTu``.\n\n Note:\n This option is **not** supported on Windows.\n\n New in version 2018.3.0\n\ntemplate\n If this setting is applied, the named templating engine will be used to\n render the downloaded file. The following templates are supported:\n\n - :mod:`cheetah<salt.renderers.cheetah>`\n - :mod:`genshi<salt.renderers.genshi>`\n - :mod:`jinja<salt.renderers.jinja>`\n - :mod:`mako<salt.renderers.mako>`\n - :mod:`py<salt.renderers.py>`\n - :mod:`wempy<salt.renderers.wempy>`\n\nmakedirs : False\n If set to ``True``, then the parent directories will be created to\n facilitate the creation of the named file. If ``False``, and the parent\n directory of the destination file doesn't exist, the state will fail.\n\ndir_mode\n If directories are to be created, passing this option specifies the\n permissions for those directories. If this is not set, directories\n will be assigned permissions by adding the execute bit to the mode of\n the files.\n\n The default mode for new files and directories corresponds umask of salt\n process. For existing files and directories it's not enforced.\n\nreplace : True\n If set to ``False`` and the file already exists, the file will not be\n modified even if changes would otherwise be made. Permissions and\n ownership will still be enforced, however.\n\ncontext\n Overrides default context variables passed to the template.\n\ndefaults\n Default context passed to the template.\n\nbackup\n Overrides the default backup mode for this specific file. See\n :ref:`backup_mode documentation <file-state-backups>` for more details.\n\nshow_changes\n Output a unified diff of the old file and the new file. If ``False``\n return a boolean if any changes were made.\n\ncreate : True\n If set to ``False``, then the file will only be managed if the file\n already exists on the system.\n\ncontents\n Specify the contents of the file. Cannot be used in combination with\n ``source``. Ignores hashes and does not use a templating engine.\n\n This value can be either a single string, a multiline YAML string or a\n list of strings. If a list of strings, then the strings will be joined\n together with newlines in the resulting file. For example, the below\n two example states would result in identical file contents:\n\n /path/to/file1:\n file.managed:\n - contents:\n - This is line 1\n - This is line 2\n\n /path/to/file2:\n file.managed:\n - contents: |\n This is line 1\n This is line 2\n\n\ncontents_pillar\n New in version 0.17.0\n Changed in version 2016.11.0\n contents_pillar can also be a list, and the pillars will be\n concatenated together to form one file.\n\n\n Operates like ``contents``, but draws from a value stored in pillar,\n using the pillar path syntax used in :mod:`pillar.get\n <salt.modules.pillar.get>`. This is useful when the pillar value\n contains newlines, as referencing a pillar variable using a jinja/mako\n template can result in YAML formatting issues due to the newlines\n causing indentation mismatches.\n\n For example, the following could be used to deploy an SSH private key:\n\n /home/deployer/.ssh/id_rsa:\n file.managed:\n - user: deployer\n - group: deployer\n - mode: 600\n - attrs: a\n - contents_pillar: userdata:deployer:id_rsa\n\n This would populate ``/home/deployer/.ssh/id_rsa`` with the contents of\n ``pillar['userdata']['deployer']['id_rsa']``. An example of this pillar\n setup would be like so:\n\n userdata:\n deployer:\n id_rsa: |\n -----BEGIN RSA PRIVATE KEY-----\n MIIEowIBAAKCAQEAoQiwO3JhBquPAalQF9qP1lLZNXVjYMIswrMe2HcWUVBgh+vY\n U7sCwx/dH6+VvNwmCoqmNnP+8gTPKGl1vgAObJAnMT623dMXjVKwnEagZPRJIxDy\n B/HaAre9euNiY3LvIzBTWRSeMfT+rWvIKVBpvwlgGrfgz70m0pqxu+UyFbAGLin+\n GpxzZAMaFpZw4sSbIlRuissXZj/sHpQb8p9M5IeO4Z3rjkCP1cxI\n -----END RSA PRIVATE KEY-----\n\n Note:\n The private key above is shortened to keep the example brief, but\n shows how to do multiline string in YAML. The key is followed by a\n pipe character, and the multiline string is indented two more\n spaces.\n\n To avoid the hassle of creating an indented multiline YAML string,\n the :mod:`file_tree external pillar <salt.pillar.file_tree>` can\n be used instead. However, this will not work for binary files in\n Salt releases before 2015.8.4.\n\ncontents_grains\n New in version 2014.7.0\n\n Operates like ``contents``, but draws from a value stored in grains,\n using the grains path syntax used in :mod:`grains.get\n <salt.modules.grains.get>`. This functionality works similarly to\n ``contents_pillar``, but with grains.\n\n For example, the following could be used to deploy a \"message of the day\"\n file:\n\n write_motd:\n file.managed:\n - name: /etc/motd\n - contents_grains: motd\n\n This would populate ``/etc/motd`` file with the contents of the ``motd``\n grain. The ``motd`` grain is not a default grain, and would need to be\n set prior to running the state:\n\n salt '*' grains.set motd 'Welcome! This system is managed by Salt.'\n\ncontents_newline : True\n New in version 2014.7.0\n Changed in version 2015.8.4\n This option is now ignored if the contents being deployed contain\n binary data.\n\n If ``True``, files managed using ``contents``, ``contents_pillar``, or\n ``contents_grains`` will have a newline added to the end of the file if\n one is not present. Setting this option to ``False`` will ensure the\n final line, or entry, does not contain a new line. If the last line, or\n entry in the file does contain a new line already, this option will not\n remove it.\n\ncontents_delimiter\n New in version 2015.8.4\n\n Can be used to specify an alternate delimiter for ``contents_pillar``\n or ``contents_grains``. This delimiter will be passed through to\n :py:func:`pillar.get <salt.modules.pillar.get>` or :py:func:`grains.get\n <salt.modules.grains.get>` when retrieving the contents.\n\nencoding\n If specified, then the specified encoding will be used. Otherwise, the\n file will be encoded using the system locale (usually UTF-8). See\n https://docs.python.org/3/library/codecs.html#standard-encodings for\n the list of available encodings.\n\n New in version 2017.7.0\n\nencoding_errors : 'strict'\n Error encoding scheme. Default is ```'strict'```.\n See https://docs.python.org/2/library/codecs.html#codec-base-classes\n for the list of available schemes.\n\n New in version 2017.7.0\n\nallow_empty : True\n New in version 2015.8.4\n\n If set to ``False``, then the state will fail if the contents specified\n by ``contents_pillar`` or ``contents_grains`` are empty.\n\nfollow_symlinks : True\n New in version 2014.7.0\n\n If the desired path is a symlink follow it and make changes to the\n file to which the symlink points.\n\ncheck_cmd\n New in version 2014.7.0\n\n The specified command will be run with an appended argument of a\n *temporary* file containing the new managed contents. If the command\n exits with a zero status the new managed contents will be written to\n the managed destination. If the command exits with a nonzero exit\n code, the state will fail and no changes will be made to the file.\n\n For example, the following could be used to verify sudoers before making\n changes:\n\n /etc/sudoers:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - attrs: i\n - source: salt://sudoers/files/sudoers.jinja\n - template: jinja\n - check_cmd: /usr/sbin/visudo -c -f\n\n **NOTE**: This ``check_cmd`` functions differently than the requisite\n ``check_cmd``.\n\ntmp_dir\n Directory for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file location (e.g. daemons restricted to their\n own config directories by an apparmor profile).\n\n /etc/dhcp/dhcpd.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0755\n - tmp_dir: '/etc/dhcp'\n - contents: \"# Managed by Salt\"\n - check_cmd: dhcpd -t -cf\n\ntmp_ext\n Suffix for temp file created by ``check_cmd``. Useful for checkers\n dependent on config file extension (e.g. the init-checkconf upstart\n config checker).\n\n /etc/init/test.conf:\n file.managed:\n - user: root\n - group: root\n - mode: 0440\n - tmp_ext: '.conf'\n - contents:\n - 'description \"Salt Minion\"'\n - 'start on started mountall'\n - 'stop on shutdown'\n - 'respawn'\n - 'exec salt-minion'\n - check_cmd: init-checkconf -f\n\nskip_verify : False\n If ``True``, hash verification of remote file sources (``http://``,\n ``https://``, ``ftp://``) will be skipped, and the ``source_hash``\n argument will be ignored.\n\n New in version 2016.3.0\n\nselinux : None\n Allows setting the selinux user, role, type, and range of a managed file\n\n /tmp/selinux.test\n file.managed:\n - user: root\n - selinux:\n seuser: system_u\n serole: object_r\n setype: system_conf_t\n seranage: s0\n\n New in version 3000\n\nwin_owner : None\n The owner of the directory. If this is not passed, user will be used. If\n user is not passed, the account under which Salt is running will be\n used.\n\n New in version 2017.7.0\n\nwin_perms : None\n A dictionary containing permissions to grant and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_deny_perms : None\n A dictionary containing permissions to deny and their propagation. For\n example: ``{'Administrators': {'perms': 'full_control'}}`` Can be a\n single basic perm or a list of advanced perms. ``perms`` must be\n specified. ``applies_to`` does not apply to file objects.\n\n New in version 2017.7.0\n\nwin_inheritance : True\n True to inherit permissions from the parent directory, False not to\n inherit permission.\n\n New in version 2017.7.0\n\nwin_perms_reset : False\n If ``True`` the existing DACL will be cleared and replaced with the\n settings defined in this function. If ``False``, new entries will be\n appended to the existing DACL. Default is ``False``.\n\n New in version 2018.3.0\n\nHere's an example using the above ``win_*`` parameters:\n\n create_config_file:\n file.managed:\n - name: C:\\config\\settings.cfg\n - source: salt://settings.cfg\n - win_owner: Administrators\n - win_perms:\n # Basic Permissions\n dev_ops:\n perms: full_control\n # List of advanced permissions\n appuser:\n perms:\n - read_attributes\n - read_ea\n - create_folders\n - read_permissions\n joe_snuffy:\n perms: read\n - win_deny_perms:\n fred_snuffy:\n perms: full_control\n - win_inheritance: False\n\nverify_ssl\n If ``False``, remote https file sources (``https://``) and source_hash\n will not attempt to validate the servers certificate. Default is True.\n\n New in version 3002",
"selectionRange": {
"end": {
"character": 14,
"line": 22
},
"start": {
"character": 2,
"line": 22
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 2,
"line": 22
}
},
"kind": 19,
"name": "file.managed"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 44,
"line": 21
},
"start": {
"character": 0,
"line": 21
}
},
"range": {
"end": {
"character": 0,
"line": 30
},
"start": {
"character": 0,
"line": 21
}
},
"kind": 19,
"name": "/etc/systemd/system/rootco-salt-backup.timer"
},
{
"children": [
{
"children": [
{
"children": [],
"detail": "",
"selectionRange": {
"end": {
"character": 10,
"line": 32
},
"start": {
"character": 4,
"line": 32
}
},
"range": {
"end": {
"character": 4,
"line": 33
},
"start": {
"character": 4,
"line": 32
}
},
"kind": 19,
"name": "enable"
},
{
"children": [
{
"children": [],
"detail": "Operations on regular files, special files, directories, and symlinks\n=====================================================================\n\nSalt States can aggressively manipulate files on a system. There are a number\nof ways in which files can be managed.\n\nRegular files can be enforced with the :mod:`file.managed\n<salt.states.file.managed>` state. This state downloads files from the salt\nmaster and places them on the target system. Managed files can be rendered as a\njinja, mako, or wempy template, adding a dynamic component to file management.\nAn example of :mod:`file.managed <salt.states.file.managed>` which makes use of\nthe jinja templating system would look like this:\n\n /etc/http/conf/http.conf:\n file.managed:\n - source: salt://apache/http.conf\n - user: root\n - group: root\n - mode: 644\n - attrs: ai\n - template: jinja\n - defaults:\n custom_var: \"default value\"\n other_var: 123\n {% if grains['os'] == 'Ubuntu' %}\n - context:\n custom_var: \"override\"\n {% endif %}\n\nIt is also possible to use the :mod:`py renderer <salt.renderers.py>` as a\ntemplating option. The template would be a Python script which would need to\ncontain a function called ``run()``, which returns a string. All arguments\nto the state will be made available to the Python script as globals. The\nreturned string will be the contents of the managed file. For example:\n\n def run():\n lines = ['foo', 'bar', 'baz']\n lines.extend([source, name, user, context]) # Arguments as globals\n return '\\n\\n'.join(lines)\n\nNote:\n\n The ``defaults`` and ``context`` arguments require extra indentation (four\n spaces instead of the normal two) in order to create a nested dictionary.\n :ref:`More information <nested-dict-indentation>`.\n\nIf using a template, any user-defined template variables in the file defined in\n``source`` must be passed in using the ``defaults`` and/or ``context``\narguments. The general best practice is to place default values in\n``defaults``, with conditional overrides going into ``context``, as seen above.\n\nThe template will receive a variable ``custom_var``, which would be accessed in\nthe template using ``{{ custom_var }}``. If the operating system is Ubuntu, the\nvalue of the variable ``custom_var`` would be *override*, otherwise it is the\ndefault *default value*\n\nThe ``source`` parameter can be specified as a list. If this is done, then the\nfirst file to be matched will be the one that is used. This allows you to have\na default file on which to fall back if the desired file does not exist on the\nsalt fileserver. Here's an example:\n\n /etc/foo.conf:\n file.managed:\n - source:\n - salt://foo.conf.{{ grains['fqdn'] }}\n - salt://foo.conf.fallback\n - user: foo\n - group: users\n - mode: 644\n - attrs: i\n - backup: minion\n\nNote:\n\n Salt supports backing up managed files via the backup option. For more\n details on this functionality please review the\n :ref:`backup_mode documentation <file-state-backups>`.\n\nThe ``source`` parameter can also specify a file in another Salt environment.\nIn this example ``foo.conf`` in the ``dev`` environment will be used instead.\n\n /etc/foo.conf:\n file.managed:\n - source:\n - 'salt://foo.conf?saltenv=dev'\n - user: foo\n - group: users\n - mode: '0644'\n - attrs: i\n\nWarning:\n\n When using a mode that includes a leading zero you must wrap the\n value in single quotes. If the value is not wrapped in quotes it\n will be read by YAML as an integer and evaluated as an octal.\n\nThe ``names`` parameter, which is part of the state compiler, can be used to\nexpand the contents of a single state declaration into multiple, single state\ndeclarations. Each item in the ``names`` list receives its own individual state\n``name`` and is converted into its own low-data structure. This is a convenient\nway to manage several files with similar attributes.\n\n salt_master_conf:\n file.managed:\n - user: root\n - group: root\n - mode: '0644'\n - names:\n - /etc/salt/master.d/master.conf:\n - source: salt://saltmaster/master.conf\n - /etc/salt/minion.d/minion-99.conf:\n - source: salt://saltmaster/minion.conf\n\nNote:\n\n There is more documentation about this feature in the :ref:`Names declaration\n <names-declaration>` section of the :ref:`Highstate docs <states-highstate>`.\n\nSpecial files can be managed via the ``mknod`` function. This function will\ncreate and enforce the permissions on a special file. The function supports the\ncreation of character devices, block devices, and FIFO pipes. The function will\ncreate the directory structure up to the special file if it is needed on the\nminion. The function will not overwrite or operate on (change major/minor\nnumbers) existing special files with the exception of user, group, and\npermissions. In most cases the creation of some special files require root\npermissions on the minion. This would require that the minion to be run as the\nroot user. Here is an example of a character device:\n\n /var/named/chroot/dev/random:\n file.mknod:\n - ntype: c\n - major: 1\n - minor: 8\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a block device:\n\n /var/named/chroot/dev/loop0:\n file.mknod:\n - ntype: b\n - major: 7\n - minor: 0\n - user: named\n - group: named\n - mode: 660\n\nHere is an example of a fifo pipe:\n\n /var/named/chroot/var/log/logfifo:\n file.mknod:\n - ntype: p\n - user: named\n - group: named\n - mode: 660\n\nDirectories can be managed via the ``directory`` function. This function can\ncreate and enforce the permissions on a directory. A directory statement will\nlook like this:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n\nIf you need to enforce user and/or group ownership or permissions recursively\non the directory's contents, you can do so by adding a ``recurse`` directive:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nAs a default, ``mode`` will resolve to ``dir_mode`` and ``file_mode``, to\nspecify both directory and file permissions, use this form:\n\n /srv/stuff/substuf:\n file.directory:\n - user: fred\n - group: users\n - file_mode: 744\n - dir_mode: 755\n - makedirs: True\n - recurse:\n - user\n - group\n - mode\n\nSymlinks can be easily created; the symlink function is very simple and only\ntakes a few arguments:\n\n /etc/grub.conf:\n file.symlink:\n - target: /boot/grub/grub.conf\n\nRecursive directory management can also be set via the ``recurse``\nfunction. Recursive directory management allows for a directory on the salt\nmaster to be recursively copied down to the minion. This is a great tool for\ndeploying large code and configuration systems. A state using ``recurse``\nwould look something like this:\n\n /opt/code/flask:\n file.recurse:\n - source: salt://code/flask\n - include_empty: True\n\nA more complex ``recurse`` example:\n\n {% set site_user = 'testuser' %}\n {% set site_name = 'test_site' %}\n {% set project_name = 'test_proj' %}\n {% set sites_dir = 'test_dir' %}\n\n django-project:\n file.recurse:\n - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }}\n - user: {{ site_user }}\n - dir_mode: 2775\n - file_mode: '0644'\n - template: jinja\n - source: salt://project/templates_dir\n - include_empty: True\n\nRetention scheduling can be applied to manage contents of backup directories.\nFor example:\n\n /var/backups/example_directory:\n file.retention_schedule:\n - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2\n - retain:\n most_recent: 5\n first_of_hour: 4\n first_of_day: 14\n first_of_week: 6\n first_of_month: 6\n first_of_year: all",
"selectionRange": {
"end": {
"character": 10,
"line": 34
},
"start": {
"character": 6,
"line": 34
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 6,
"line": 34
}
},
"kind": 19,
"name": "file"
}
],
"detail": "List of requisites.\nSee also: https://docs.saltproject.io/en/latest/ref/states/requisites.html\n",
"selectionRange": {
"end": {
"character": 11,
"line": 33
},
"start": {
"character": 4,
"line": 33
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 4,
"line": 33
}
},
"kind": 19,
"name": "require"
}
],
"detail": "Ensure that the service is running\n\nname\n The name of the init or rc script used to manage the service\n\nenable\n Set the service to be enabled at boot time, ``True`` sets the service\n to be enabled, ``False`` sets the named service to be disabled. The\n default is ``None``, which does not enable or disable anything.\n\nsig\n The string to search for when looking for the service process with ps\n\ninit_delay\n Some services may not be truly available for a short period after their\n startup script indicates to the system that they are. Provide an\n 'init_delay' to specify that this state should wait an additional given\n number of seconds after a service has started before returning. Useful\n for requisite states wherein a dependent state might assume a service\n has started but is not yet fully initialized.\n\nno_block : False\n **For systemd minions only.** Starts the service using ``--no-block``.\n\n New in version 2017.7.0\n\ntimeout\n **For Windows minions only.**\n\n The time in seconds to wait for the service to start before returning.\n Default is the default for :py:func:`win_service.start\n <salt.modules.win_service.start>`.\n\n New in version 2017.7.9,2018.3.4\n\nunmask : False\n **For systemd minions only.** Set to ``True`` to remove an indefinite\n mask before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nunmask_runtime : False\n **For systemd minions only.** Set to ``True`` to remove a runtime mask\n before attempting to start the service.\n\n New in version 2017.7.0\n In previous releases, Salt would simply unmask a service before\n making any changes. This behavior is no longer the default.\n\nwait : 3\n **For systemd minions only.** Passed through when using\n :py:func:`service.status <salt.modules.systemd_service.status>` to\n determine whether the service is running or not.\n\n New in version 2019.2.3\n\nNote:\n ``watch`` can be used with service.running to restart a service when\n another state changes ( example: a file.managed state that creates the\n service's config file ). More details regarding ``watch`` can be found\n in the :ref:`Requisites <requisites>` documentation.",
"selectionRange": {
"end": {
"character": 17,
"line": 31
},
"start": {
"character": 2,
"line": 31
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 2,
"line": 31
}
},
"kind": 19,
"name": "service.running"
}
],
"detail": "",
"selectionRange": {
"end": {
"character": 24,
"line": 30
},
"start": {
"character": 0,
"line": 30
}
},
"range": {
"end": {
"character": 0,
"line": 35
},
"start": {
"character": 0,
"line": 30
}
},
"kind": 19,
"name": "rootco-salt-backup.timer"
}
]