From 31c9d0df191009207c72ea73abfd3a1e3a0e6425 Mon Sep 17 00:00:00 2001 From: Salt Project Packaging Date: Sun, 3 Mar 2024 07:00:21 +0000 Subject: [PATCH] Release v3007.0 --- CHANGELOG.md | 180 + changelog/18907.fixed.md | 1 - changelog/40943.added.md | 1 - changelog/42039.fixed.md | 1 - changelog/45450.added.md | 1 - changelog/48067.fixed.md | 1 - changelog/50196.fixed.md | 1 - changelog/51605.fixed.md | 1 - changelog/51858.fixed.md | 1 - changelog/51986.fixed.md | 1 - changelog/52452.fixed.md | 1 - changelog/53120.changed.md | 1 - changelog/53666.added.md | 1 - changelog/53982.added.md | 1 - changelog/54426.fixed.md | 1 - changelog/55687.fixed.md | 1 - changelog/56441.fixed.md | 1 - changelog/57204.fixed.md | 1 - changelog/57541.added.md | 1 - changelog/57561.fixed.md | 1 - changelog/57946.fixed.md | 1 - changelog/58044.added.md | 1 - changelog/58174.fixed.md | 1 - changelog/58580.fixed.md | 1 - changelog/58936.fixed.md | 1 - changelog/59037.added.md | 1 - changelog/59514.fixed.md | 1 - changelog/59783.added.md | 1 - changelog/59806.fixed.md | 1 - changelog/60500.fixed.md | 1 - changelog/60779.fixed.md | 1 - changelog/61100.fixed.md | 1 - changelog/61143.fixed.md | 1 - changelog/61416.fixed.md | 1 - changelog/61620.fixed.md | 1 - changelog/62380.fixed.md | 1 - changelog/62520.removed.md | 1 - changelog/62589.added.md | 1 - changelog/62823.added.md | 1 - changelog/62825.added.md | 1 - changelog/62828.added.md | 1 - changelog/62961.added.md | 1 - changelog/63052.fixed.md | 1 - changelog/63143.added.md | 1 - changelog/63144.fixed.md | 1 - changelog/63153.fixed.md | 1 - changelog/63156.fixed.md | 1 - changelog/63159.fixed.md | 1 - changelog/63166.added.md | 1 - changelog/63214.fixed.md | 1 - changelog/63278.added.md | 1 - changelog/63278.fixed.md | 1 - changelog/63406.added.md | 1 - changelog/63416.added.md | 1 - changelog/63440.added.md | 1 - changelog/63442.added.md | 1 - changelog/63463.added.md | 1 - changelog/63545.added.md | 1 - changelog/63583.fixed.md | 1 - changelog/63708.fixed.md | 1 - changelog/63714.fixed.md | 1 - changelog/63767.fixed.md | 1 - changelog/63779.fixed.md | 1 - changelog/63905.added.md | 1 - changelog/63982.fixed.md | 1 - changelog/63985.added.md | 1 - changelog/63991.fixed.md | 1 - changelog/63996.fixed.md | 1 - changelog/64096.added.md | 1 - changelog/64224.deprecated.md | 1 - changelog/64256.added.md | 1 - changelog/64260.fixed.md | 1 - changelog/64300.fixed.md | 1 - changelog/64305.fixed.md | 1 - changelog/64322.removed.md | 1 - changelog/64369.fixed.md | 1 - changelog/64379.added.md | 1 - changelog/64417.removed.md | 1 - changelog/64418.added.md | 1 - changelog/64420.fixed.md | 1 - changelog/64450.fixed.md | 1 - changelog/64457.added.md | 1 - changelog/64457.changed.md | 6 - changelog/64459.removed.md | 1 - changelog/64460.removed.md | 1 - changelog/64461.removed.md | 1 - changelog/64462.changed.md | 1 - changelog/64488.fixed.md | 1 - changelog/64517.removed.md | 1 - changelog/64531.fixed.md | 1 - changelog/64532.added.md | 1 - changelog/64567.fixed.md | 1 - changelog/64569.added.md | 1 - changelog/64599.fixed.md | 2 - changelog/64600.added.md | 1 - changelog/64610.fixed.md | 1 - changelog/64660.added.md | 1 - changelog/64665.added.md | 1 - changelog/64893.deprecated.md | 1 - changelog/64894.deprecated.md | 1 - changelog/64896.deprecated.md | 1 - changelog/64909.deprecated.md | 1 - changelog/64924.fixed.md | 7 - changelog/64934.fixed.md | 1 - changelog/64939.added.md | 1 - changelog/64978.added.md | 1 - changelog/64989.security.md | 1 - changelog/65008.added.md | 3 - changelog/65067.fixed.md | 1 - changelog/65080.fixed.md | 1 - changelog/65137.security.md | 1 - changelog/65169.fixed.md | 1 - changelog/65220.added.md | 1 - changelog/65295.fixed.md | 1 - changelog/65435.fixed.md | 1 - changelog/65479.added.md | 1 - changelog/65480.fixed.md | 1 - changelog/65513.fixed.md | 1 - changelog/65542.deprecated.md | 1 - changelog/65562.fixed.md | 1 - changelog/65565.deprecated.md | 1 - changelog/65567.deprecated.md | 1 - changelog/65630.fixed.md | 1 - changelog/65645.added.md | 1 - changelog/65652.fixed.md | 1 - changelog/65686.fixed.md | 1 - changelog/65697.added.md | 1 - changelog/65713.added.md | 1 - changelog/65739.fixed.md | 1 - changelog/65744.added.md | 1 - changelog/65986.deprecated.md | 8 - changelog/66124.fixed.md | 1 - changelog/66126.fixed.md | 2 - doc/man/salt-api.1 | 2 +- doc/man/salt-call.1 | 2 +- doc/man/salt-cloud.1 | 2 +- doc/man/salt-cp.1 | 2 +- doc/man/salt-key.1 | 2 +- doc/man/salt-master.1 | 2 +- doc/man/salt-minion.1 | 2 +- doc/man/salt-proxy.1 | 2 +- doc/man/salt-run.1 | 2 +- doc/man/salt-ssh.1 | 2 +- doc/man/salt-syndic.1 | 2 +- doc/man/salt.1 | 2 +- doc/man/salt.7 | 31375 +++++++++++++------------------- doc/man/spm.1 | 2 +- doc/topics/releases/3007.0.md | 18 +- pkg/debian/changelog | 177 + pkg/rpm/salt.spec | 176 +- 150 files changed, 12961 insertions(+), 19145 deletions(-) delete mode 100644 changelog/18907.fixed.md delete mode 100644 changelog/40943.added.md delete mode 100644 changelog/42039.fixed.md delete mode 100644 changelog/45450.added.md delete mode 100644 changelog/48067.fixed.md delete mode 100644 changelog/50196.fixed.md delete mode 100644 changelog/51605.fixed.md delete mode 100644 changelog/51858.fixed.md delete mode 100644 changelog/51986.fixed.md delete mode 100644 changelog/52452.fixed.md delete mode 100644 changelog/53120.changed.md delete mode 100644 changelog/53666.added.md delete mode 100644 changelog/53982.added.md delete mode 100644 changelog/54426.fixed.md delete mode 100644 changelog/55687.fixed.md delete mode 100644 changelog/56441.fixed.md delete mode 100644 changelog/57204.fixed.md delete mode 100644 changelog/57541.added.md delete mode 100644 changelog/57561.fixed.md delete mode 100644 changelog/57946.fixed.md delete mode 100644 changelog/58044.added.md delete mode 100644 changelog/58174.fixed.md delete mode 100644 changelog/58580.fixed.md delete mode 100644 changelog/58936.fixed.md delete mode 100644 changelog/59037.added.md delete mode 100644 changelog/59514.fixed.md delete mode 100644 changelog/59783.added.md delete mode 100644 changelog/59806.fixed.md delete mode 100644 changelog/60500.fixed.md delete mode 100644 changelog/60779.fixed.md delete mode 100644 changelog/61100.fixed.md delete mode 100644 changelog/61143.fixed.md delete mode 100644 changelog/61416.fixed.md delete mode 100644 changelog/61620.fixed.md delete mode 100644 changelog/62380.fixed.md delete mode 100644 changelog/62520.removed.md delete mode 100644 changelog/62589.added.md delete mode 100644 changelog/62823.added.md delete mode 100644 changelog/62825.added.md delete mode 100644 changelog/62828.added.md delete mode 100644 changelog/62961.added.md delete mode 100644 changelog/63052.fixed.md delete mode 100644 changelog/63143.added.md delete mode 100644 changelog/63144.fixed.md delete mode 100644 changelog/63153.fixed.md delete mode 100644 changelog/63156.fixed.md delete mode 100644 changelog/63159.fixed.md delete mode 100644 changelog/63166.added.md delete mode 100644 changelog/63214.fixed.md delete mode 100644 changelog/63278.added.md delete mode 100644 changelog/63278.fixed.md delete mode 100644 changelog/63406.added.md delete mode 100644 changelog/63416.added.md delete mode 100644 changelog/63440.added.md delete mode 100644 changelog/63442.added.md delete mode 100644 changelog/63463.added.md delete mode 100644 changelog/63545.added.md delete mode 100644 changelog/63583.fixed.md delete mode 100644 changelog/63708.fixed.md delete mode 100644 changelog/63714.fixed.md delete mode 100644 changelog/63767.fixed.md delete mode 100644 changelog/63779.fixed.md delete mode 100644 changelog/63905.added.md delete mode 100644 changelog/63982.fixed.md delete mode 100644 changelog/63985.added.md delete mode 100644 changelog/63991.fixed.md delete mode 100644 changelog/63996.fixed.md delete mode 100644 changelog/64096.added.md delete mode 100644 changelog/64224.deprecated.md delete mode 100644 changelog/64256.added.md delete mode 100644 changelog/64260.fixed.md delete mode 100644 changelog/64300.fixed.md delete mode 100644 changelog/64305.fixed.md delete mode 100644 changelog/64322.removed.md delete mode 100644 changelog/64369.fixed.md delete mode 100644 changelog/64379.added.md delete mode 100644 changelog/64417.removed.md delete mode 100644 changelog/64418.added.md delete mode 100644 changelog/64420.fixed.md delete mode 100644 changelog/64450.fixed.md delete mode 100644 changelog/64457.added.md delete mode 100644 changelog/64457.changed.md delete mode 100644 changelog/64459.removed.md delete mode 100644 changelog/64460.removed.md delete mode 100644 changelog/64461.removed.md delete mode 100644 changelog/64462.changed.md delete mode 100644 changelog/64488.fixed.md delete mode 100644 changelog/64517.removed.md delete mode 100644 changelog/64531.fixed.md delete mode 100644 changelog/64532.added.md delete mode 100644 changelog/64567.fixed.md delete mode 100644 changelog/64569.added.md delete mode 100644 changelog/64599.fixed.md delete mode 100644 changelog/64600.added.md delete mode 100644 changelog/64610.fixed.md delete mode 100644 changelog/64660.added.md delete mode 100644 changelog/64665.added.md delete mode 100644 changelog/64893.deprecated.md delete mode 100644 changelog/64894.deprecated.md delete mode 100644 changelog/64896.deprecated.md delete mode 100644 changelog/64909.deprecated.md delete mode 100644 changelog/64924.fixed.md delete mode 100644 changelog/64934.fixed.md delete mode 100644 changelog/64939.added.md delete mode 100644 changelog/64978.added.md delete mode 100644 changelog/64989.security.md delete mode 100644 changelog/65008.added.md delete mode 100644 changelog/65067.fixed.md delete mode 100644 changelog/65080.fixed.md delete mode 100644 changelog/65137.security.md delete mode 100644 changelog/65169.fixed.md delete mode 100644 changelog/65220.added.md delete mode 100644 changelog/65295.fixed.md delete mode 100644 changelog/65435.fixed.md delete mode 100644 changelog/65479.added.md delete mode 100644 changelog/65480.fixed.md delete mode 100644 changelog/65513.fixed.md delete mode 100644 changelog/65542.deprecated.md delete mode 100644 changelog/65562.fixed.md delete mode 100644 changelog/65565.deprecated.md delete mode 100644 changelog/65567.deprecated.md delete mode 100644 changelog/65630.fixed.md delete mode 100644 changelog/65645.added.md delete mode 100644 changelog/65652.fixed.md delete mode 100644 changelog/65686.fixed.md delete mode 100644 changelog/65697.added.md delete mode 100644 changelog/65713.added.md delete mode 100644 changelog/65739.fixed.md delete mode 100644 changelog/65744.added.md delete mode 100644 changelog/65986.deprecated.md delete mode 100644 changelog/66124.fixed.md delete mode 100644 changelog/66126.fixed.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f69ebad42f0..3ea1a0e5d5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,186 @@ Versions are `MAJOR.PATCH`. # Changelog +## 3007.0 (2024-03-03) + + +### Removed + +- Removed RHEL 5 support since long since end-of-lifed [#62520](https://github.com/saltstack/salt/issues/62520) +- Removing Azure-Cloud modules from the code base. [#64322](https://github.com/saltstack/salt/issues/64322) +- Dropped Python 3.7 support since it's EOL in 27 Jun 2023 [#64417](https://github.com/saltstack/salt/issues/64417) +- Remove salt.payload.Serial [#64459](https://github.com/saltstack/salt/issues/64459) +- Remove netmiko_conn and pyeapi_conn from salt.modules.napalm_mod [#64460](https://github.com/saltstack/salt/issues/64460) +- Removed 'transport' arg from salt.utils.event.get_event [#64461](https://github.com/saltstack/salt/issues/64461) +- Removed the usage of retired Linode API v3 from Salt Cloud [#64517](https://github.com/saltstack/salt/issues/64517) + + +### Deprecated + +- Deprecate all Proxmox cloud modules [#64224](https://github.com/saltstack/salt/issues/64224) +- Deprecate all the Vault modules in favor of the Vault Salt Extension https://github.com/salt-extensions/saltext-vault. The Vault modules will be removed in Salt core in 3009.0. [#64893](https://github.com/saltstack/salt/issues/64893) +- Deprecate all the Docker modules in favor of the Docker Salt Extension https://github.com/saltstack/saltext-docker. The Docker modules will be removed in Salt core in 3009.0. [#64894](https://github.com/saltstack/salt/issues/64894) +- Deprecate all the Zabbix modules in favor of the Zabbix Salt Extension https://github.com/salt-extensions/saltext-zabbix. The Zabbix modules will be removed in Salt core in 3009.0. [#64896](https://github.com/saltstack/salt/issues/64896) +- Deprecate all the Apache modules in favor of the Apache Salt Extension https://github.com/salt-extensions/saltext-apache. The Apache modules will be removed in Salt core in 3009.0. [#64909](https://github.com/saltstack/salt/issues/64909) +- Deprecation warning for Salt's backport of ``OrderedDict`` class which will be removed in 3009 [#65542](https://github.com/saltstack/salt/issues/65542) +- Deprecate Kubernetes modules for move to saltext-kubernetes in version 3009 [#65565](https://github.com/saltstack/salt/issues/65565) +- Deprecated all Pushover modules in favor of the Salt Extension at https://github.com/salt-extensions/saltext-pushover. The Pushover modules will be removed from Salt core in 3009.0 [#65567](https://github.com/saltstack/salt/issues/65567) +- Removed deprecated code: + + * All of ``salt/log/`` which has been on a deprecation path for a long time. + * Some of the logging handlers found in ``salt/_logging/handlers`` have been removed since the standard library provides + them. + * Removed the deprecated ``salt/modules/cassandra_mod.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/cassandra_return.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/django_return.py`` module and any tests for it. [#65986](https://github.com/saltstack/salt/issues/65986) + + +### Changed + +- Masquerade property will not default to false turning off masquerade if not specified. [#53120](https://github.com/saltstack/salt/issues/53120) +- Addressed Python 3.11 deprecations: + + * Switch to `FullArgSpec` since Py 3.11 no longer has `ArgSpec`, deprecated since Py 3.0 + * Stopped using the deprecated `cgi` module. + * Stopped using the deprecated `pipes` module + * Stopped using the deprecated `imp` module [#64457](https://github.com/saltstack/salt/issues/64457) +- changed 'gpg_decrypt_must_succeed' default from False to True [#64462](https://github.com/saltstack/salt/issues/64462) + + +### Fixed + +- When an NFS or FUSE mount fails to unmount when mount options have changed, try again with a lazy umount before mounting again. [#18907](https://github.com/saltstack/salt/issues/18907) +- fix autoaccept gpg keys by supporting it in refresh_db module [#42039](https://github.com/saltstack/salt/issues/42039) +- Made cmd.script work with files from the fileserver via salt-ssh [#48067](https://github.com/saltstack/salt/issues/48067) +- Made slsutil.renderer work with salt-ssh [#50196](https://github.com/saltstack/salt/issues/50196) +- Fixed defaults.merge is not available when using salt-ssh [#51605](https://github.com/saltstack/salt/issues/51605) +- Fix extfs.mkfs missing parameter handling for -C, -d, and -e [#51858](https://github.com/saltstack/salt/issues/51858) +- Fixed Salt master does not renew token [#51986](https://github.com/saltstack/salt/issues/51986) +- Fixed salt-ssh continues state/pillar rendering with incorrect data when an exception is raised by a module on the target [#52452](https://github.com/saltstack/salt/issues/52452) +- Fix extfs.tune has 'reserved' documented twice and is missing the 'reserved_percentage' keyword argument [#54426](https://github.com/saltstack/salt/issues/54426) +- Fix the ability of the 'selinux.port_policy_present' state to modify. [#55687](https://github.com/saltstack/salt/issues/55687) +- Fixed config.get does not support merge option with salt-ssh [#56441](https://github.com/saltstack/salt/issues/56441) +- Removed an unused assignment in file.patch [#57204](https://github.com/saltstack/salt/issues/57204) +- Fixed vault module fetching more than one secret in one run with single-use tokens [#57561](https://github.com/saltstack/salt/issues/57561) +- Use brew path from which in mac_brew_pkg module and rely on _homebrew_bin() everytime [#57946](https://github.com/saltstack/salt/issues/57946) +- Fixed Vault verify option to work on minions when only specified in master config [#58174](https://github.com/saltstack/salt/issues/58174) +- Fixed vault command errors configured locally [#58580](https://github.com/saltstack/salt/issues/58580) +- Fixed issue with basic auth causing invalid header error and 401 Bad Request, by using HTTPBasicAuthHandler instead of header. [#58936](https://github.com/saltstack/salt/issues/58936) +- Make the LXD module work with pyLXD > 2.10 [#59514](https://github.com/saltstack/salt/issues/59514) +- Return error if patch file passed to state file.patch is malformed. [#59806](https://github.com/saltstack/salt/issues/59806) +- Handle failure and error information from tuned module/state [#60500](https://github.com/saltstack/salt/issues/60500) +- Fixed sdb.get_or_set_hash with Vault single-use tokens [#60779](https://github.com/saltstack/salt/issues/60779) +- Fixed state.test does not work with salt-ssh [#61100](https://github.com/saltstack/salt/issues/61100) +- Made slsutil.findup work with salt-ssh [#61143](https://github.com/saltstack/salt/issues/61143) +- Allow all primitive grain types for autosign_grains [#61416](https://github.com/saltstack/salt/issues/61416), [#63708](https://github.com/saltstack/salt/issues/63708) +- `ipset.new_set` no longer fails when creating a set type that uses the `family` create option [#61620](https://github.com/saltstack/salt/issues/61620) +- Fixed Vault session storage to allow unlimited use tokens [#62380](https://github.com/saltstack/salt/issues/62380) +- fix the efi grain on FreeBSD [#63052](https://github.com/saltstack/salt/issues/63052) +- Fixed gpg.receive_keys returns success on failed import [#63144](https://github.com/saltstack/salt/issues/63144) +- Fixed GPG state module always reports success without changes [#63153](https://github.com/saltstack/salt/issues/63153) +- Fixed GPG state module does not respect test mode [#63156](https://github.com/saltstack/salt/issues/63156) +- Fixed gpg.absent with gnupghome/user, fixed gpg.delete_key with gnupghome [#63159](https://github.com/saltstack/salt/issues/63159) +- Fixed service module does not handle enable/disable if systemd service is an alias [#63214](https://github.com/saltstack/salt/issues/63214) +- Made x509_v2 compound match detection use new runner instead of peer publishing [#63278](https://github.com/saltstack/salt/issues/63278) +- Need to make sure we update __pillar__ during a pillar refresh to ensure that process_beacons has the updated beacons loaded from pillar. [#63583](https://github.com/saltstack/salt/issues/63583) +- This implements the vpc_uuid parameter when creating a droplet. This parameter selects the correct virtual private cloud (private network interface). [#63714](https://github.com/saltstack/salt/issues/63714) +- pkg.installed no longer reports failure when installing packages that are installed via the task manager [#63767](https://github.com/saltstack/salt/issues/63767) +- mac_xattr.list and mac_xattr.read will replace undecode-able bytes to avoid raising CommandExecutionError. [#63779](https://github.com/saltstack/salt/issues/63779) [#63779](https://github.com/saltstack/salt/issues/63779) +- Fix aptpkg.latest_version performance, reducing number of times to 'shell out' [#63982](https://github.com/saltstack/salt/issues/63982) +- Added option to use a fresh connection for mysql cache [#63991](https://github.com/saltstack/salt/issues/63991) +- [lxd] Fixed a bug in `container_create` which prevented devices which are not of type `disk` to be correctly created and added to the container when passed via the `devices` parameter. [#63996](https://github.com/saltstack/salt/issues/63996) +- Skipped the `isfile` check to greatly increase speed of reading minion keys for systems with a large number of minions on slow file storage [#64260](https://github.com/saltstack/salt/issues/64260) +- Fix utf8 handling in 'pass' renderer [#64300](https://github.com/saltstack/salt/issues/64300) +- Upgade tornado to 6.3.2 [#64305](https://github.com/saltstack/salt/issues/64305) +- Prevent errors due missing 'transactional_update.apply' on SLE Micro and MicroOS. [#64369](https://github.com/saltstack/salt/issues/64369) +- Fix 'unable to unmount' failure to return False result instead of None [#64420](https://github.com/saltstack/salt/issues/64420) +- Fixed issue uninstalling duplicate packages in ``win_appx`` execution module [#64450](https://github.com/saltstack/salt/issues/64450) +- Clean up tech debt, IPC now uses tcp transport. [#64488](https://github.com/saltstack/salt/issues/64488) +- Made salt-ssh more strict when handling unexpected situations and state.* wrappers treat a remote exception as failure, excluded salt-ssh error returns from mine [#64531](https://github.com/saltstack/salt/issues/64531) +- Fix flaky test for LazyLoader with isolated mocking of threading.RLock [#64567](https://github.com/saltstack/salt/issues/64567) +- Fix possible `KeyError` exceptions in `salt.utils.user.get_group_dict` + while reading improper duplicated GID assigned for the user. [#64599](https://github.com/saltstack/salt/issues/64599) +- changed vm_config() to deep-merge vm_overrides of specific VM, instead of simple-merging the whole vm_overrides [#64610](https://github.com/saltstack/salt/issues/64610) +- Fix the way Salt tries to get the Homebrew's prefix + + The first attempt to get the Homebrew's prefix is to look for + the `HOMEBREW_PREFIX` environment variable. If it's not set, then + Salt tries to get the prefix from the `brew` command. However, the + `brew` command can fail. So a last attempt is made to get the + prefix by guessing the installation path. [#64924](https://github.com/saltstack/salt/issues/64924) +- Add missing MySQL Grant SERVICE_CONNECTION_ADMIN to mysql module. [#64934](https://github.com/saltstack/salt/issues/64934) +- Fixed slsutil.update with salt-ssh during template rendering [#65067](https://github.com/saltstack/salt/issues/65067) +- Keep track when an included file only includes sls files but is a requisite. [#65080](https://github.com/saltstack/salt/issues/65080) +- Fixed `gpg.present` succeeds when the keyserver is unreachable [#65169](https://github.com/saltstack/salt/issues/65169) +- Fix typo in nftables module to ensure unique nft family values [#65295](https://github.com/saltstack/salt/issues/65295) +- Dereference symlinks to set proper __cli opt [#65435](https://github.com/saltstack/salt/issues/65435) +- Made salt-ssh merge master top returns for the same environment [#65480](https://github.com/saltstack/salt/issues/65480) +- Account for situation where the metadata grain fails because the AWS environment requires an authentication token to query the metadata URL. [#65513](https://github.com/saltstack/salt/issues/65513) +- Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. [#65562](https://github.com/saltstack/salt/issues/65562) +- Added SSH wrapper for logmod [#65630](https://github.com/saltstack/salt/issues/65630) +- Include changes in the results when schedule.present state is run with test=True. [#65652](https://github.com/saltstack/salt/issues/65652) +- Fix extfs.tune doesn't pass retcode to module.run [#65686](https://github.com/saltstack/salt/issues/65686) +- Return an error message when the DNS plugin is not supported [#65739](https://github.com/saltstack/salt/issues/65739) +- Execution modules have access to regular fileclient durring pillar rendering. [#66124](https://github.com/saltstack/salt/issues/66124) +- Fixed a issue with server channel where a minion's public key + would be rejected if it contained a final newline character. [#66126](https://github.com/saltstack/salt/issues/66126) + + +### Added + +- Allowed publishing to regular minions from the SSH wrapper [#40943](https://github.com/saltstack/salt/issues/40943) +- Added syncing of custom salt-ssh wrappers [#45450](https://github.com/saltstack/salt/issues/45450) +- Made salt-ssh sync custom utils [#53666](https://github.com/saltstack/salt/issues/53666) +- Add ability to use file.managed style check_cmd in file.serialize [#53982](https://github.com/saltstack/salt/issues/53982) +- Revised use of deprecated net-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 [#57541](https://github.com/saltstack/salt/issues/57541) +- Added password support to Redis returner. [#58044](https://github.com/saltstack/salt/issues/58044) +- Added a state (win_task) for managing scheduled tasks on Windows [#59037](https://github.com/saltstack/salt/issues/59037) +- Added keyring param to gpg modules [#59783](https://github.com/saltstack/salt/issues/59783) +- Added new grain to detect the Salt package type: onedir, pip or system [#62589](https://github.com/saltstack/salt/issues/62589) +- Added Vault AppRole and identity issuance to minions [#62823](https://github.com/saltstack/salt/issues/62823) +- Added Vault AppRole auth mount path configuration option [#62825](https://github.com/saltstack/salt/issues/62825) +- Added distribution of Vault authentication details via response wrapping [#62828](https://github.com/saltstack/salt/issues/62828) +- Add salt package type information. Either onedir, pip or system. [#62961](https://github.com/saltstack/salt/issues/62961) +- Added signature verification to file.managed/archive.extracted [#63143](https://github.com/saltstack/salt/issues/63143) +- Added signed_by_any/signed_by_all parameters to gpg.verify [#63166](https://github.com/saltstack/salt/issues/63166) +- Added match runner [#63278](https://github.com/saltstack/salt/issues/63278) +- Added Vault token lifecycle management [#63406](https://github.com/saltstack/salt/issues/63406) +- adding new call for openscap xccdf eval supporting new parameters [#63416](https://github.com/saltstack/salt/issues/63416) +- Added Vault lease management utility [#63440](https://github.com/saltstack/salt/issues/63440) +- implement removal of ptf packages in zypper pkg module [#63442](https://github.com/saltstack/salt/issues/63442) +- add JUnit output for saltcheck [#63463](https://github.com/saltstack/salt/issues/63463) +- Add ability for file.keyvalue to create a file if it doesn't exist [#63545](https://github.com/saltstack/salt/issues/63545) +- added cleanup of temporary mountpoint dir for macpackage installed state [#63905](https://github.com/saltstack/salt/issues/63905) +- Add pkg.installed show installable version in test mode [#63985](https://github.com/saltstack/salt/issues/63985) +- Added patch option to Vault SDB driver [#64096](https://github.com/saltstack/salt/issues/64096) +- Added flags to create local users and groups [#64256](https://github.com/saltstack/salt/issues/64256) +- Added inline specification of trusted CA root certificate for Vault [#64379](https://github.com/saltstack/salt/issues/64379) +- Add ability to return False result in test mode of configurable_test_state [#64418](https://github.com/saltstack/salt/issues/64418) +- Switched Salt's onedir Python version to 3.11 [#64457](https://github.com/saltstack/salt/issues/64457) +- Added support for dnf5 and its new command syntax [#64532](https://github.com/saltstack/salt/issues/64532) +- Adding a new decorator to indicate when a module is deprecated in favor of a Salt extension. [#64569](https://github.com/saltstack/salt/issues/64569) +- Add jq-esque to_entries and from_entries functions [#64600](https://github.com/saltstack/salt/issues/64600) +- Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. [#64660](https://github.com/saltstack/salt/issues/64660) +- Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False [#64665](https://github.com/saltstack/salt/issues/64665) +- Strenghten Salt's HA capabilities with master clustering. [#64939](https://github.com/saltstack/salt/issues/64939) +- Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems [#64978](https://github.com/saltstack/salt/issues/64978) +- Add support for show_jid to salt-run + + Adds support for show_jid master config option to salt-run, so its behaviour matches the salt cli command. [#65008](https://github.com/saltstack/salt/issues/65008) +- Add ability to remove packages by wildcard via apt execution module [#65220](https://github.com/saltstack/salt/issues/65220) +- Added support for master top modules on masterless minions [#65479](https://github.com/saltstack/salt/issues/65479) +- Allowed accessing the regular mine from the SSH wrapper [#65645](https://github.com/saltstack/salt/issues/65645) +- Allow enabling backup for Linode in Salt Cloud [#65697](https://github.com/saltstack/salt/issues/65697) +- Add a backup schedule setter fFunction for Linode VMs [#65713](https://github.com/saltstack/salt/issues/65713) +- Add acme support for manual plugin hooks [#65744](https://github.com/saltstack/salt/issues/65744) + + +### Security + +- Upgrade to `tornado>=6.3.3` due to https://github.com/advisories/GHSA-qppv-j76h-2rpx [#64989](https://github.com/saltstack/salt/issues/64989) +- Update to `gitpython>=3.1.35` due to https://github.com/advisories/GHSA-wfm5-v35h-vwf4 and https://github.com/advisories/GHSA-cwvm-v4w8-q58c [#65137](https://github.com/saltstack/salt/issues/65137) + + ## 3007.0rc1 (2024-01-02) diff --git a/changelog/18907.fixed.md b/changelog/18907.fixed.md deleted file mode 100644 index 3c728b85db5..00000000000 --- a/changelog/18907.fixed.md +++ /dev/null @@ -1 +0,0 @@ -When an NFS or FUSE mount fails to unmount when mount options have changed, try again with a lazy umount before mounting again. diff --git a/changelog/40943.added.md b/changelog/40943.added.md deleted file mode 100644 index f8f5f8199ff..00000000000 --- a/changelog/40943.added.md +++ /dev/null @@ -1 +0,0 @@ -Allowed publishing to regular minions from the SSH wrapper diff --git a/changelog/42039.fixed.md b/changelog/42039.fixed.md deleted file mode 100644 index d3e9eab2d0c..00000000000 --- a/changelog/42039.fixed.md +++ /dev/null @@ -1 +0,0 @@ -fix autoaccept gpg keys by supporting it in refresh_db module diff --git a/changelog/45450.added.md b/changelog/45450.added.md deleted file mode 100644 index c7d6cd93074..00000000000 --- a/changelog/45450.added.md +++ /dev/null @@ -1 +0,0 @@ -Added syncing of custom salt-ssh wrappers diff --git a/changelog/48067.fixed.md b/changelog/48067.fixed.md deleted file mode 100644 index b060c44cde8..00000000000 --- a/changelog/48067.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made cmd.script work with files from the fileserver via salt-ssh diff --git a/changelog/50196.fixed.md b/changelog/50196.fixed.md deleted file mode 100644 index 979411a640d..00000000000 --- a/changelog/50196.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made slsutil.renderer work with salt-ssh diff --git a/changelog/51605.fixed.md b/changelog/51605.fixed.md deleted file mode 100644 index 990b34413d9..00000000000 --- a/changelog/51605.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed defaults.merge is not available when using salt-ssh diff --git a/changelog/51858.fixed.md b/changelog/51858.fixed.md deleted file mode 100644 index 72778ff2599..00000000000 --- a/changelog/51858.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix extfs.mkfs missing parameter handling for -C, -d, and -e diff --git a/changelog/51986.fixed.md b/changelog/51986.fixed.md deleted file mode 100644 index 2ac8623e859..00000000000 --- a/changelog/51986.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed Salt master does not renew token diff --git a/changelog/52452.fixed.md b/changelog/52452.fixed.md deleted file mode 100644 index 4b09aedca67..00000000000 --- a/changelog/52452.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed salt-ssh continues state/pillar rendering with incorrect data when an exception is raised by a module on the target diff --git a/changelog/53120.changed.md b/changelog/53120.changed.md deleted file mode 100644 index 9889e6e83f3..00000000000 --- a/changelog/53120.changed.md +++ /dev/null @@ -1 +0,0 @@ -Masquerade property will not default to false turning off masquerade if not specified. diff --git a/changelog/53666.added.md b/changelog/53666.added.md deleted file mode 100644 index 0f82455c934..00000000000 --- a/changelog/53666.added.md +++ /dev/null @@ -1 +0,0 @@ -Made salt-ssh sync custom utils diff --git a/changelog/53982.added.md b/changelog/53982.added.md deleted file mode 100644 index e9411910188..00000000000 --- a/changelog/53982.added.md +++ /dev/null @@ -1 +0,0 @@ -Add ability to use file.managed style check_cmd in file.serialize diff --git a/changelog/54426.fixed.md b/changelog/54426.fixed.md deleted file mode 100644 index 172458ae258..00000000000 --- a/changelog/54426.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix extfs.tune has 'reserved' documented twice and is missing the 'reserved_percentage' keyword argument diff --git a/changelog/55687.fixed.md b/changelog/55687.fixed.md deleted file mode 100644 index 73c8c852b3f..00000000000 --- a/changelog/55687.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix the ability of the 'selinux.port_policy_present' state to modify. diff --git a/changelog/56441.fixed.md b/changelog/56441.fixed.md deleted file mode 100644 index 489ad80f770..00000000000 --- a/changelog/56441.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed config.get does not support merge option with salt-ssh diff --git a/changelog/57204.fixed.md b/changelog/57204.fixed.md deleted file mode 100644 index 038b6642852..00000000000 --- a/changelog/57204.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Removed an unused assignment in file.patch diff --git a/changelog/57541.added.md b/changelog/57541.added.md deleted file mode 100644 index 985bad2ee10..00000000000 --- a/changelog/57541.added.md +++ /dev/null @@ -1 +0,0 @@ -Revised use of deprecated net-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 diff --git a/changelog/57561.fixed.md b/changelog/57561.fixed.md deleted file mode 100644 index 57ca72619ee..00000000000 --- a/changelog/57561.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed vault module fetching more than one secret in one run with single-use tokens diff --git a/changelog/57946.fixed.md b/changelog/57946.fixed.md deleted file mode 100644 index c2ad189fa7f..00000000000 --- a/changelog/57946.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Use brew path from which in mac_brew_pkg module and rely on _homebrew_bin() everytime diff --git a/changelog/58044.added.md b/changelog/58044.added.md deleted file mode 100644 index 5e4181520ef..00000000000 --- a/changelog/58044.added.md +++ /dev/null @@ -1 +0,0 @@ -Added password support to Redis returner. diff --git a/changelog/58174.fixed.md b/changelog/58174.fixed.md deleted file mode 100644 index e2059921109..00000000000 --- a/changelog/58174.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed Vault verify option to work on minions when only specified in master config diff --git a/changelog/58580.fixed.md b/changelog/58580.fixed.md deleted file mode 100644 index b86d0ac8d4b..00000000000 --- a/changelog/58580.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed vault command errors configured locally diff --git a/changelog/58936.fixed.md b/changelog/58936.fixed.md deleted file mode 100644 index 1ab53ccfe1b..00000000000 --- a/changelog/58936.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed issue with basic auth causing invalid header error and 401 Bad Request, by using HTTPBasicAuthHandler instead of header. diff --git a/changelog/59037.added.md b/changelog/59037.added.md deleted file mode 100644 index 6d74b4ba63c..00000000000 --- a/changelog/59037.added.md +++ /dev/null @@ -1 +0,0 @@ -Added a state (win_task) for managing scheduled tasks on Windows diff --git a/changelog/59514.fixed.md b/changelog/59514.fixed.md deleted file mode 100644 index 1c7726290d9..00000000000 --- a/changelog/59514.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Make the LXD module work with pyLXD > 2.10 diff --git a/changelog/59783.added.md b/changelog/59783.added.md deleted file mode 100644 index ba6d71d494d..00000000000 --- a/changelog/59783.added.md +++ /dev/null @@ -1 +0,0 @@ -Added keyring param to gpg modules diff --git a/changelog/59806.fixed.md b/changelog/59806.fixed.md deleted file mode 100644 index 2cca505c2bf..00000000000 --- a/changelog/59806.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Return error if patch file passed to state file.patch is malformed. diff --git a/changelog/60500.fixed.md b/changelog/60500.fixed.md deleted file mode 100644 index 1daf48c1a11..00000000000 --- a/changelog/60500.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Handle failure and error information from tuned module/state diff --git a/changelog/60779.fixed.md b/changelog/60779.fixed.md deleted file mode 100644 index 597117d1f18..00000000000 --- a/changelog/60779.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed sdb.get_or_set_hash with Vault single-use tokens diff --git a/changelog/61100.fixed.md b/changelog/61100.fixed.md deleted file mode 100644 index d7ac2b6bc3f..00000000000 --- a/changelog/61100.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed state.test does not work with salt-ssh diff --git a/changelog/61143.fixed.md b/changelog/61143.fixed.md deleted file mode 100644 index 08a62c9d8b1..00000000000 --- a/changelog/61143.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made slsutil.findup work with salt-ssh diff --git a/changelog/61416.fixed.md b/changelog/61416.fixed.md deleted file mode 100644 index 3203a0a1c6a..00000000000 --- a/changelog/61416.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Allow all primitive grain types for autosign_grains diff --git a/changelog/61620.fixed.md b/changelog/61620.fixed.md deleted file mode 100644 index cd0818244ce..00000000000 --- a/changelog/61620.fixed.md +++ /dev/null @@ -1 +0,0 @@ -`ipset.new_set` no longer fails when creating a set type that uses the `family` create option diff --git a/changelog/62380.fixed.md b/changelog/62380.fixed.md deleted file mode 100644 index 839ec661d1a..00000000000 --- a/changelog/62380.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed Vault session storage to allow unlimited use tokens diff --git a/changelog/62520.removed.md b/changelog/62520.removed.md deleted file mode 100644 index 381c33ea090..00000000000 --- a/changelog/62520.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removed RHEL 5 support since long since end-of-lifed diff --git a/changelog/62589.added.md b/changelog/62589.added.md deleted file mode 100644 index 2d4dcb0116e..00000000000 --- a/changelog/62589.added.md +++ /dev/null @@ -1 +0,0 @@ -Added new grain to detect the Salt package type: onedir, pip or system diff --git a/changelog/62823.added.md b/changelog/62823.added.md deleted file mode 100644 index cdce46c5b4e..00000000000 --- a/changelog/62823.added.md +++ /dev/null @@ -1 +0,0 @@ -Added Vault AppRole and identity issuance to minions diff --git a/changelog/62825.added.md b/changelog/62825.added.md deleted file mode 100644 index 8935d16d237..00000000000 --- a/changelog/62825.added.md +++ /dev/null @@ -1 +0,0 @@ -Added Vault AppRole auth mount path configuration option diff --git a/changelog/62828.added.md b/changelog/62828.added.md deleted file mode 100644 index d848300f676..00000000000 --- a/changelog/62828.added.md +++ /dev/null @@ -1 +0,0 @@ -Added distribution of Vault authentication details via response wrapping diff --git a/changelog/62961.added.md b/changelog/62961.added.md deleted file mode 100644 index bb33cbdd766..00000000000 --- a/changelog/62961.added.md +++ /dev/null @@ -1 +0,0 @@ -Add salt package type information. Either onedir, pip or system. diff --git a/changelog/63052.fixed.md b/changelog/63052.fixed.md deleted file mode 100644 index 9344ce70fae..00000000000 --- a/changelog/63052.fixed.md +++ /dev/null @@ -1 +0,0 @@ -fix the efi grain on FreeBSD diff --git a/changelog/63143.added.md b/changelog/63143.added.md deleted file mode 100644 index 9a423baeff4..00000000000 --- a/changelog/63143.added.md +++ /dev/null @@ -1 +0,0 @@ -Added signature verification to file.managed/archive.extracted diff --git a/changelog/63144.fixed.md b/changelog/63144.fixed.md deleted file mode 100644 index cc100dcd21f..00000000000 --- a/changelog/63144.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed gpg.receive_keys returns success on failed import diff --git a/changelog/63153.fixed.md b/changelog/63153.fixed.md deleted file mode 100644 index f1c617f8cd6..00000000000 --- a/changelog/63153.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed GPG state module always reports success without changes diff --git a/changelog/63156.fixed.md b/changelog/63156.fixed.md deleted file mode 100644 index 85efe22e226..00000000000 --- a/changelog/63156.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed GPG state module does not respect test mode diff --git a/changelog/63159.fixed.md b/changelog/63159.fixed.md deleted file mode 100644 index 914bb703b28..00000000000 --- a/changelog/63159.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed gpg.absent with gnupghome/user, fixed gpg.delete_key with gnupghome diff --git a/changelog/63166.added.md b/changelog/63166.added.md deleted file mode 100644 index bb672a367bf..00000000000 --- a/changelog/63166.added.md +++ /dev/null @@ -1 +0,0 @@ -Added signed_by_any/signed_by_all parameters to gpg.verify diff --git a/changelog/63214.fixed.md b/changelog/63214.fixed.md deleted file mode 100644 index 58d314aeaa5..00000000000 --- a/changelog/63214.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed service module does not handle enable/disable if systemd service is an alias diff --git a/changelog/63278.added.md b/changelog/63278.added.md deleted file mode 100644 index 5bbf1535cc2..00000000000 --- a/changelog/63278.added.md +++ /dev/null @@ -1 +0,0 @@ -Added match runner diff --git a/changelog/63278.fixed.md b/changelog/63278.fixed.md deleted file mode 100644 index dbf3c7ae562..00000000000 --- a/changelog/63278.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made x509_v2 compound match detection use new runner instead of peer publishing diff --git a/changelog/63406.added.md b/changelog/63406.added.md deleted file mode 100644 index 25e0a5341df..00000000000 --- a/changelog/63406.added.md +++ /dev/null @@ -1 +0,0 @@ -Added Vault token lifecycle management diff --git a/changelog/63416.added.md b/changelog/63416.added.md deleted file mode 100644 index a59fb21eef4..00000000000 --- a/changelog/63416.added.md +++ /dev/null @@ -1 +0,0 @@ -adding new call for openscap xccdf eval supporting new parameters diff --git a/changelog/63440.added.md b/changelog/63440.added.md deleted file mode 100644 index a3fdd865d75..00000000000 --- a/changelog/63440.added.md +++ /dev/null @@ -1 +0,0 @@ -Added Vault lease management utility diff --git a/changelog/63442.added.md b/changelog/63442.added.md deleted file mode 100644 index ad81b2f9d51..00000000000 --- a/changelog/63442.added.md +++ /dev/null @@ -1 +0,0 @@ -implement removal of ptf packages in zypper pkg module diff --git a/changelog/63463.added.md b/changelog/63463.added.md deleted file mode 100644 index 0592bf74a7d..00000000000 --- a/changelog/63463.added.md +++ /dev/null @@ -1 +0,0 @@ -add JUnit output for saltcheck diff --git a/changelog/63545.added.md b/changelog/63545.added.md deleted file mode 100644 index c53ef8dda80..00000000000 --- a/changelog/63545.added.md +++ /dev/null @@ -1 +0,0 @@ -Add ability for file.keyvalue to create a file if it doesn't exist diff --git a/changelog/63583.fixed.md b/changelog/63583.fixed.md deleted file mode 100644 index f1b6e325070..00000000000 --- a/changelog/63583.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Need to make sure we update __pillar__ during a pillar refresh to ensure that process_beacons has the updated beacons loaded from pillar. diff --git a/changelog/63708.fixed.md b/changelog/63708.fixed.md deleted file mode 100644 index 3203a0a1c6a..00000000000 --- a/changelog/63708.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Allow all primitive grain types for autosign_grains diff --git a/changelog/63714.fixed.md b/changelog/63714.fixed.md deleted file mode 100644 index 76a603f3f9c..00000000000 --- a/changelog/63714.fixed.md +++ /dev/null @@ -1 +0,0 @@ -This implements the vpc_uuid parameter when creating a droplet. This parameter selects the correct virtual private cloud (private network interface). diff --git a/changelog/63767.fixed.md b/changelog/63767.fixed.md deleted file mode 100644 index 018b01feb18..00000000000 --- a/changelog/63767.fixed.md +++ /dev/null @@ -1 +0,0 @@ -pkg.installed no longer reports failure when installing packages that are installed via the task manager diff --git a/changelog/63779.fixed.md b/changelog/63779.fixed.md deleted file mode 100644 index 08e7fa44f6e..00000000000 --- a/changelog/63779.fixed.md +++ /dev/null @@ -1 +0,0 @@ -mac_xattr.list and mac_xattr.read will replace undecode-able bytes to avoid raising CommandExecutionError. [#63779](https://github.com/saltstack/salt/issues/63779) diff --git a/changelog/63905.added.md b/changelog/63905.added.md deleted file mode 100644 index 6545f2df43d..00000000000 --- a/changelog/63905.added.md +++ /dev/null @@ -1 +0,0 @@ -added cleanup of temporary mountpoint dir for macpackage installed state diff --git a/changelog/63982.fixed.md b/changelog/63982.fixed.md deleted file mode 100644 index 600e9bcb3a2..00000000000 --- a/changelog/63982.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix aptpkg.latest_version performance, reducing number of times to 'shell out' diff --git a/changelog/63985.added.md b/changelog/63985.added.md deleted file mode 100644 index 49b8114d7cb..00000000000 --- a/changelog/63985.added.md +++ /dev/null @@ -1 +0,0 @@ -Add pkg.installed show installable version in test mode diff --git a/changelog/63991.fixed.md b/changelog/63991.fixed.md deleted file mode 100644 index 03cdfb3210d..00000000000 --- a/changelog/63991.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Added option to use a fresh connection for mysql cache diff --git a/changelog/63996.fixed.md b/changelog/63996.fixed.md deleted file mode 100644 index 09f814a5fa4..00000000000 --- a/changelog/63996.fixed.md +++ /dev/null @@ -1 +0,0 @@ -[lxd] Fixed a bug in `container_create` which prevented devices which are not of type `disk` to be correctly created and added to the container when passed via the `devices` parameter. diff --git a/changelog/64096.added.md b/changelog/64096.added.md deleted file mode 100644 index 567ec1287df..00000000000 --- a/changelog/64096.added.md +++ /dev/null @@ -1 +0,0 @@ -Added patch option to Vault SDB driver diff --git a/changelog/64224.deprecated.md b/changelog/64224.deprecated.md deleted file mode 100644 index abbeca28b88..00000000000 --- a/changelog/64224.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate all Proxmox cloud modules diff --git a/changelog/64256.added.md b/changelog/64256.added.md deleted file mode 100644 index fba43a411f5..00000000000 --- a/changelog/64256.added.md +++ /dev/null @@ -1 +0,0 @@ -Added flags to create local users and groups diff --git a/changelog/64260.fixed.md b/changelog/64260.fixed.md deleted file mode 100644 index 6de5c7a72d0..00000000000 --- a/changelog/64260.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Skipped the `isfile` check to greatly increase speed of reading minion keys for systems with a large number of minions on slow file storage diff --git a/changelog/64300.fixed.md b/changelog/64300.fixed.md deleted file mode 100644 index 4418db1d04c..00000000000 --- a/changelog/64300.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix utf8 handling in 'pass' renderer diff --git a/changelog/64305.fixed.md b/changelog/64305.fixed.md deleted file mode 100644 index f2b4c0c5d7d..00000000000 --- a/changelog/64305.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Upgade tornado to 6.3.2 diff --git a/changelog/64322.removed.md b/changelog/64322.removed.md deleted file mode 100644 index fe7916f991f..00000000000 --- a/changelog/64322.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removing Azure-Cloud modules from the code base. diff --git a/changelog/64369.fixed.md b/changelog/64369.fixed.md deleted file mode 100644 index 6c6b1eba5e0..00000000000 --- a/changelog/64369.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Prevent errors due missing 'transactional_update.apply' on SLE Micro and MicroOS. diff --git a/changelog/64379.added.md b/changelog/64379.added.md deleted file mode 100644 index 7e232ad85e0..00000000000 --- a/changelog/64379.added.md +++ /dev/null @@ -1 +0,0 @@ -Added inline specification of trusted CA root certificate for Vault diff --git a/changelog/64417.removed.md b/changelog/64417.removed.md deleted file mode 100644 index db689856f15..00000000000 --- a/changelog/64417.removed.md +++ /dev/null @@ -1 +0,0 @@ -Dropped Python 3.7 support since it's EOL in 27 Jun 2023 diff --git a/changelog/64418.added.md b/changelog/64418.added.md deleted file mode 100644 index b189c0d40f0..00000000000 --- a/changelog/64418.added.md +++ /dev/null @@ -1 +0,0 @@ -Add ability to return False result in test mode of configurable_test_state diff --git a/changelog/64420.fixed.md b/changelog/64420.fixed.md deleted file mode 100644 index d4f2be87d43..00000000000 --- a/changelog/64420.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix 'unable to unmount' failure to return False result instead of None diff --git a/changelog/64450.fixed.md b/changelog/64450.fixed.md deleted file mode 100644 index 86d36e8094c..00000000000 --- a/changelog/64450.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed issue uninstalling duplicate packages in ``win_appx`` execution module diff --git a/changelog/64457.added.md b/changelog/64457.added.md deleted file mode 100644 index b868b65eb7f..00000000000 --- a/changelog/64457.added.md +++ /dev/null @@ -1 +0,0 @@ -Switched Salt's onedir Python version to 3.11 diff --git a/changelog/64457.changed.md b/changelog/64457.changed.md deleted file mode 100644 index 8e3364743f9..00000000000 --- a/changelog/64457.changed.md +++ /dev/null @@ -1,6 +0,0 @@ -Addressed Python 3.11 deprecations: - -* Switch to `FullArgSpec` since Py 3.11 no longer has `ArgSpec`, deprecated since Py 3.0 -* Stopped using the deprecated `cgi` module. -* Stopped using the deprecated `pipes` module -* Stopped using the deprecated `imp` module diff --git a/changelog/64459.removed.md b/changelog/64459.removed.md deleted file mode 100644 index c37eda28fcd..00000000000 --- a/changelog/64459.removed.md +++ /dev/null @@ -1 +0,0 @@ -Remove salt.payload.Serial diff --git a/changelog/64460.removed.md b/changelog/64460.removed.md deleted file mode 100644 index c0465ad335b..00000000000 --- a/changelog/64460.removed.md +++ /dev/null @@ -1 +0,0 @@ -Remove netmiko_conn and pyeapi_conn from salt.modules.napalm_mod diff --git a/changelog/64461.removed.md b/changelog/64461.removed.md deleted file mode 100644 index 1d542f5e533..00000000000 --- a/changelog/64461.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removed 'transport' arg from salt.utils.event.get_event diff --git a/changelog/64462.changed.md b/changelog/64462.changed.md deleted file mode 100644 index 8728b6eb2d8..00000000000 --- a/changelog/64462.changed.md +++ /dev/null @@ -1 +0,0 @@ -changed 'gpg_decrypt_must_succeed' default from False to True diff --git a/changelog/64488.fixed.md b/changelog/64488.fixed.md deleted file mode 100644 index ee4ef7af50d..00000000000 --- a/changelog/64488.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Clean up tech debt, IPC now uses tcp transport. diff --git a/changelog/64517.removed.md b/changelog/64517.removed.md deleted file mode 100644 index 4c7a2b82a67..00000000000 --- a/changelog/64517.removed.md +++ /dev/null @@ -1 +0,0 @@ -Removed the usage of retired Linode API v3 from Salt Cloud diff --git a/changelog/64531.fixed.md b/changelog/64531.fixed.md deleted file mode 100644 index 1e01e69eaae..00000000000 --- a/changelog/64531.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made salt-ssh more strict when handling unexpected situations and state.* wrappers treat a remote exception as failure, excluded salt-ssh error returns from mine diff --git a/changelog/64532.added.md b/changelog/64532.added.md deleted file mode 100644 index 53595d69280..00000000000 --- a/changelog/64532.added.md +++ /dev/null @@ -1 +0,0 @@ -Added support for dnf5 and its new command syntax diff --git a/changelog/64567.fixed.md b/changelog/64567.fixed.md deleted file mode 100644 index 442d9eda9eb..00000000000 --- a/changelog/64567.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix flaky test for LazyLoader with isolated mocking of threading.RLock diff --git a/changelog/64569.added.md b/changelog/64569.added.md deleted file mode 100644 index 1ee4c96b146..00000000000 --- a/changelog/64569.added.md +++ /dev/null @@ -1 +0,0 @@ -Adding a new decorator to indicate when a module is deprecated in favor of a Salt extension. diff --git a/changelog/64599.fixed.md b/changelog/64599.fixed.md deleted file mode 100644 index 0d03c6b0cf7..00000000000 --- a/changelog/64599.fixed.md +++ /dev/null @@ -1,2 +0,0 @@ -Fix possible `KeyError` exceptions in `salt.utils.user.get_group_dict` -while reading improper duplicated GID assigned for the user. diff --git a/changelog/64600.added.md b/changelog/64600.added.md deleted file mode 100644 index 05707b2bbe6..00000000000 --- a/changelog/64600.added.md +++ /dev/null @@ -1 +0,0 @@ -Add jq-esque to_entries and from_entries functions diff --git a/changelog/64610.fixed.md b/changelog/64610.fixed.md deleted file mode 100644 index de4628940bc..00000000000 --- a/changelog/64610.fixed.md +++ /dev/null @@ -1 +0,0 @@ -changed vm_config() to deep-merge vm_overrides of specific VM, instead of simple-merging the whole vm_overrides diff --git a/changelog/64660.added.md b/changelog/64660.added.md deleted file mode 100644 index 9c2e3db54bd..00000000000 --- a/changelog/64660.added.md +++ /dev/null @@ -1 +0,0 @@ -Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. diff --git a/changelog/64665.added.md b/changelog/64665.added.md deleted file mode 100644 index 1f320613efe..00000000000 --- a/changelog/64665.added.md +++ /dev/null @@ -1 +0,0 @@ -Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False diff --git a/changelog/64893.deprecated.md b/changelog/64893.deprecated.md deleted file mode 100644 index efb81505f9d..00000000000 --- a/changelog/64893.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate all the Vault modules in favor of the Vault Salt Extension https://github.com/salt-extensions/saltext-vault. The Vault modules will be removed in Salt core in 3009.0. diff --git a/changelog/64894.deprecated.md b/changelog/64894.deprecated.md deleted file mode 100644 index 6f8feb46097..00000000000 --- a/changelog/64894.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate all the Docker modules in favor of the Docker Salt Extension https://github.com/saltstack/saltext-docker. The Docker modules will be removed in Salt core in 3009.0. diff --git a/changelog/64896.deprecated.md b/changelog/64896.deprecated.md deleted file mode 100644 index 9164da75e4a..00000000000 --- a/changelog/64896.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate all the Zabbix modules in favor of the Zabbix Salt Extension https://github.com/salt-extensions/saltext-zabbix. The Zabbix modules will be removed in Salt core in 3009.0. diff --git a/changelog/64909.deprecated.md b/changelog/64909.deprecated.md deleted file mode 100644 index 74901b7ac44..00000000000 --- a/changelog/64909.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate all the Apache modules in favor of the Apache Salt Extension https://github.com/salt-extensions/saltext-apache. The Apache modules will be removed in Salt core in 3009.0. diff --git a/changelog/64924.fixed.md b/changelog/64924.fixed.md deleted file mode 100644 index a843345813d..00000000000 --- a/changelog/64924.fixed.md +++ /dev/null @@ -1,7 +0,0 @@ -Fix the way Salt tries to get the Homebrew's prefix - -The first attempt to get the Homebrew's prefix is to look for -the `HOMEBREW_PREFIX` environment variable. If it's not set, then -Salt tries to get the prefix from the `brew` command. However, the -`brew` command can fail. So a last attempt is made to get the -prefix by guessing the installation path. diff --git a/changelog/64934.fixed.md b/changelog/64934.fixed.md deleted file mode 100644 index 601ee1f9132..00000000000 --- a/changelog/64934.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Add missing MySQL Grant SERVICE_CONNECTION_ADMIN to mysql module. diff --git a/changelog/64939.added.md b/changelog/64939.added.md deleted file mode 100644 index 17b9080bb09..00000000000 --- a/changelog/64939.added.md +++ /dev/null @@ -1 +0,0 @@ -Strenghten Salt's HA capabilities with master clustering. diff --git a/changelog/64978.added.md b/changelog/64978.added.md deleted file mode 100644 index 15974414a26..00000000000 --- a/changelog/64978.added.md +++ /dev/null @@ -1 +0,0 @@ -Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems diff --git a/changelog/64989.security.md b/changelog/64989.security.md deleted file mode 100644 index 65ec0821e67..00000000000 --- a/changelog/64989.security.md +++ /dev/null @@ -1 +0,0 @@ -Upgrade to `tornado>=6.3.3` due to https://github.com/advisories/GHSA-qppv-j76h-2rpx diff --git a/changelog/65008.added.md b/changelog/65008.added.md deleted file mode 100644 index 2e8b5adec5e..00000000000 --- a/changelog/65008.added.md +++ /dev/null @@ -1,3 +0,0 @@ -Add support for show_jid to salt-run - -Adds support for show_jid master config option to salt-run, so its behaviour matches the salt cli command. diff --git a/changelog/65067.fixed.md b/changelog/65067.fixed.md deleted file mode 100644 index d6de87b5bc1..00000000000 --- a/changelog/65067.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed slsutil.update with salt-ssh during template rendering diff --git a/changelog/65080.fixed.md b/changelog/65080.fixed.md deleted file mode 100644 index 92226b222fa..00000000000 --- a/changelog/65080.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Keep track when an included file only includes sls files but is a requisite. diff --git a/changelog/65137.security.md b/changelog/65137.security.md deleted file mode 100644 index 8d6f57c7d0c..00000000000 --- a/changelog/65137.security.md +++ /dev/null @@ -1 +0,0 @@ -Update to `gitpython>=3.1.35` due to https://github.com/advisories/GHSA-wfm5-v35h-vwf4 and https://github.com/advisories/GHSA-cwvm-v4w8-q58c diff --git a/changelog/65169.fixed.md b/changelog/65169.fixed.md deleted file mode 100644 index 8210d1b62d7..00000000000 --- a/changelog/65169.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fixed `gpg.present` succeeds when the keyserver is unreachable diff --git a/changelog/65220.added.md b/changelog/65220.added.md deleted file mode 100644 index 6db0a4c4b0a..00000000000 --- a/changelog/65220.added.md +++ /dev/null @@ -1 +0,0 @@ -Add ability to remove packages by wildcard via apt execution module diff --git a/changelog/65295.fixed.md b/changelog/65295.fixed.md deleted file mode 100644 index c672de05b75..00000000000 --- a/changelog/65295.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix typo in nftables module to ensure unique nft family values diff --git a/changelog/65435.fixed.md b/changelog/65435.fixed.md deleted file mode 100644 index 5fa532891d3..00000000000 --- a/changelog/65435.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Dereference symlinks to set proper __cli opt diff --git a/changelog/65479.added.md b/changelog/65479.added.md deleted file mode 100644 index 037ba183c94..00000000000 --- a/changelog/65479.added.md +++ /dev/null @@ -1 +0,0 @@ -Added support for master top modules on masterless minions diff --git a/changelog/65480.fixed.md b/changelog/65480.fixed.md deleted file mode 100644 index ea30dbc50b7..00000000000 --- a/changelog/65480.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Made salt-ssh merge master top returns for the same environment diff --git a/changelog/65513.fixed.md b/changelog/65513.fixed.md deleted file mode 100644 index ea2b5f43f8a..00000000000 --- a/changelog/65513.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Account for situation where the metadata grain fails because the AWS environment requires an authentication token to query the metadata URL. diff --git a/changelog/65542.deprecated.md b/changelog/65542.deprecated.md deleted file mode 100644 index 13ad306efa9..00000000000 --- a/changelog/65542.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecation warning for Salt's backport of ``OrderedDict`` class which will be removed in 3009 diff --git a/changelog/65562.fixed.md b/changelog/65562.fixed.md deleted file mode 100644 index ba483b4b779..00000000000 --- a/changelog/65562.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. diff --git a/changelog/65565.deprecated.md b/changelog/65565.deprecated.md deleted file mode 100644 index 95c4b572265..00000000000 --- a/changelog/65565.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecate Kubernetes modules for move to saltext-kubernetes in version 3009 diff --git a/changelog/65567.deprecated.md b/changelog/65567.deprecated.md deleted file mode 100644 index 54069d1cf04..00000000000 --- a/changelog/65567.deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Deprecated all Pushover modules in favor of the Salt Extension at https://github.com/salt-extensions/saltext-pushover. The Pushover modules will be removed from Salt core in 3009.0 diff --git a/changelog/65630.fixed.md b/changelog/65630.fixed.md deleted file mode 100644 index e8650abcdc1..00000000000 --- a/changelog/65630.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Added SSH wrapper for logmod diff --git a/changelog/65645.added.md b/changelog/65645.added.md deleted file mode 100644 index eeddb0f332a..00000000000 --- a/changelog/65645.added.md +++ /dev/null @@ -1 +0,0 @@ -Allowed accessing the regular mine from the SSH wrapper diff --git a/changelog/65652.fixed.md b/changelog/65652.fixed.md deleted file mode 100644 index 2f93147a233..00000000000 --- a/changelog/65652.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Include changes in the results when schedule.present state is run with test=True. diff --git a/changelog/65686.fixed.md b/changelog/65686.fixed.md deleted file mode 100644 index 11dad52ae68..00000000000 --- a/changelog/65686.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Fix extfs.tune doesn't pass retcode to module.run diff --git a/changelog/65697.added.md b/changelog/65697.added.md deleted file mode 100644 index 322289aedc6..00000000000 --- a/changelog/65697.added.md +++ /dev/null @@ -1 +0,0 @@ -Allow enabling backup for Linode in Salt Cloud diff --git a/changelog/65713.added.md b/changelog/65713.added.md deleted file mode 100644 index 19f4b190f1a..00000000000 --- a/changelog/65713.added.md +++ /dev/null @@ -1 +0,0 @@ -Add a backup schedule setter fFunction for Linode VMs diff --git a/changelog/65739.fixed.md b/changelog/65739.fixed.md deleted file mode 100644 index 23eaea55c0f..00000000000 --- a/changelog/65739.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Return an error message when the DNS plugin is not supported diff --git a/changelog/65744.added.md b/changelog/65744.added.md deleted file mode 100644 index 1d751e475ce..00000000000 --- a/changelog/65744.added.md +++ /dev/null @@ -1 +0,0 @@ -Add acme support for manual plugin hooks diff --git a/changelog/65986.deprecated.md b/changelog/65986.deprecated.md deleted file mode 100644 index 582631a4100..00000000000 --- a/changelog/65986.deprecated.md +++ /dev/null @@ -1,8 +0,0 @@ -Removed deprecated code: - -* All of ``salt/log/`` which has been on a deprecation path for a long time. -* Some of the logging handlers found in ``salt/_logging/handlers`` have been removed since the standard library provides - them. -* Removed the deprecated ``salt/modules/cassandra_mod.py`` module and any tests for it. -* Removed the deprecated ``salt/returners/cassandra_return.py`` module and any tests for it. -* Removed the deprecated ``salt/returners/django_return.py`` module and any tests for it. diff --git a/changelog/66124.fixed.md b/changelog/66124.fixed.md deleted file mode 100644 index 2721fed62b3..00000000000 --- a/changelog/66124.fixed.md +++ /dev/null @@ -1 +0,0 @@ -Execution modules have access to regular fileclient durring pillar rendering. diff --git a/changelog/66126.fixed.md b/changelog/66126.fixed.md deleted file mode 100644 index 9879189e644..00000000000 --- a/changelog/66126.fixed.md +++ /dev/null @@ -1,2 +0,0 @@ -Fixed a issue with server channel where a minion's public key -would be rejected if it contained a final newline character. diff --git a/doc/man/salt-api.1 b/doc/man/salt-api.1 index f82b64a4acf..e1b6eaf98f6 100644 --- a/doc/man/salt-api.1 +++ b/doc/man/salt-api.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-API" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-API" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-api \- salt-api Command .sp diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1 index 01a8c6c5900..c5db295fe31 100644 --- a/doc/man/salt-call.1 +++ b/doc/man/salt-call.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-CALL" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-CALL" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-call \- salt-call Documentation .SH SYNOPSIS diff --git a/doc/man/salt-cloud.1 b/doc/man/salt-cloud.1 index e2c57db40fc..b9f7d287b03 100644 --- a/doc/man/salt-cloud.1 +++ b/doc/man/salt-cloud.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-CLOUD" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-CLOUD" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-cloud \- Salt Cloud Command .sp diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1 index bbd76b69121..4bbcd759a77 100644 --- a/doc/man/salt-cp.1 +++ b/doc/man/salt-cp.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-CP" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-CP" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-cp \- salt-cp Documentation .sp diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1 index c6de3044097..9287e07fa3c 100644 --- a/doc/man/salt-key.1 +++ b/doc/man/salt-key.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-KEY" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-KEY" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-key \- salt-key Documentation .SH SYNOPSIS diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1 index e7c04e2c15f..f645cd60541 100644 --- a/doc/man/salt-master.1 +++ b/doc/man/salt-master.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-MASTER" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-MASTER" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-master \- salt-master Documentation .sp diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1 index 70e2f1879c7..d3741f30dd3 100644 --- a/doc/man/salt-minion.1 +++ b/doc/man/salt-minion.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-MINION" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-MINION" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-minion \- salt-minion Documentation .sp diff --git a/doc/man/salt-proxy.1 b/doc/man/salt-proxy.1 index 93bdd1f6fae..d8e782ecc34 100644 --- a/doc/man/salt-proxy.1 +++ b/doc/man/salt-proxy.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-PROXY" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-PROXY" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-proxy \- salt-proxy Documentation .sp diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1 index 5231095e460..f786144b903 100644 --- a/doc/man/salt-run.1 +++ b/doc/man/salt-run.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-RUN" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-RUN" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-run \- salt-run Documentation .sp diff --git a/doc/man/salt-ssh.1 b/doc/man/salt-ssh.1 index 1835a0ba620..190a94b33ee 100644 --- a/doc/man/salt-ssh.1 +++ b/doc/man/salt-ssh.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-SSH" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-SSH" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-ssh \- salt-ssh Documentation .SH SYNOPSIS diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1 index 652fbeb0c94..5606f6698c0 100644 --- a/doc/man/salt-syndic.1 +++ b/doc/man/salt-syndic.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT-SYNDIC" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT-SYNDIC" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt-syndic \- salt-syndic Documentation .sp diff --git a/doc/man/salt.1 b/doc/man/salt.1 index 5faa32466d7..2f31d337ee0 100644 --- a/doc/man/salt.1 +++ b/doc/man/salt.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt \- salt .SH SYNOPSIS diff --git a/doc/man/salt.7 b/doc/man/salt.7 index 108bbdf6bf4..51163c375f2 100644 --- a/doc/man/salt.7 +++ b/doc/man/salt.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SALT" "7" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SALT" "7" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME salt \- Salt Documentation .SH SALT PROJECT @@ -1693,6 +1693,293 @@ for the current installation instructions. .sp This section explains how to configure user access, view and store job results, secure and troubleshoot, and how to perform many other administrative tasks. +.SS Configuring Salt +.sp +Salt configuration is very simple. The default configuration for the +\fI\%master\fP will work for most installations and the only requirement for +setting up a \fI\%minion\fP is to set the location of the master in the minion +configuration file. +.sp +The configuration files will be installed to \fB/etc/salt\fP and are named +after the respective components, \fB/etc/salt/master\fP, and +\fB/etc/salt/minion\fP\&. +.SS Master Configuration +.sp +By default the Salt master listens on ports 4505 and 4506 on all +interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the +\(dqinterface\(dq directive in the master configuration file, typically +\fB/etc/salt/master\fP, as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\- #interface: 0.0.0.0 ++ interface: 10.0.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +After updating the configuration file, restart the Salt master. +See the \fI\%master configuration reference\fP +for more details about other configurable options. +.SS Minion Configuration +.sp +Although there are many Salt Minion configuration options, configuring +a Salt Minion is very simple. By default a Salt Minion will +try to connect to the DNS name \(dqsalt\(dq; if the Minion is able to +resolve that name correctly, no configuration is needed. +.sp +If the DNS name \(dqsalt\(dq does not resolve to point to the correct +location of the Master, redefine the \(dqmaster\(dq directive in the minion +configuration file, typically \fB/etc/salt/minion\fP, as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\- #master: salt ++ master: 10.0.0.1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +After updating the configuration file, restart the Salt minion. +See the \fI\%minion configuration reference\fP +for more details about other configurable options. +.SS Proxy Minion Configuration +.sp +A proxy minion emulates the behaviour of a regular minion +and inherits their options. +.sp +Similarly, the configuration file is \fB/etc/salt/proxy\fP and the proxy +tries to connect to the DNS name \(dqsalt\(dq. +.sp +In addition to the regular minion options, +there are several proxy\-specific \- see the +\fI\%proxy minion configuration reference\fP\&. +.SS Running Salt +.INDENT 0.0 +.IP 1. 3 +Start the master in the foreground (to daemonize the process, pass the +\fI\%\-d flag\fP): +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-master +.ft P +.fi +.UNINDENT +.UNINDENT +.IP 2. 3 +Start the minion in the foreground (to daemonize the process, pass the +\fI\%\-d flag\fP): +.INDENT 3.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-minion +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Having trouble?" +.sp +The simplest way to troubleshoot Salt is to run the master and minion in +the foreground with \fI\%log level\fP set to \fBdebug\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-master \-\-log\-level=debug +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For information on salt\(aqs logging system please see the \fI\%logging +document\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Run as an unprivileged (non\-root) user" +.sp +To run Salt as another user, set the \fI\%user\fP parameter in the +master config file. +.sp +Additionally, ownership, and permissions need to be set such that the +desired user can read from and write to the following directories (and +their subdirectories, where applicable): +.INDENT 0.0 +.IP \(bu 2 +/etc/salt +.IP \(bu 2 +/var/cache/salt +.IP \(bu 2 +/var/log/salt +.IP \(bu 2 +/var/run/salt +.UNINDENT +.sp +More information about running salt as a non\-privileged user can be found +\fI\%here\fP\&. +.UNINDENT +.UNINDENT +.sp +There is also a full \fI\%troubleshooting guide\fP +available. +.SS Key Identity +.sp +Salt provides commands to validate the identity of your Salt master +and Salt minions before the initial key exchange. Validating key identity helps +avoid inadvertently connecting to the wrong Salt master, and helps prevent +a potential MiTM attack when establishing the initial connection. +.SS Master Key Fingerprint +.sp +Print the master key fingerprint by running the following command on the Salt master: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-key \-F master +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Copy the \fBmaster.pub\fP fingerprint from the \fILocal Keys\fP section, and then set this value +as the \fI\%master_finger\fP in the minion configuration file. Save the configuration +file and then restart the Salt minion. +.SS Minion Key Fingerprint +.sp +Run the following command on each Salt minion to view the minion key fingerprint: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call \-\-local key.finger +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Compare this value to the value that is displayed when you run the +\fBsalt\-key \-\-finger \fP command on the Salt master. +.SS Key Management +.sp +Salt uses AES encryption for all communication between the Master and +the Minion. This ensures that the commands sent to the Minions cannot +be tampered with, and that communication between Master and Minion is +authenticated through trusted, accepted keys. +.sp +Before commands can be sent to a Minion, its key must be accepted on +the Master. Run the \fBsalt\-key\fP command to list the keys known to +the Salt Master: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[root@master ~]# salt\-key \-L +Unaccepted Keys: +alpha +bravo +charlie +delta +Accepted Keys: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This example shows that the Salt Master is aware of four Minions, but none of +the keys has been accepted. To accept the keys and allow the Minions to be +controlled by the Master, again use the \fBsalt\-key\fP command: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[root@master ~]# salt\-key \-A +[root@master ~]# salt\-key \-L +Unaccepted Keys: +Accepted Keys: +alpha +bravo +charlie +delta +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The +example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys +individually use the lowercase of the same option, \fB\-a keyname\fP\&. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +\fI\%salt\-key manpage\fP +.UNINDENT +.UNINDENT +.SS Sending Commands +.sp +Communication between the Master and a Minion may be verified by running +the \fBtest.version\fP command: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[root@master ~]# salt alpha test.version +alpha: + 2018.3.4 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Communication between the Master and all Minions may be tested in a +similar way: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[root@master ~]# salt \(aq*\(aq test.version +alpha: + 2018.3.4 +bravo: + 2018.3.4 +charlie: + 2018.3.4 +delta: + 2018.3.4 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Each of the Minions should send a \fB2018.3.4\fP response as shown above, +or any other salt version installed. +.SS What\(aqs Next? +.sp +Understanding \fI\%targeting\fP is important. From there, depending +on the way you wish to use Salt, you should also proceed to learn about +\fI\%Remote Execution\fP and \fI\%Configuration Management\fP\&. .SS Configuring the Salt Master .sp The Salt system is amazingly simple and easy to configure, the two components @@ -1816,8 +2103,13 @@ enable_ssh_minions: True \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Cross\-minion communication is still not possible. The Salt mine and -publish.publish do not work between minion types. +Enabling this does not influence the limitations on cross\-minion communication. +The Salt mine and \fBpublish.publish\fP do not work from regular minions +to SSH minions, the other way around is partly possible since 3007.0 +(during state rendering on the master). +This means you can use the mentioned functions to call out to regular minions +in \fBsls\fP templates and wrapper modules, but state modules +(which are executed on the remote) relying on them still do not work. .UNINDENT .UNINDENT .SS \fBret_port\fP @@ -1913,6 +2205,62 @@ pki_dir: /etc/salt/pki/master .fi .UNINDENT .UNINDENT +.SS \fBcluster_id\fP +.sp +New in version 3007. + +.sp +When defined, the master will operate in cluster mode. The master will send the +cluster key and id to minions instead of its own key and id. The master will +also forward its local event bus to other masters defined by \fBcluster_peers\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cluster_id: master +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBcluster_peers\fP +.sp +New in version 3007. + +.sp +When \fBcluster_id\fP is defined, this setting is a list of other master +(hostnames or ips) that will be in the cluster. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cluster_peers: + \- master2 + \- master3 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBcluster_pki_dir\fP +.sp +New in version 3007. + +.sp +When \fBcluster_id\fP is defined, this sets the location of where this cluster +will store its cluster public and private key as well as any minion keys. This +setting will default to the value of \fBpki_dir\fP, but should be changed +to the filesystem location shared between peers in the cluster. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +cluster_pki: /my/gluster/share/pki +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fBextension_modules\fP .sp Changed in version 2016.3.0: The default location for this directory has been moved. Prior to this @@ -6352,31 +6700,6 @@ minionfs_update_interval: 120 .fi .UNINDENT .UNINDENT -.SS azurefs: Azure File Server Backend -.sp -New in version 2015.8.0. - -.sp -See the \fI\%azurefs documentation\fP for usage -examples. -.SS \fBazurefs_update_interval\fP -.sp -New in version 2018.3.0. - -.sp -Default: \fB60\fP -.sp -This option defines the update interval (in seconds) for azurefs. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurefs_update_interval: 120 -.ft P -.fi -.UNINDENT -.UNINDENT .SS s3fs: S3 File Server Backend .sp New in version 0.16.0. @@ -7893,9 +8216,9 @@ and pkg modules. .nf .ft C peer: - foo.example.com: - \- test.* - \- pkg.* + foo\e.example\e.com: + \- test\e..* + \- pkg\e..* .ft P .fi .UNINDENT @@ -7918,22 +8241,34 @@ peer: This is not recommended, since it would allow anyone who gets root on any single minion to instantly have root on all of the minions! .sp -By adding an additional layer you can limit the target hosts in addition to the -accessible commands: +It is also possible to limit target hosts with the \fI\%Compound Matcher\fP\&. +You can achieve this by adding another layer in between the source and the +allowed functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: - foo.example.com: - \(aqdb*\(aq: - \- test.* - \- pkg.* + \(aq.*\e.example\e.com\(aq: + \- \(aqG@role:db\(aq: + \- test\e..* + \- pkg\e..* .ft P .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Notice that the source hosts are matched by a regular expression +on their minion ID, while target hosts can be matched by any of +the \fI\%available matchers\fP\&. +.sp +Note that globbing and regex matching on pillar values is not supported. You can only match exact values. +.UNINDENT +.UNINDENT .SS \fBpeer_run\fP .sp Default: \fB{}\fP @@ -11354,8 +11689,6 @@ pillar .UNINDENT .UNINDENT .SS Top File Settings -.sp -These parameters only have an effect if running a masterless minion. .SS \fBstate_top\fP .sp Default: \fBtop.sls\fP @@ -17915,7 +18248,7 @@ peer: .UNINDENT .UNINDENT .sp -This configuration will allow minions with IDs ending in example.com access +This configuration allows minions with IDs ending in \fB\&.example.com\fP access to the test, ps, and pkg module functions. .INDENT 0.0 .INDENT 3.5 @@ -17923,10 +18256,10 @@ to the test, ps, and pkg module functions. .nf .ft C peer: - .*example.com: - \- test.* - \- ps.* - \- pkg.* + .*\e.example.com: + \- test\e..* + \- ps\e..* + \- pkg\e..* .ft P .fi .UNINDENT @@ -17942,14 +18275,14 @@ allow minions ending with foo.org access to the publisher. .nf .ft C peer: - .*example.com: - \- test.* - \- ps.* - \- pkg.* - .*foo.org: - \- test.* - \- ps.* - \- pkg.* + .*\e.example.com: + \- test\e..* + \- ps\e..* + \- pkg\e..* + .*\e.foo.org: + \- test\e..* + \- ps\e..* + \- pkg\e..* .ft P .fi .UNINDENT @@ -17958,7 +18291,36 @@ peer: \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Functions are matched using regular expressions. +Functions are matched using regular expressions as well. +.UNINDENT +.UNINDENT +.sp +It is also possible to limit target hosts with the \fI\%Compound Matcher\fP\&. +You can achieve this by adding another layer in between the source and the +allowed functions: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +peer: + \(aq.*\e.example\e.com\(aq: + \- \(aqG@role:db\(aq: + \- test\e..* + \- pkg\e..* +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Notice that the source hosts are matched by a regular expression +on their minion ID, while target hosts can be matched by any of +the \fI\%available matchers\fP\&. +.sp +Note that globbing and regex matching on pillar values is not supported. You can only match exact values. .UNINDENT .UNINDENT .SS Peer Runner Communication @@ -20721,10 +21083,12 @@ first.git: edit/vim.sls edit/vimrc nginx/init.sls + shell/init.sls second.git: edit/dev_vimrc haproxy/init.sls + shell.sls third: haproxy/haproxy.conf @@ -20748,6 +21112,14 @@ A request for the file \fBsalt://haproxy/haproxy.conf\fP will be served from the \fBfile:///root/third\fP repo. .UNINDENT .sp +Also a requested state file overrules a directory with an \fIinit.sls\fP\-file. +For example: +.INDENT 0.0 +.IP \(bu 2 +A request for \fBstate.apply shell\fP will be served from the +\fBhttps://github.com/example/second.git\fP git repo. +.UNINDENT +.sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 @@ -23364,6 +23736,46 @@ salt\-call sdb.get sdb://kevinopenstack/password .UNINDENT .UNINDENT .sp +For SDB sub\-keys, ie users[\(aquser1\(aq][\(aqid\(aq] +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +users: + user1: + id: 12345 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To get SDB sub\-keys from the CLI, use a colon to separate sub key values. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call sdb.get sdb://users:user1:id +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To get SDB sub\-keys in a state file, use this syntax: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +users: + user1: + id: sdb.get sdb://users:user1:id +.ft P +.fi +.UNINDENT +.UNINDENT +.sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 @@ -24153,6 +24565,10 @@ use the same transport. We\(aqre investigating a report of an error when using mixed transport types at very heavy loads. .UNINDENT .UNINDENT +.SS TLS Support +.sp +The TLS transport supports full encryption and verification using both server +and client certificates. See \fI\%Transport TLS Support\fP for more details. .SS Wire Protocol .sp This implementation over TCP focuses on flexibility over absolute efficiency. @@ -24176,62 +24592,6 @@ Head contains header information (such as \(dqmessage id\(dq). The Body contains actual message that we are sending. With this flexible wire protocol we can implement any message semantics that we\(aqd like\-\- including multiplexed message passing on a single socket. -.SS TLS Support -.sp -New in version 2016.11.1. - -.sp -The TCP transport allows for the master/minion communication to be optionally -wrapped in a TLS connection. Enabling this is simple, the master and minion need -to be using the tcp connection, then the \fIssl\fP option is enabled. The \fIssl\fP -option is passed as a dict and corresponds to the options passed to the -Python \fI\%ssl.wrap_socket\fP -function. -.sp -A simple setup looks like this, on the Salt Master add the \fIssl\fP option to the -master configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ssl: - keyfile: - certfile: - ssl_version: PROTOCOL_TLSv1_2 - ciphers: ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The minimal \fIssl\fP option in the minion configuration file looks like this: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ssl: True -# Versions below 2016.11.4: -ssl: {} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Specific options can be sent to the minion also, as defined in the Python -\fIssl.wrap_socket\fP function. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -While setting the ssl_version is not required, we recommend it. Some older -versions of python do not support the latest TLS protocol and if this is -the case for your version of python we strongly recommend upgrading your -version of Python. Ciphers specification might be omitted, but strongly -recommended as otherwise all available ciphers will be enabled. -.UNINDENT -.UNINDENT .SS Crypto .sp The current implementation uses the same crypto as the \fBzeromq\fP transport. @@ -24259,6 +24619,118 @@ Salt CLI defaults to \fBglob\fP targeting type, so in order to target specific m .sp For the request server and client we send messages with a \(dqmessage id\(dq. This \(dqmessage id\(dq allows us to multiplex messages across the socket. +.SS Websocket Transport +.sp +The Websocket transport is an implementation of Salt\(aqs transport using the websocket protocol. +The Websocket transport is enabled by changing the \fI\%transport\fP setting +to \fBws\fP on each Salt minion and Salt master. +.SS TLS Support +.sp +The Websocket transport supports full encryption and verification using both server +and client certificates. See \fI\%Transport TLS Support\fP for more details. +.SS Publish Server and Client +.sp +The publish server and client are implemented using aiohttp. +.SS Request Server and Client +.sp +The request server and client are implemented using aiohttp. +.SS Transport TLS Support +.sp +Whenever possible transports should provide TLS Support. Currently the \fI\%TCP Transport\fP and +\fI\%Websocket Transport\fP transports support encryption and verification using TLS. +.sp +New in version 2016.11.1. + +.sp +The TCP transport allows for the master/minion communication to be optionally +wrapped in a TLS connection. Enabling this is simple, the master and minion need +to be using the tcp connection, then the \fBssl\fP option is enabled. The \fBssl\fP +option is passed as a dict and roughly corresponds to the options passed to the +Python \fI\%ssl.wrap_socket\fP +function for backwards compatability. +.sp +New in version 3007.0. + +.sp +The \fBssl\fP option accepts \fBverify_locations\fP and \fBverify_flags\fP\&. The +\fBverify_locations\fP option is a list of strings or dictionaries. Strings are +passed as a single argument to the SSL context\(aqs \fBload_verify_locations\fP +method. Dictionary keys are expected to be one of \fBcafile\fP, \fBcapath\fP, +\fBcadata\fP\&. For each corresponding key, the key and value will be passed as a +keyword argument to \fBload_verify_locations\fP\&. The \fBverify_flags\fP option is +a list of string names of verification flags which will be set on the SSL +context. All paths are assumed to be the full path to the file or directory. +.sp +A simple setup looks like this, on the Salt Master add the \fBssl\fP option to the +master configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ssl: + keyfile: + certfile: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A more complex setup looks like this, on the Salt Master add the \fBssl\fP +option to the master\(aqs configuration file. In this example the Salt Master will +require valid client side certificates from Minions by setting \fBcert_reqs\fP to +\fBCERT_REQUIRED\fP\&. The Salt Master will also check a certificate revocation list +if one is provided in \fBverify_locations\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ssl: + keyfile: + certfile: + cert_reqs: CERT_REQUIRED + verify_locations: + \- + \- capath: + \- cafile: + verify_flags: + \- VERIFY_CRL_CHECK_CHAIN +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The minimal \fIssl\fP option in the minion configuration file looks like this: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ssl: True +# Versions below 2016.11.4: +ssl: {} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A Minion can be configured to present a client certificate to the master like this: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ssl: + keyfile: + certfile: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Specific options can be sent to the minion also, as defined in the Python +\fIssl.wrap_socket\fP function. .SS Master Tops System .sp In 0.10.4 the \fIexternal_nodes\fP system was upgraded to allow for modular @@ -24267,6 +24739,9 @@ subsystems to be used to generate the top file data for a \fI\%highstate\fP run The old \fIexternal_nodes\fP option has been removed. The master tops system provides a pluggable and extendable replacement for it, allowing for multiple different subsystems to provide top file data. +.sp +Changed in version 3007.0: Masterless minions now support master top modules as well. + .sp Using the new \fImaster_tops\fP option is simple: .INDENT 0.0 @@ -24389,5760 +24864,6 @@ functionality allowing a minion to treat master_tops as the single source of truth, irrespective of the top file. .UNINDENT .UNINDENT -.SS Returners -.sp -By default the return values of the commands sent to the Salt minions are -returned to the Salt master, however anything at all can be done with the results -data. -.sp -By using a Salt returner, results data can be redirected to external data\-stores -for analysis and archival. -.sp -Returners pull their configuration values from the Salt minions. Returners are only -configured once, which is generally at load time. -.sp -The returner interface allows the return data to be sent to any system that -can receive data. This means that return data can be sent to a Redis server, -a MongoDB server, a MySQL server, or any system. -.sp -\fBSEE ALSO:\fP -.INDENT 0.0 -.INDENT 3.5 -\fI\%Full list of builtin returners\fP -.UNINDENT -.UNINDENT -.SS Using Returners -.sp -All Salt commands will return the command data back to the master. Specifying -returners will ensure that the data is _also_ sent to the specified returner -interfaces. -.sp -Specifying what returners to use is done when the command is invoked: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.version \-\-return redis_return -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This command will ensure that the redis_return returner is used. -.sp -It is also possible to specify multiple returners: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.version \-\-return mongo_return,redis_return,cassandra_return -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -In this scenario all three returners will be called and the data from the -test.version command will be sent out to the three named returners. -.SS Writing a Returner -.sp -Returners are Salt modules that allow the redirection of results data to targets other than the Salt Master. -.SS Returners Are Easy To Write! -.sp -Writing a Salt returner is straightforward. -.sp -A returner is a Python module containing at minimum a \fBreturner\fP function. -Other optional functions can be included to add support for -\fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, and \fI\%Event Returners\fP\&. -.INDENT 0.0 -.TP -.B \fBreturner\fP -The \fBreturner\fP function must accept a single argument. The argument -contains return data from the called minion function. If the minion -function \fBtest.version\fP is called, the value of the argument will be a -dictionary. Run the following command from a Salt master to get a sample -of the dictionary: -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call \-\-local \-\-metadata test.version \-\-out=pprint -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -import redis -import salt.utils.json - - -def returner(ret): - \(dq\(dq\(dq - Return information to a redis server - \(dq\(dq\(dq - # Get a redis connection - serv = redis.Redis(host=\(dqredis\-serv.example.com\(dq, port=6379, db=\(dq0\(dq) - serv.sadd(\(dq%(id)s:jobs\(dq % ret, ret[\(dqjid\(dq]) - serv.set(\(dq%(jid)s:%(id)s\(dq % ret, salt.utils.json.dumps(ret[\(dqreturn\(dq])) - serv.sadd(\(dqjobs\(dq, ret[\(dqjid\(dq]) - serv.sadd(ret[\(dqjid\(dq], ret[\(dqid\(dq]) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The above example of a returner set to send the data to a Redis server -serializes the data as JSON and sets it in redis. -.SS Using Custom Returner Modules -.sp -Place custom returners in a \fB_returners/\fP directory within the -\fI\%file_roots\fP specified by the master config file. -.sp -Custom returners are distributed when any of the following are called: -.INDENT 0.0 -.IP \(bu 2 -\fI\%state.apply\fP -.IP \(bu 2 -\fI\%saltutil.sync_returners\fP -.IP \(bu 2 -\fI\%saltutil.sync_all\fP -.UNINDENT -.sp -Any custom returners which have been synced to a minion that are named the -same as one of Salt\(aqs default set of returners will take the place of the -default returner with the same name. -.SS Naming the Returner -.sp -Note that a returner\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes -returner \fBfoo\fP), but that its name can be overridden by using a -\fI\%__virtual__ function\fP\&. A good example of this can be -found in the \fI\%redis\fP returner, which is named \fBredis_return.py\fP but is -loaded as simply \fBredis\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -try: - import redis - - HAS_REDIS = True -except ImportError: - HAS_REDIS = False - -__virtualname__ = \(dqredis\(dq - - -def __virtual__(): - if not HAS_REDIS: - return False - return __virtualname__ -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Master Job Cache Support -.sp -\fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, and \fI\%Event Returners\fP\&. -Salt\(aqs \fI\%master_job_cache\fP allows returners to be used as a pluggable -replacement for the \fI\%Default Job Cache\fP\&. In order to do so, a returner -must implement the following functions: -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The code samples contained in this section were taken from the cassandra_cql -returner. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBprep_jid\fP -Ensures that job ids (jid) don\(aqt collide, unless passed_jid is provided. -.sp -\fBnocache\fP is an optional boolean that indicates if return data -should be cached. \fBpassed_jid\fP is a caller provided jid which should be -returned unconditionally. -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -def prep_jid(nocache, passed_jid=None): # pylint: disable=unused\-argument - \(dq\(dq\(dq - Do any work necessary to prepare a JID, including sending a custom id - \(dq\(dq\(dq - return passed_jid if passed_jid is not None else salt.utils.jid.gen_jid() -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBsave_load\fP -Save job information. The \fBjid\fP is generated by \fBprep_jid\fP and should -be considered a unique identifier for the job. The jid, for example, could -be used as the primary/unique key in a database. The \fBload\fP is what is -returned to a Salt master by a minion. \fBminions\fP is a list of minions -that the job was run against. The following code example stores the load as -a JSON string in the salt.jids table. -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -import salt.utils.json - - -def save_load(jid, load, minions=None): - \(dq\(dq\(dq - Save the load to the specified jid id - \(dq\(dq\(dq - query = \(dq\(dq\(dqINSERT INTO salt.jids ( - jid, load - ) VALUES ( - \(aq{0}\(aq, \(aq{1}\(aq - );\(dq\(dq\(dq.format( - jid, salt.utils.json.dumps(load) - ) - - # cassandra_cql.cql_query may raise a CommandExecutionError - try: - __salt__[\(dqcassandra_cql.cql_query\(dq](query) - except CommandExecutionError: - log.critical(\(dqCould not save load in jids table.\(dq) - raise - except Exception as e: - log.critical(\(dqUnexpected error while inserting into jids: {0}\(dq.format(e)) - raise -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBget_load\fP -must accept a job id (jid) and return the job load stored by \fBsave_load\fP, -or an empty dictionary when not found. -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -def get_load(jid): - \(dq\(dq\(dq - Return the load data that marks a specified jid - \(dq\(dq\(dq - query = \(dq\(dq\(dqSELECT load FROM salt.jids WHERE jid = \(aq{0}\(aq;\(dq\(dq\(dq.format(jid) - - ret = {} - - # cassandra_cql.cql_query may raise a CommandExecutionError - try: - data = __salt__[\(dqcassandra_cql.cql_query\(dq](query) - if data: - load = data[0].get(\(dqload\(dq) - if load: - ret = json.loads(load) - except CommandExecutionError: - log.critical(\(dqCould not get load from jids table.\(dq) - raise - except Exception as e: - log.critical( - \(dq\(dq\(dqUnexpected error while getting load from - jids: {0}\(dq\(dq\(dq.format( - str(e) - ) - ) - raise - - return ret -.ft P -.fi -.UNINDENT -.UNINDENT -.SS External Job Cache Support -.sp -Salt\(aqs \fI\%Storing Job Results in an External System\fP extends the \fI\%master_job_cache\fP\&. External -Job Cache support requires the following functions in addition to what is -required for Master Job Cache support: -.INDENT 0.0 -.TP -.B \fBget_jid\fP -Return a dictionary containing the information (load) returned by each -minion when the specified job id was executed. -.UNINDENT -.sp -Sample: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ - \(dqlocal\(dq: { - \(dqmaster_minion\(dq: { - \(dqfun_args\(dq: [], - \(dqjid\(dq: \(dq20150330121011408195\(dq, - \(dqreturn\(dq: \(dq2018.3.4\(dq, - \(dqretcode\(dq: 0, - \(dqsuccess\(dq: true, - \(dqcmd\(dq: \(dq_return\(dq, - \(dq_stamp\(dq: \(dq2015\-03\-30T12:10:12.708663\(dq, - \(dqfun\(dq: \(dqtest.version\(dq, - \(dqid\(dq: \(dqmaster_minion\(dq - } - } -} -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBget_fun\fP -Return a dictionary of minions that called a given Salt function as their -last function call. -.UNINDENT -.sp -Sample: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ - \(dqlocal\(dq: { - \(dqminion1\(dq: \(dqtest.version\(dq, - \(dqminion3\(dq: \(dqtest.version\(dq, - \(dqminion2\(dq: \(dqtest.version\(dq - } -} -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBget_jids\fP -Return a list of all job ids. -.UNINDENT -.sp -Sample: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ - \(dqlocal\(dq: [ - \(dq20150330121011408195\(dq, - \(dq20150330195922139916\(dq - ] -} -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBget_minions\fP -Returns a list of minions -.UNINDENT -.sp -Sample: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ - \(dqlocal\(dq: [ - \(dqminion3\(dq, - \(dqminion2\(dq, - \(dqminion1\(dq, - \(dqmaster_minion\(dq - ] -} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Please refer to one or more of the existing returners (i.e. mysql, -cassandra_cql) if you need further clarification. -.SS Event Support -.sp -An \fBevent_return\fP function must be added to the returner module to allow -events to be logged from a master via the returner. A list of events are passed -to the function by the master. -.sp -The following example was taken from the MySQL returner. In this example, each -event is inserted into the salt_events table keyed on the event tag. The tag -contains the jid and therefore is guaranteed to be unique. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -import salt.utils.json - - -def event_return(events): - \(dq\(dq\(dq - Return event to mysql server - - Requires that configuration be enabled via \(aqevent_return\(aq - option in master config. - \(dq\(dq\(dq - with _get_serv(events, commit=True) as cur: - for event in events: - tag = event.get(\(dqtag\(dq, \(dq\(dq) - data = event.get(\(dqdata\(dq, \(dq\(dq) - sql = \(dq\(dq\(dqINSERT INTO \(gasalt_events\(ga (\(gatag\(ga, \(gadata\(ga, \(gamaster_id\(ga ) - VALUES (%s, %s, %s)\(dq\(dq\(dq - cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__[\(dqid\(dq])) -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Testing the Returner -.sp -The \fBreturner\fP, \fBprep_jid\fP, \fBsave_load\fP, \fBget_load\fP, and -\fBevent_return\fP functions can be tested by configuring the -\fI\%master_job_cache\fP and \fI\%Event Returners\fP in the master config -file and submitting a job to \fBtest.version\fP each minion from the master. -.sp -Once you have successfully exercised the Master Job Cache functions, test the -External Job Cache functions using the \fBret\fP execution module. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call ret.get_jids cassandra_cql \-\-output=json -salt\-call ret.get_fun cassandra_cql test.version \-\-output=json -salt\-call ret.get_minions cassandra_cql \-\-output=json -salt\-call ret.get_jid cassandra_cql 20150330121011408195 \-\-output=json -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Event Returners -.sp -For maximum visibility into the history of events across a Salt -infrastructure, all events seen by a salt master may be logged to one or -more returners. -.sp -To enable event logging, set the \fBevent_return\fP configuration option in the -master config to the returner(s) which should be designated as the handler -for event returns. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Not all returners support event returns. Verify a returner has an -\fBevent_return()\fP function before using. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -On larger installations, many hundreds of events may be generated on a -busy master every second. Be certain to closely monitor the storage of -a given returner as Salt can easily overwhelm an underpowered server -with thousands of returns. -.UNINDENT -.UNINDENT -.SS Full List of Returners -.SS returner modules -.TS -center; -|l|l|. -_ -T{ -\fI\%appoptics_return\fP -T} T{ -Salt returner to return highstate stats to AppOptics Metrics -T} -_ -T{ -\fI\%carbon_return\fP -T} T{ -Take data from salt and \(dqreturn\(dq it into a carbon receiver -T} -_ -T{ -\fI\%cassandra_cql_return\fP -T} T{ -Return data to a cassandra server -T} -_ -T{ -\fI\%cassandra_return\fP -T} T{ -T} -_ -T{ -\fI\%couchbase_return\fP -T} T{ -Simple returner for Couchbase. -T} -_ -T{ -\fI\%couchdb_return\fP -T} T{ -Simple returner for CouchDB. -T} -_ -T{ -\fI\%django_return\fP -T} T{ -Deprecated since version 3006.0. -T} -_ -T{ -\fI\%elasticsearch_return\fP -T} T{ -Return data to an elasticsearch server for indexing. -T} -_ -T{ -\fI\%etcd_return\fP -T} T{ -Return data to an etcd server or cluster -T} -_ -T{ -\fI\%highstate_return\fP -T} T{ -Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file. -T} -_ -T{ -\fI\%influxdb_return\fP -T} T{ -Return data to an influxdb server. -T} -_ -T{ -\fI\%kafka_return\fP -T} T{ -Return data to a Kafka topic -T} -_ -T{ -\fI\%librato_return\fP -T} T{ -Salt returner to return highstate stats to Librato -T} -_ -T{ -\fI\%local\fP -T} T{ -The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly -T} -_ -T{ -\fI\%local_cache\fP -T} T{ -Return data to local job cache -T} -_ -T{ -\fI\%mattermost_returner\fP -T} T{ -Return salt data via mattermost -T} -_ -T{ -\fI\%memcache_return\fP -T} T{ -Return data to a memcache server -T} -_ -T{ -\fI\%mongo_future_return\fP -T} T{ -Return data to a mongodb server -T} -_ -T{ -\fI\%mongo_return\fP -T} T{ -Return data to a mongodb server -T} -_ -T{ -\fI\%multi_returner\fP -T} T{ -Read/Write multiple returners -T} -_ -T{ -\fI\%mysql\fP -T} T{ -Return data to a mysql server -T} -_ -T{ -\fI\%nagios_nrdp_return\fP -T} T{ -Return salt data to Nagios -T} -_ -T{ -\fI\%odbc\fP -T} T{ -Return data to an ODBC compliant server. -T} -_ -T{ -\fI\%pgjsonb\fP -T} T{ -Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type -T} -_ -T{ -\fI\%postgres\fP -T} T{ -Return data to a postgresql server -T} -_ -T{ -\fI\%postgres_local_cache\fP -T} T{ -Use a postgresql server for the master job cache. -T} -_ -T{ -\fI\%pushover_returner\fP -T} T{ -Return salt data via pushover (\fI\%http://www.pushover.net\fP) -T} -_ -T{ -\fI\%rawfile_json\fP -T} T{ -Take data from salt and \(dqreturn\(dq it into a raw file containing the json, with one line per event. -T} -_ -T{ -\fI\%redis_return\fP -T} T{ -Return data to a redis server -T} -_ -T{ -\fI\%sentry_return\fP -T} T{ -Salt returner that reports execution results back to sentry. -T} -_ -T{ -\fI\%slack_returner\fP -T} T{ -Return salt data via slack -T} -_ -T{ -\fI\%slack_webhook_return\fP -T} T{ -Return salt data via Slack using Incoming Webhooks -T} -_ -T{ -\fI\%sms_return\fP -T} T{ -Return data by SMS. -T} -_ -T{ -\fI\%smtp_return\fP -T} T{ -Return salt data via email -T} -_ -T{ -\fI\%splunk\fP -T} T{ -Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar: -T} -_ -T{ -\fI\%sqlite3_return\fP -T} T{ -Insert minion return data into a sqlite3 database -T} -_ -T{ -\fI\%syslog_return\fP -T} T{ -Return data to the host operating system\(aqs syslog facility -T} -_ -T{ -\fI\%telegram_return\fP -T} T{ -Return salt data via Telegram. -T} -_ -T{ -\fI\%xmpp_return\fP -T} T{ -Return salt data via xmpp -T} -_ -T{ -\fI\%zabbix_return\fP -T} T{ -Return salt data to Zabbix -T} -_ -.TE -.SS salt.returners.appoptics_return -.sp -Salt returner to return highstate stats to AppOptics Metrics -.sp -To enable this returner the minion will need the AppOptics Metrics -client importable on the Python path and the following -values configured in the minion or master config. -.sp -The AppOptics python client can be found at: -.sp -\fI\%https://github.com/appoptics/python\-appoptics\-metrics\fP -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -appoptics.api_token: abc12345def -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -An example configuration that returns the total number of successes -and failures for your salt highstate runs (the default) would look -like this: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -return: appoptics -appoptics.api_token: -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The returner publishes the following metrics to AppOptics: -.INDENT 0.0 -.IP \(bu 2 -saltstack.failed -.IP \(bu 2 -saltstack.passed -.IP \(bu 2 -saltstack.retcode -.IP \(bu 2 -saltstack.runtime -.IP \(bu 2 -saltstack.total -.UNINDENT -.sp -You can add a tags section to specify which tags should be attached to -all metrics created by the returner. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -appoptics.tags: - host_hostname_alias: - tier: - cluster: -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If no tags are explicitly configured, then the tag key \fBhost_hostname_alias\fP -will be set, with the minion\(aqs \fBid\fP grain being the value. -.sp -In addition to the requested tags, for a highstate run each of these -will be tagged with the \fBkey:value\fP of \fBstate_type: highstate\fP\&. -.sp -In order to return metrics for \fBstate.sls\fP runs (distinct from highstates), you can -specify a list of state names to the key \fBappoptics.sls_states\fP like so: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -appoptics.sls_states: - \- role_salt_master.netapi - \- role_redis.config - \- role_smarty.dummy -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This will report success and failure counts on runs of the -\fBrole_salt_master.netapi\fP, \fBrole_redis.config\fP, and -\fBrole_smarty.dummy\fP states in addition to highstates. -.sp -This will report the same metrics as above, but for these runs the -metrics will be tagged with \fBstate_type: sls\fP and \fBstate_name\fP set to -the name of the state that was invoked, e.g. \fBrole_salt_master.netapi\fP\&. -.INDENT 0.0 -.TP -.B salt.returners.appoptics_return.returner(ret) -Parse the return data and return metrics to AppOptics. -.sp -For each state that\(aqs provided in the configuration, return tagged metrics for -the result of that state if it\(aqs present. -.UNINDENT -.SS salt.returners.carbon_return -.sp -Take data from salt and \(dqreturn\(dq it into a carbon receiver -.sp -Add the following configuration to the minion configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -carbon.host: -carbon.port: 2003 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Errors when trying to convert data to numbers may be ignored by setting -\fBcarbon.skip_on_error\fP to \fITrue\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -carbon.skip_on_error: True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -By default, data will be sent to carbon using the plaintext protocol. To use -the pickle protocol, set \fBcarbon.mode\fP to \fBpickle\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -carbon.mode: pickle -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B You can also specify the pattern used for the metric base path (except for virt modules metrics): -carbon.metric_base_pattern: carbon.[minion_id].[module].[function] -.TP -.B These tokens can used : -[module]: salt module -[function]: salt function -[minion_id]: minion id -.TP -.B Default is : -carbon.metric_base_pattern: [module].[function].[minion_id] -.UNINDENT -.sp -Carbon settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -carbon: - host: - port: - skip_on_error: True - mode: (pickle|text) - metric_base_pattern: | [module].[function].[minion_id] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.carbon: - host: - port: - skip_on_error: True - mode: (pickle|text) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the carbon returner, append \(aq\-\-return carbon\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return carbon -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return carbon \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return carbon \-\-return_kwargs \(aq{\(dqskip_on_error\(dq: False}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.carbon_return.event_return(events) -Return event data to remote carbon server -.sp -Provide a list of events to be stored in carbon -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.carbon_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.carbon_return.returner(ret) -Return data to a remote carbon server using the text metric protocol -.sp -Each metric will look like: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -[module].[function].[minion_id].[metric path [...]].[metric name] -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.returners.cassandra_cql_return -.sp -Return data to a cassandra server -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.TP -.B maintainer -Corin Kochenower<\fI\%ckochenower@saltstack.com\fP> -.TP -.B maturity -new as of 2015.2 -.TP -.B depends -salt.modules.cassandra_cql -.TP -.B depends -DataStax Python Driver for Apache Cassandra -\fI\%https://github.com/datastax/python\-driver\fP -pip install cassandra\-driver -.TP -.B platform -all -.TP -.B configuration -To enable this returner, the minion will need the DataStax Python Driver -for Apache Cassandra ( \fI\%https://github.com/datastax/python\-driver\fP ) -installed and the following values configured in the minion or master -config. The list of cluster IPs must include at least one cassandra node -IP address. No assumption or default will be used for the cluster IPs. -The cluster IPs will be tried in the order listed. The port, username, -and password values shown below will be the assumed defaults if you do -not provide values.: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -cassandra: - cluster: - \- 192.168.50.11 - \- 192.168.50.12 - \- 192.168.50.13 - port: 9042 - username: salt - password: salt -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Use the following cassandra database schema: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -CREATE KEYSPACE IF NOT EXISTS salt - WITH replication = {\(aqclass\(aq: \(aqSimpleStrategy\(aq, \(aqreplication_factor\(aq : 1}; - -CREATE USER IF NOT EXISTS salt WITH PASSWORD \(aqsalt\(aq NOSUPERUSER; - -GRANT ALL ON KEYSPACE salt TO salt; - -USE salt; - -CREATE TABLE IF NOT EXISTS salt.salt_returns ( - jid text, - minion_id text, - fun text, - alter_time timestamp, - full_ret text, - return text, - success boolean, - PRIMARY KEY (jid, minion_id, fun) -) WITH CLUSTERING ORDER BY (minion_id ASC, fun ASC); -CREATE INDEX IF NOT EXISTS salt_returns_minion_id ON salt.salt_returns (minion_id); -CREATE INDEX IF NOT EXISTS salt_returns_fun ON salt.salt_returns (fun); - -CREATE TABLE IF NOT EXISTS salt.jids ( - jid text PRIMARY KEY, - load text -); - -CREATE TABLE IF NOT EXISTS salt.minions ( - minion_id text PRIMARY KEY, - last_fun text -); -CREATE INDEX IF NOT EXISTS minions_last_fun ON salt.minions (last_fun); - -CREATE TABLE IF NOT EXISTS salt.salt_events ( - id timeuuid, - tag text, - alter_time timestamp, - data text, - master_id text, - PRIMARY KEY (id, tag) -) WITH CLUSTERING ORDER BY (tag ASC); -CREATE INDEX tag ON salt.salt_events (tag); -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Required python modules: cassandra\-driver -.sp -To use the cassandra returner, append \(aq\-\-return cassandra_cql\(aq to the salt command. ex: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return_cql cassandra -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Note: if your Cassandra instance has not been tuned much you may benefit from -altering some timeouts in \fIcassandra.yaml\fP like so: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# How long the coordinator should wait for read operations to complete -read_request_timeout_in_ms: 5000 -# How long the coordinator should wait for seq or index scans to complete -range_request_timeout_in_ms: 20000 -# How long the coordinator should wait for writes to complete -write_request_timeout_in_ms: 20000 -# How long the coordinator should wait for counter writes to complete -counter_write_request_timeout_in_ms: 10000 -# How long a coordinator should continue to retry a CAS operation -# that contends with other proposals for the same row -cas_contention_timeout_in_ms: 5000 -# How long the coordinator should wait for truncates to complete -# (This can be much longer, because unless auto_snapshot is disabled -# we need to flush first so we can snapshot before removing the data.) -truncate_request_timeout_in_ms: 60000 -# The default timeout for other, miscellaneous operations -request_timeout_in_ms: 20000 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -As always, your mileage may vary and your Cassandra cluster may have different -needs. SaltStack has seen situations where these timeouts can resolve -some stacktraces that appear to come from the Datastax Python driver. -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.event_return(events) -Return event to one of potentially many clustered cassandra nodes -.sp -Requires that configuration be enabled via \(aqevent_return\(aq -option in master config. -.sp -Cassandra does not support an auto\-increment feature due to the -highly inefficient nature of creating a monotonically increasing -number across all nodes in a distributed database. Each event -will be assigned a uuid by the connecting client. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.prep_jid(nocache, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.returner(ret) -Return data to one of potentially many clustered cassandra nodes -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.save_load(jid, load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_cql_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.cassandra_return -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fIcassandra\fP returner is deprecated in favor of the \fIcassandra_cql\fP -returner. -.UNINDENT -.UNINDENT -.sp -Return data to a Cassandra ColumnFamily -.sp -Here\(aqs an example Keyspace / ColumnFamily setup that works with this -returner: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -create keyspace salt; -use salt; -create column family returns - with key_validation_class=\(aqUTF8Type\(aq - and comparator=\(aqUTF8Type\(aq - and default_validation_class=\(aqUTF8Type\(aq; -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Required python modules: pycassa -.INDENT 0.0 -.INDENT 3.5 -To use the cassandra returner, append \(aq\-\-return cassandra\(aq to the salt command. ex: -.INDENT 0.0 -.INDENT 3.5 -salt \(aq*\(aq test.ping \-\-return cassandra -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.cassandra_return.returner(ret) -Return data to a Cassandra ColumnFamily -.UNINDENT -.SS salt.returners.couchbase_return -.sp -Simple returner for Couchbase. Optional configuration -settings are listed below, along with sane defaults. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -couchbase.host: \(aqsalt\(aq -couchbase.port: 8091 -couchbase.bucket: \(aqsalt\(aq -couchbase.ttl: 86400 -couchbase.password: \(aqpassword\(aq -couchbase.skip_verify_views: False -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the couchbase returner, append \(aq\-\-return couchbase\(aq to the salt command. ex: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchbase -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_kwargs \(aq{\(dqbucket\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -All of the return data will be stored in documents as follows: -.SS JID -.sp -load: load obj -tgt_minions: list of minions targeted -nocache: should we not cache the return data -.SS JID/MINION_ID -.sp -return: return_data -full_ret: full load of job return -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.prep_jid(nocache=False, passed_jid=None) -Return a job id and prepare the job id directory -This is the function responsible for making sure jids don\(aqt collide (unless -its passed a jid) -So do what you have to do to make sure that stays the case -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.returner(load) -Return data to couchbase bucket -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.save_load(jid, clear_load, minion=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchbase_return.save_minions(jid, minions, syndic_id=None) -Save/update the minion list for a given jid. The syndic_id argument is -included for API compatibility only. -.UNINDENT -.SS salt.returners.couchdb_return -.sp -Simple returner for CouchDB. Optional configuration -settings are listed below, along with sane defaults: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -couchdb.db: \(aqsalt\(aq -couchdb.url: \(aqhttp://salt:5984/\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.couchdb.db: \(aqsalt\(aq -alternative.couchdb.url: \(aqhttp://salt:5984/\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the couchdb returner, append \fB\-\-return couchdb\fP to the salt command. Example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchdb -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \fB\-\-return_config alternative\fP to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS On concurrent database access -.sp -As this returner creates a couchdb document with the salt job id as document id -and as only one document with a given id can exist in a given couchdb database, -it is advised for most setups that every minion be configured to write to it own -database (the value of \fBcouchdb.db\fP may be suffixed with the minion id), -otherwise multi\-minion targeting can lead to losing output: -.INDENT 0.0 -.IP \(bu 2 -the first returning minion is able to create a document in the database -.IP \(bu 2 -other minions fail with \fB{\(aqerror\(aq: \(aqHTTP Error 409: Conflict\(aq}\fP -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.ensure_views() -This function makes sure that all the views that should -exist in the design document do exist. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.get_fun(fun) -Return a dict with key being minion and value -being the job details of the last run of function \(aqfun\(aq. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.get_jid(jid) -Get the document with a given JID. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.get_jids() -List all the jobs that we have.. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.get_minions() -Return a list of minion identifiers from a request of the view. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.get_valid_salt_views() -Returns a dict object of views that should be -part of the salt design document. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.returner(ret) -Take in the return and shove it into the couchdb database. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.couchdb_return.set_salt_view() -Helper function that sets the salt design -document. Uses get_valid_salt_views and some hardcoded values. -.UNINDENT -.SS salt.returners.django_return -.sp -Deprecated since version 3006.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This module has been deprecated and will be removed after January 2024. -.UNINDENT -.UNINDENT -.sp -A returner that will inform a Django system that -returns are available using Django\(aqs signal system. -.sp -\fI\%https://docs.djangoproject.com/en/dev/topics/signals/\fP -.sp -It is up to the Django developer to register necessary -handlers with the signals provided by this returner -and process returns as necessary. -.sp -The easiest way to use signals is to import them from -this returner directly and then use a decorator to register -them. -.sp -An example Django module that registers a function called -\(aqreturner_callback\(aq with this module\(aqs \(aqreturner\(aq function: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -import salt.returners.django_return -from django.dispatch import receiver - -@receiver(salt.returners.django_return, sender=returner) -def returner_callback(sender, ret): - print(\(aqI received {0} from {1}\(aq.format(ret, sender)) -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.django_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom ID -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.django_return.returner(ret) -Signal a Django server that a return is available -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.django_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.SS salt.returners.elasticsearch_return -.sp -Return data to an elasticsearch server for indexing. -.INDENT 0.0 -.TP -.B maintainer -Jurnell Cockhren <\fI\%jurnell.cockhren@sophicware.com\fP>, Arnold Bechtoldt <\fI\%mail@arnoldbechtoldt.com\fP> -.TP -.B maturity -New -.TP -.B depends -\fI\%elasticsearch\-py\fP -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner the elasticsearch python client must be installed -on the desired minions (all or some subset). -.sp -Please see documentation of \fI\%elasticsearch execution module\fP -for a valid connection configuration. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -The index that you wish to store documents will be created by Elasticsearch automatically if -doesn\(aqt exist yet. It is highly recommended to create predefined index templates with appropriate mapping(s) -that will be used by Elasticsearch upon index creation. Otherwise you will have problems as described in #20826. -.UNINDENT -.UNINDENT -.sp -To use the returner per salt call: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return elasticsearch -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -In order to have the returner apply to all minions: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ext_job_cache: elasticsearch -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B Minion configuration: -.INDENT 7.0 -.TP -.B debug_returner_payload\(aq: False -Output the payload being posted to the log file in debug mode -.TP -.B doc_type: \(aqdefault\(aq -Document type to use for normal return messages -.TP -.B functions_blacklist -Optional list of functions that should not be returned to elasticsearch -.TP -.B index_date: False -Use a dated index (e.g. \-2016.11.29) -.TP -.B master_event_index: \(aqsalt\-master\-event\-cache\(aq -Index to use when returning master events -.TP -.B master_event_doc_type: \(aqefault\(aq -Document type to use got master events -.TP -.B master_job_cache_index: \(aqsalt\-master\-job\-cache\(aq -Index to use for master job cache -.TP -.B master_job_cache_doc_type: \(aqdefault\(aq -Document type to use for master job cache -.TP -.B number_of_shards: 1 -Number of shards to use for the indexes -.TP -.B number_of_replicas: 0 -Number of replicas to use for the indexes -.UNINDENT -.sp -NOTE: The following options are valid for \(aqstate.apply\(aq, \(aqstate.sls\(aq and \(aqstate.highstate\(aq functions only. -.INDENT 7.0 -.TP -.B states_count: False -Count the number of states which succeeded or failed and return it in top\-level item called \(aqcounts\(aq. -States reporting None (i.e. changes would be made but it ran in test mode) are counted as successes. -.TP -.B states_order_output: False -Prefix the state UID (e.g. file_|\-yum_configured_|\-/etc/yum.conf_|\-managed) with a zero\-padded version -of the \(aq__run_num__\(aq value to allow for easier sorting. Also store the state function (i.e. file.managed) -into a new key \(aq_func\(aq. Change the index to be \(aq\-ordered\(aq (e.g. salt\-state_apply\-ordered). -.TP -.B states_single_index: False -Store results for state.apply, state.sls and state.highstate in the salt\-state_apply index -(or \-ordered/\-) indexes if enabled -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -elasticsearch: - hosts: - \- \(dq10.10.10.10:9200\(dq - \- \(dq10.10.10.11:9200\(dq - \- \(dq10.10.10.12:9200\(dq - index_date: True - number_of_shards: 5 - number_of_replicas: 1 - debug_returner_payload: True - states_count: True - states_order_output: True - states_single_index: True - functions_blacklist: - \- test.ping - \- saltutil.find_job -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.elasticsearch_return.event_return(events) -Return events to Elasticsearch -.sp -Requires that the \fIevent_return\fP configuration be set in master config. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.elasticsearch_return.get_load(jid) -Return the load data that marks a specified jid -.sp -New in version 2015.8.1. - -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.elasticsearch_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.elasticsearch_return.returner(ret) -Process the return from Salt -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.elasticsearch_return.save_load(jid, load, minions=None) -Save the load to the specified jid id -.sp -New in version 2015.8.1. - -.UNINDENT -.SS salt.returners.etcd_return -.sp -Return data to an etcd server or cluster -.INDENT 0.0 -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -python\-etcd or etcd3\-py -.UNINDENT -.UNINDENT -.sp -In order to return to an etcd server, a profile should be created in the master -configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my_etcd_config: - etcd.host: 127.0.0.1 - etcd.port: 2379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -It is technically possible to configure etcd without using a profile, but this -is not considered to be a best practice, especially when multiple etcd servers -or clusters are available. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.host: 127.0.0.1 -etcd.port: 2379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -In order to choose whether to use etcd API v2 or v3, you can put the following -configuration option in the same place as your etcd configuration. This option -defaults to true, meaning you will use v2 unless you specify otherwise. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.require_v2: True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -When using API v3, there are some specific options available to be configured -within your etcd profile. They are defaulted to the following... -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.encode_keys: False -etcd.encode_values: True -etcd.raw_keys: False -etcd.raw_values: False -etcd.unicode_errors: \(dqsurrogateescape\(dq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before -adding them to etcd. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. -This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. -This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have -differing byte prefixes, and etcd v3 searches recursively using prefixes. -.UNINDENT -.UNINDENT -.sp -\fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before -adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. -.sp -\fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. -.sp -\fBetcd.raw_values\fP determines whether you want the raw value or a string returned. -.sp -\fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. -.sp -Additionally, two more options must be specified in the top\-level configuration -in order to use the etcd returner: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.returner: my_etcd_config -etcd.returner_root: /salt/return -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The \fBetcd.returner\fP option specifies which configuration profile to use. The -\fBetcd.returner_root\fP option specifies the path inside etcd to use as the root -of the returner system. -.sp -Once the etcd options are configured, the returner may be used: -.sp -CLI Example: -.INDENT 0.0 -.INDENT 3.5 -salt \(aq*\(aq test.ping \-\-return etcd -.UNINDENT -.UNINDENT -.sp -A username and password can be set: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.username: larry # Optional; requires etcd.password to be set -etcd.password: 123pass # Optional; requires etcd.username to be set -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -You can also set a TTL (time to live) value for the returner: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.ttl: 5 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Authentication with username and password, and ttl, currently requires the -\fBmaster\fP branch of \fBpython\-etcd\fP\&. -.sp -You may also specify different roles for read and write operations. First, -create the profiles as specified above. Then add: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -etcd.returner_read_profile: my_etcd_read -etcd.returner_write_profile: my_etcd_write -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.clean_old_jobs() -Included for API consistency -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.returner(ret) -Return data to an etcd server or cluster -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.etcd_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.highstate_return -.sp -Return the results of a highstate (or any other state function that returns -data in a compatible format) via an HTML email or HTML file. -.sp -New in version 2017.7.0. - -.sp -Similar results can be achieved by using the smtp returner with a custom template, -except an attempt at writing such a template for the complex data structure -returned by highstate function had proven to be a challenge, not to mention -that the smtp module doesn\(aqt support sending HTML mail at the moment. -.sp -The main goal of this returner was to produce an easy to read email similar -to the output of highstate outputter used by the CLI. -.sp -This returner could be very useful during scheduled executions, -but could also be useful for communicating the results of a manual execution. -.sp -Returner configuration is controlled in a standard fashion either via -highstate group or an alternatively named group. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.highstate \-\-return highstate -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config config\-name\(aq -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq state.highstate \-\-return highstate \-\-return_config simple -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Here is an example of what the configuration might look like: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -simple.highstate: - report_failures: True - report_changes: True - report_everything: False - failure_function: pillar.items - success_function: pillar.items - report_format: html - report_delivery: smtp - smtp_success_subject: \(aqsuccess minion {id} on host {host}\(aq - smtp_failure_subject: \(aqfailure minion {id} on host {host}\(aq - smtp_server: smtp.example.com - smtp_recipients: saltusers@example.com, devops@example.com - smtp_sender: salt@example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The \fIreport_failures\fP, \fIreport_changes\fP, and \fIreport_everything\fP flags provide -filtering of the results. If you want an email to be sent every time, then -\fIreport_everything\fP is your choice. If you want to be notified only when -changes were successfully made use \fIreport_changes\fP\&. And \fIreport_failures\fP will -generate an email if there were failures. -.sp -The configuration allows you to run a salt module function in case of -success (\fIsuccess_function\fP) or failure (\fIfailure_function\fP). -.sp -Any salt function, including ones defined in the _module folder of your salt -repo, could be used here and its output will be displayed under the \(aqextra\(aq -heading of the email. -.sp -Supported values for \fIreport_format\fP are html, json, and yaml. The latter two -are typically used for debugging purposes, but could be used for applying -a template at some later stage. -.sp -The values for \fIreport_delivery\fP are smtp or file. In case of file delivery -the only other applicable option is \fIfile_output\fP\&. -.sp -In case of smtp delivery, smtp_* options demonstrated by the example above -could be used to customize the email. -.sp -As you might have noticed, the success and failure subjects contain {id} and {host} -values. Any other grain name could be used. As opposed to using -{{grains[\(aqid\(aq]}}, which will be rendered by the master and contain master\(aqs -values at the time of pillar generation, these will contain minion values at -the time of execution. -.INDENT 0.0 -.TP -.B salt.returners.highstate_return.returner(ret) -Check highstate return information and possibly fire off an email -or save a file. -.UNINDENT -.SS salt.returners.influxdb_return -.sp -Return data to an influxdb server. -.sp -New in version 2015.8.0. - -.sp -To enable this returner the minion will need the python client for influxdb -installed and the following values configured in the minion or master -config, these are the defaults: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -influxdb.db: \(aqsalt\(aq -influxdb.user: \(aqsalt\(aq -influxdb.password: \(aqsalt\(aq -influxdb.host: \(aqlocalhost\(aq -influxdb.port: 8086 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.influxdb.db: \(aqsalt\(aq -alternative.influxdb.user: \(aqsalt\(aq -alternative.influxdb.password: \(aqsalt\(aq -alternative.influxdb.host: \(aqlocalhost\(aq -alternative.influxdb.port: 6379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the influxdb returner, append \(aq\-\-return influxdb\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return influxdb -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.returner(ret) -Return data to a influxdb data store -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.influxdb_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.kafka_return -.sp -Return data to a Kafka topic -.INDENT 0.0 -.TP -.B maintainer -Justin Desilets (\fI\%justin.desilets@gmail.com\fP) -.TP -.B maturity -20181119 -.TP -.B depends -confluent\-kafka -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner install confluent\-kafka and enable the following -settings in the minion config: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.TP -.B returner.kafka.bootstrap: -.INDENT 7.0 -.IP \(bu 2 -\(dqserver1:9092\(dq -.IP \(bu 2 -\(dqserver2:9092\(dq -.IP \(bu 2 -\(dqserver3:9092\(dq -.UNINDENT -.UNINDENT -.sp -returner.kafka.topic: \(aqtopic\(aq -.UNINDENT -.UNINDENT -.sp -To use the kafka returner, append \fI\-\-return kafka\fP to the Salt command, eg; -.INDENT 0.0 -.INDENT 3.5 -salt \(aq*\(aq test.ping \-\-return kafka -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.kafka_return.returner(ret) -Return information to a Kafka server -.UNINDENT -.SS salt.returners.librato_return -.sp -Salt returner to return highstate stats to Librato -.sp -To enable this returner the minion will need the Librato -client importable on the Python path and the following -values configured in the minion or master config. -.sp -The Librato python client can be found at: -\fI\%https://github.com/librato/python\-librato\fP -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -librato.email: example@librato.com -librato.api_token: abc12345def -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This return supports multi\-dimension metrics for Librato. To enable -support for more metrics, the tags JSON object can be modified to include -other tags. -.sp -Adding EC2 Tags example: -If ec2_tags:region were desired within the tags for multi\-dimension. The tags -could be modified to include the ec2 tags. Multiple dimensions are added simply -by adding more tags to the submission. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pillar_data = __salt__[\(aqpillar.raw\(aq]() -q.add(metric.name, value, tags={\(aqName\(aq: ret[\(aqid\(aq],\(aqRegion\(aq: pillar_data[\(aqec2_tags\(aq][\(aqName\(aq]}) -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.librato_return.returner(ret) -Parse the return data and return metrics to Librato. -.UNINDENT -.SS salt.returners.local -.sp -The local returner is used to test the returner interface, it just prints the -return data to the console to verify that it is being passed properly -.sp -To use the local returner, append \(aq\-\-return local\(aq to the salt command. ex: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return local -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local.event_return(event) -Print event return data to the terminal to verify functionality -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local.returner(ret) -Print the return data to the terminal to verify functionality -.UNINDENT -.SS salt.returners.local_cache -.sp -Return data to local job cache -.INDENT 0.0 -.TP -.B salt.returners.local_cache.clean_old_jobs() -Clean out the old jobs from the job cache -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.get_endtime(jid) -Retrieve the stored endtime for a given job -.sp -Returns False if no endtime is present -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.get_jids() -Return a dict mapping all job ids to job information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.get_jids_filter(count, filter_find_job=True) -Return a list of all jobs information filtered by the given criteria. -:param int count: show not more than the count of most recent jobs -:param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.load_reg() -Load the register from msgpack files -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.prep_jid(nocache=False, passed_jid=None, recurse_count=0) -Return a job id and prepare the job id directory. -.sp -This is the function responsible for making sure jids don\(aqt collide (unless -it is passed a jid). -So do what you have to do to make sure that stays the case -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.returner(load) -Return data to the local job cache -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.save_load(jid, clear_load, minions=None, recurse_count=0) -Save the load to the specified jid -.sp -minions argument is to provide a pre\-computed list of matched minions for -the job, for cases when this function can\(aqt compute that list itself (such -as for salt\-ssh) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.save_minions(jid, minions, syndic_id=None) -Save/update the serialized list of minions for a given job -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.save_reg(data) -Save the register to msgpack files -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.local_cache.update_endtime(jid, time) -Update (or store) the end time for a given job -.sp -Endtime is stored as a plain text string -.UNINDENT -.SS salt.returners.mattermost_returner -.sp -Return salt data via mattermost -.sp -New in version 2017.7.0. - -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mattermost.hook (required) -mattermost.username (optional) -mattermost.channel (optional) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mattermost.channel -mattermost.hook -mattermost.username -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -mattermost settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mattermost: - channel: RoomName - hook: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - username: user -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the mattermost returner, append \(aq\-\-return mattermost\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mattermost -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(aqkey:\(aq: \(aqvalue\(aq}\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mattermost \-\-return_kwargs \(aq{\(aqchannel\(aq: \(aq#random\(aq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mattermost_returner.event_return(events) -Send the events to a mattermost room. -.INDENT 7.0 -.TP -.B Parameters -\fBevents\fP \-\- List of events -.TP -.B Returns -Boolean if messages were sent successfully. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mattermost_returner.post_message(channel, message, username, api_url, hook) -Send a message to a mattermost room. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBchannel\fP \-\- The room name. -.IP \(bu 2 -\fBmessage\fP \-\- The message to send to the mattermost room. -.IP \(bu 2 -\fBusername\fP \-\- Specify who the message is from. -.IP \(bu 2 -\fBhook\fP \-\- The mattermost hook, if not specified in the configuration. -.UNINDENT -.TP -.B Returns -Boolean if message was sent successfully. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mattermost_returner.returner(ret) -Send an mattermost message with the data -.UNINDENT -.SS salt.returners.memcache_return -.sp -Return data to a memcache server -.sp -To enable this returner the minion will need the python client for memcache -installed and the following values configured in the minion or master -config, these are the defaults. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -memcache.host: \(aqlocalhost\(aq -memcache.port: \(aq11211\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.memcache.host: \(aqlocalhost\(aq -alternative.memcache.port: \(aq11211\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -python2\-memcache uses \(aqlocalhost\(aq and \(aq11211\(aq as syntax on connection. -.sp -To use the memcache returner, append \(aq\-\-return memcache\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return memcache -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return memcache \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return memcache \-\-return_kwargs \(aq{\(dqhost\(dq: \(dqhostname.domain.com\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.returner(ret) -Return data to a memcache data store -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.memcache_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.mongo_future_return -.sp -Return data to a mongodb server -.sp -Required python modules: pymongo -.sp -This returner will send data from the minions to a MongoDB server. MongoDB -server can be configured by using host, port, db, user and password settings -or by connection string URI (for pymongo > 2.3). To configure the settings -for your MongoDB server, add the following lines to the minion config files: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongo.db: -mongo.host: -mongo.user: -mongo.password: -mongo.port: 27017 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Or single URI: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongo.uri: URI -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -where uri is in the format: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongodb://db1.example.net:27017/mydatabase -mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test -mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -More information on URI format can be found in -\fI\%https://docs.mongodb.com/manual/reference/connection\-string/\fP -.sp -You can also ask for indexes creation on the most common used fields, which -should greatly improve performance. Indexes are not created by default. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongo.indexes: true -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.mongo.db: -alternative.mongo.host: -alternative.mongo.user: -alternative.mongo.password: -alternative.mongo.port: 27017 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Or single URI: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.mongo.uri: URI -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This mongo returner is being developed to replace the default mongodb returner -in the future and should not be considered API stable yet. -.sp -To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.event_return(events) -Return events to Mongodb server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.get_fun(fun) -Return the most recent jobs that have executed the named function -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.get_jid(jid) -Return the return information associated with a jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.get_jids() -Return a list of job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.get_load(jid) -Return the load associated with a given job id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.returner(ret) -Return data to a mongodb server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.save_load(jid, load, minions=None) -Save the load for a given job id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_future_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.mongo_return -.sp -Return data to a mongodb server -.sp -Required python modules: pymongo -.sp -This returner will send data from the minions to a MongoDB server. To -configure the settings for your MongoDB server, add the following lines -to the minion config files. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mongo.db: -mongo.host: -mongo.user: -mongo.password: -mongo.port: 27017 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.mongo.db: -alternative.mongo.host: -alternative.mongo.user: -alternative.mongo.password: -alternative.mongo.port: 27017 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo_return -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo_return \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_return.get_fun(fun) -Return the most recent jobs that have executed the named function -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_return.get_jid(jid) -Return the return information associated with a jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_return.returner(ret) -Return data to a mongodb server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mongo_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.multi_returner -.sp -Read/Write multiple returners -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.clean_old_jobs() -Clean out the old jobs from all returners (if you have it) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.get_jid(jid) -Merge the return data from all returners -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.get_jids() -Return all job data from all returners -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.get_load(jid) -Merge the load data from all returners -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.prep_jid(nocache=False, passed_jid=None) -Call both with prep_jid on all returners in multi_returner -.sp -TODO: finish this, what do do when you get different jids from 2 returners... -since our jids are time based, this make this problem hard, because they -aren\(aqt unique, meaning that we have to make sure that no one else got the jid -and if they did we spin to get a new one, which means \(dqlocking\(dq the jid in 2 -returners is non\-trivial -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.returner(load) -Write return to all returners in multi_returner -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.save_load(jid, clear_load, minions=None) -Write load to all returners in multi_returner -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.multi_returner.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.mysql -.sp -Return data to a mysql server -.INDENT 0.0 -.TP -.B maintainer -Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP> -.TP -.B maturity -mature -.TP -.B depends -python\-mysqldb -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner, the minion will need the python client for mysql -installed and the following values configured in the minion or master -config. These are the defaults: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mysql.host: \(aqsalt\(aq -mysql.user: \(aqsalt\(aq -mysql.pass: \(aqsalt\(aq -mysql.db: \(aqsalt\(aq -mysql.port: 3306 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -SSL is optional. The defaults are set to None. If you do not want to use SSL, -either exclude these options or set them to None. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mysql.ssl_ca: None -mysql.ssl_cert: None -mysql.ssl_key: None -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration -with \fIalternative.\fP\&. Any values not found in the alternative configuration will -be pulled from the default location. As stated above, SSL configuration is -optional. The following ssl options are simply for illustration purposes: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.mysql.host: \(aqsalt\(aq -alternative.mysql.user: \(aqsalt\(aq -alternative.mysql.pass: \(aqsalt\(aq -alternative.mysql.db: \(aqsalt\(aq -alternative.mysql.port: 3306 -alternative.mysql.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq -alternative.mysql.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq -alternative.mysql.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Should you wish the returner data to be cleaned out every so often, set -\fIkeep_jobs_seconds\fP to the number of hours for the jobs to live in the -tables. Setting it to \fI0\fP will cause the data to stay in the tables. The -default setting for \fIkeep_jobs_seconds\fP is set to \fI86400\fP\&. -.sp -Should you wish to archive jobs in a different table for later processing, -set \fIarchive_jobs\fP to True. Salt will create 3 archive tables -.INDENT 0.0 -.IP \(bu 2 -\fIjids_archive\fP -.IP \(bu 2 -\fIsalt_returns_archive\fP -.IP \(bu 2 -\fIsalt_events_archive\fP -.UNINDENT -.sp -and move the contents of \fIjids\fP, \fIsalt_returns\fP, and \fIsalt_events\fP that are -more than \fIkeep_jobs_seconds\fP seconds old to these tables. -.sp -Use the following mysql database schema: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -CREATE DATABASE \(gasalt\(ga - DEFAULT CHARACTER SET utf8 - DEFAULT COLLATE utf8_general_ci; - -USE \(gasalt\(ga; - -\-\- -\-\- Table structure for table \(gajids\(ga -\-\- - -DROP TABLE IF EXISTS \(gajids\(ga; -CREATE TABLE \(gajids\(ga ( - \(gajid\(ga varchar(255) NOT NULL, - \(gaload\(ga mediumtext NOT NULL, - UNIQUE KEY \(gajid\(ga (\(gajid\(ga) -) ENGINE=InnoDB DEFAULT CHARSET=utf8; - -\-\- -\-\- Table structure for table \(gasalt_returns\(ga -\-\- - -DROP TABLE IF EXISTS \(gasalt_returns\(ga; -CREATE TABLE \(gasalt_returns\(ga ( - \(gafun\(ga varchar(50) NOT NULL, - \(gajid\(ga varchar(255) NOT NULL, - \(gareturn\(ga mediumtext NOT NULL, - \(gaid\(ga varchar(255) NOT NULL, - \(gasuccess\(ga varchar(10) NOT NULL, - \(gafull_ret\(ga mediumtext NOT NULL, - \(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - KEY \(gaid\(ga (\(gaid\(ga), - KEY \(gajid\(ga (\(gajid\(ga), - KEY \(gafun\(ga (\(gafun\(ga) -) ENGINE=InnoDB DEFAULT CHARSET=utf8; - -\-\- -\-\- Table structure for table \(gasalt_events\(ga -\-\- - -DROP TABLE IF EXISTS \(gasalt_events\(ga; -CREATE TABLE \(gasalt_events\(ga ( -\(gaid\(ga BIGINT NOT NULL AUTO_INCREMENT, -\(gatag\(ga varchar(255) NOT NULL, -\(gadata\(ga mediumtext NOT NULL, -\(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -\(gamaster_id\(ga varchar(255) NOT NULL, -PRIMARY KEY (\(gaid\(ga), -KEY \(gatag\(ga (\(gatag\(ga) -) ENGINE=InnoDB DEFAULT CHARSET=utf8; -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Required python modules: MySQLdb -.sp -To use the mysql returner, append \(aq\-\-return mysql\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mysql -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mysql \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return mysql \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.clean_old_jobs() -Called in the master\(aqs event loop every loop_interval. Archives and/or -deletes the events and job details from the database. -:return: -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.event_return(events) -Return event to mysql server -.sp -Requires that configuration be enabled via \(aqevent_return\(aq -option in master config. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_jids_filter(count, filter_find_job=True) -Return a list of all job ids -:param int count: show not more than the count of most recent jobs -:param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.returner(ret) -Return data to a mysql server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.save_load(jid, load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.mysql.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.nagios_nrdp_return -.sp -Return salt data to Nagios -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -nagios.url (required) -nagios.token (required) -nagios.service (optional) -nagios.check_type (optional) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -nagios.url -nagios.token -nagios.service -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Nagios settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C - nagios: - url: http://localhost/nrdp - token: r4nd0mt0k3n - service: service\-check - - alternative.nagios: - url: http://localhost/nrdp - token: r4nd0mt0k3n - service: another\-service\-check - -To use the Nagios returner, append \(aq\-\-return nagios\(aq to the salt command. ex: - -\&.. code\-block:: bash - - salt \(aq*\(aq test.ping \-\-return nagios - -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: - - salt \(aq*\(aq test.ping \-\-return nagios \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return nagios \-\-return_kwargs \(aq{\(dqservice\(dq: \(dqservice\-name\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.nagios_nrdp_return.returner(ret) -Send a message to Nagios with the data -.UNINDENT -.SS salt.returners.odbc -.sp -Return data to an ODBC compliant server. This driver was -developed with Microsoft SQL Server in mind, but theoretically -could be used to return data to any compliant ODBC database -as long as there is a working ODBC driver for it on your -minion platform. -.INDENT 0.0 -.TP -.B maintainer -.INDENT 7.0 -.IP C. 3 -.INDENT 3.0 -.IP R. 3 -Oldham (\fI\%cr@saltstack.com\fP) -.UNINDENT -.UNINDENT -.TP -.B maturity -New -.TP -.B depends -unixodbc, pyodbc, freetds (for SQL Server) -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner the minion will need -.sp -On Linux: -.INDENT 0.0 -.INDENT 3.5 -unixodbc (\fI\%http://www.unixodbc.org\fP) -pyodbc (\fIpip install pyodbc\fP) -The FreeTDS ODBC driver for SQL Server (\fI\%http://www.freetds.org\fP) -or another compatible ODBC driver -.UNINDENT -.UNINDENT -.sp -On Windows: -.INDENT 0.0 -.INDENT 3.5 -TBD -.UNINDENT -.UNINDENT -.sp -unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and -/etc/odbc.ini. -.sp -/etc/odbcinst.ini: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[TDS] -Description=TDS -Driver=/usr/lib/x86_64\-linux\-gnu/odbc/libtdsodbc.so -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -(Note the above Driver line needs to point to the location of the FreeTDS -shared library. This example is for Ubuntu 14.04.) -.sp -/etc/odbc.ini: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[TS] -Description = \(dqSalt Returner\(dq -Driver=TDS -Server = -Port = 1433 -Database = salt -Trace = No -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Also you need the following values configured in the minion or master config. -Configure as you see fit: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -returner.odbc.dsn: \(aqTS\(aq -returner.odbc.user: \(aqsalt\(aq -returner.odbc.passwd: \(aqsalt\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.returner.odbc.dsn: \(aqTS\(aq -alternative.returner.odbc.user: \(aqsalt\(aq -alternative.returner.odbc.passwd: \(aqsalt\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Running the following commands against Microsoft SQL Server in the desired -database as the appropriate user should create the database tables -correctly. Replace with equivalent SQL for other ODBC\-compliant servers -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C - \-\- - \-\- Table structure for table \(aqjids\(aq - \-\- - - if OBJECT_ID(\(aqdbo.jids\(aq, \(aqU\(aq) is not null - DROP TABLE dbo.jids - - CREATE TABLE dbo.jids ( - jid varchar(255) PRIMARY KEY, - load varchar(MAX) NOT NULL - ); - - \-\- - \-\- Table structure for table \(aqsalt_returns\(aq - \-\- - IF OBJECT_ID(\(aqdbo.salt_returns\(aq, \(aqU\(aq) IS NOT NULL - DROP TABLE dbo.salt_returns; - - CREATE TABLE dbo.salt_returns ( - added datetime not null default (getdate()), - fun varchar(100) NOT NULL, - jid varchar(255) NOT NULL, - retval varchar(MAX) NOT NULL, - id varchar(255) NOT NULL, - success bit default(0) NOT NULL, - full_ret varchar(MAX) - ); - - CREATE INDEX salt_returns_added on dbo.salt_returns(added); - CREATE INDEX salt_returns_id on dbo.salt_returns(id); - CREATE INDEX salt_returns_jid on dbo.salt_returns(jid); - CREATE INDEX salt_returns_fun on dbo.salt_returns(fun); - -To use this returner, append \(aq\-\-return odbc\(aq to the salt command. - -\&.. code\-block:: bash - - salt \(aq*\(aq status.diskusage \-\-return odbc - -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. - -\&.. versionadded:: 2015.5.0 - -\&.. code\-block:: bash - - salt \(aq*\(aq test.ping \-\-return odbc \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return odbc \-\-return_kwargs \(aq{\(dqdsn\(dq: \(dqdsn\-name\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.returner(ret) -Return data to an odbc server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.save_load(jid, load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.odbc.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.pgjsonb -.sp -Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type -.INDENT 0.0 -.TP -.B maintainer -Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP>, C. R. Oldham <\fI\%cr@saltstack.com\fP> -.TP -.B maturity -Stable -.TP -.B depends -python\-psycopg2 -.TP -.B platform -all -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -There are three PostgreSQL returners. Any can function as an external -\fI\%master job cache\fP\&. but each has different -features. SaltStack recommends -\fI\%returners.pgjsonb\fP if you are working with -a version of PostgreSQL that has the appropriate native binary JSON types. -Otherwise, review -\fI\%returners.postgres\fP and -\fI\%returners.postgres_local_cache\fP -to see which module best suits your particular needs. -.UNINDENT -.UNINDENT -.sp -To enable this returner, the minion will need the python client for PostgreSQL -installed and the following values configured in the minion or master -config. These are the defaults: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -returner.pgjsonb.host: \(aqsalt\(aq -returner.pgjsonb.user: \(aqsalt\(aq -returner.pgjsonb.pass: \(aqsalt\(aq -returner.pgjsonb.db: \(aqsalt\(aq -returner.pgjsonb.port: 5432 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -SSL is optional. The defaults are set to None. If you do not want to use SSL, -either exclude these options or set them to None. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -returner.pgjsonb.sslmode: None -returner.pgjsonb.sslcert: None -returner.pgjsonb.sslkey: None -returner.pgjsonb.sslrootcert: None -returner.pgjsonb.sslcrl: None -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2017.5.0. - -.sp -Alternative configuration values can be used by prefacing the configuration -with \fIalternative.\fP\&. Any values not found in the alternative configuration will -be pulled from the default location. As stated above, SSL configuration is -optional. The following ssl options are simply for illustration purposes: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.pgjsonb.host: \(aqsalt\(aq -alternative.pgjsonb.user: \(aqsalt\(aq -alternative.pgjsonb.pass: \(aqsalt\(aq -alternative.pgjsonb.db: \(aqsalt\(aq -alternative.pgjsonb.port: 5432 -alternative.pgjsonb.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq -alternative.pgjsonb.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq -alternative.pgjsonb.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Should you wish the returner data to be cleaned out every so often, set -\fBkeep_jobs_seconds\fP to the number of seconds for the jobs to live in the tables. -Setting it to \fB0\fP or leaving it unset will cause the data to stay in the tables. -.sp -Should you wish to archive jobs in a different table for later processing, -set \fBarchive_jobs\fP to True. Salt will create 3 archive tables; -.INDENT 0.0 -.IP \(bu 2 -\fBjids_archive\fP -.IP \(bu 2 -\fBsalt_returns_archive\fP -.IP \(bu 2 -\fBsalt_events_archive\fP -.UNINDENT -.sp -and move the contents of \fBjids\fP, \fBsalt_returns\fP, and \fBsalt_events\fP that are -more than \fBkeep_jobs_seconds\fP seconds old to these tables. -.sp -New in version 2019.2.0. - -.sp -Use the following Pg database schema: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -CREATE DATABASE salt - WITH ENCODING \(aqutf\-8\(aq; - -\-\- -\-\- Table structure for table \(gajids\(ga -\-\- -DROP TABLE IF EXISTS jids; -CREATE TABLE jids ( - jid varchar(255) NOT NULL primary key, - load jsonb NOT NULL -); -CREATE INDEX idx_jids_jsonb on jids - USING gin (load) - WITH (fastupdate=on); - -\-\- -\-\- Table structure for table \(gasalt_returns\(ga -\-\- - -DROP TABLE IF EXISTS salt_returns; -CREATE TABLE salt_returns ( - fun varchar(50) NOT NULL, - jid varchar(255) NOT NULL, - return jsonb NOT NULL, - id varchar(255) NOT NULL, - success varchar(10) NOT NULL, - full_ret jsonb NOT NULL, - alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW()); - -CREATE INDEX idx_salt_returns_id ON salt_returns (id); -CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); -CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); -CREATE INDEX idx_salt_returns_return ON salt_returns - USING gin (return) with (fastupdate=on); -CREATE INDEX idx_salt_returns_full_ret ON salt_returns - USING gin (full_ret) with (fastupdate=on); - -\-\- -\-\- Table structure for table \(gasalt_events\(ga -\-\- - -DROP TABLE IF EXISTS salt_events; -DROP SEQUENCE IF EXISTS seq_salt_events_id; -CREATE SEQUENCE seq_salt_events_id; -CREATE TABLE salt_events ( - id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), - tag varchar(255) NOT NULL, - data jsonb NOT NULL, - alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), - master_id varchar(255) NOT NULL); - -CREATE INDEX idx_salt_events_tag on - salt_events (tag); -CREATE INDEX idx_salt_events_data ON salt_events - USING gin (data) with (fastupdate=on); -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Required python modules: Psycopg2 -.sp -To use this returner, append \(aq\-\-return pgjsonb\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return pgjsonb -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.clean_old_jobs() -Called in the master\(aqs event loop every loop_interval. Archives and/or -deletes the events and job details from the database. -:return: -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.event_return(events) -Return event to Pg server -.sp -Requires that configuration be enabled via \(aqevent_return\(aq -option in master config. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.returner(ret) -Return data to a Pg server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.save_load(jid, load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pgjsonb.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.postgres -.sp -Return data to a postgresql server -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -There are three PostgreSQL returners. Any can function as an external -\fI\%master job cache\fP\&. but each has different -features. SaltStack recommends -\fI\%returners.pgjsonb\fP if you are working with -a version of PostgreSQL that has the appropriate native binary JSON types. -Otherwise, review -\fI\%returners.postgres\fP and -\fI\%returners.postgres_local_cache\fP -to see which module best suits your particular needs. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -None -.TP -.B maturity -New -.TP -.B depends -psycopg2 -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner the minion will need the psycopg2 installed and -the following values configured in the minion or master config: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -returner.postgres.host: \(aqsalt\(aq -returner.postgres.user: \(aqsalt\(aq -returner.postgres.passwd: \(aqsalt\(aq -returner.postgres.db: \(aqsalt\(aq -returner.postgres.port: 5432 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.returner.postgres.host: \(aqsalt\(aq -alternative.returner.postgres.user: \(aqsalt\(aq -alternative.returner.postgres.passwd: \(aqsalt\(aq -alternative.returner.postgres.db: \(aqsalt\(aq -alternative.returner.postgres.port: 5432 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Running the following commands as the postgres user should create the database -correctly: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -psql << EOF -CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; -CREATE DATABASE salt WITH OWNER salt; -EOF - -psql \-h localhost \-U salt << EOF -\-\- -\-\- Table structure for table \(aqjids\(aq -\-\- - -DROP TABLE IF EXISTS jids; -CREATE TABLE jids ( - jid varchar(20) PRIMARY KEY, - load text NOT NULL -); - -\-\- -\-\- Table structure for table \(aqsalt_returns\(aq -\-\- - -DROP TABLE IF EXISTS salt_returns; -CREATE TABLE salt_returns ( - fun varchar(50) NOT NULL, - jid varchar(255) NOT NULL, - return text NOT NULL, - full_ret text, - id varchar(255) NOT NULL, - success varchar(10) NOT NULL, - alter_time TIMESTAMP WITH TIME ZONE DEFAULT now() -); - -CREATE INDEX idx_salt_returns_id ON salt_returns (id); -CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); -CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); -CREATE INDEX idx_salt_returns_updated ON salt_returns (alter_time); - -\-\- -\-\- Table structure for table \(gasalt_events\(ga -\-\- - -DROP TABLE IF EXISTS salt_events; -DROP SEQUENCE IF EXISTS seq_salt_events_id; -CREATE SEQUENCE seq_salt_events_id; -CREATE TABLE salt_events ( - id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), - tag varchar(255) NOT NULL, - data text NOT NULL, - alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), - master_id varchar(255) NOT NULL -); - -CREATE INDEX idx_salt_events_tag on salt_events (tag); - -EOF -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Required python modules: psycopg2 -.sp -To use the postgres returner, append \(aq\-\-return postgres\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return postgres -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return postgres \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return postgres \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.event_return(events) -Return event to Pg server -.sp -Requires that configuration be enabled via \(aqevent_return\(aq -option in master config. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.returner(ret) -Return data to a postgres server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.save_load(jid, load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.postgres_local_cache -.sp -Use a postgresql server for the master job cache. This helps the job cache to -cope with scale. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -There are three PostgreSQL returners. Any can function as an external -\fI\%master job cache\fP\&. but each has different -features. SaltStack recommends -\fI\%returners.pgjsonb\fP if you are working with -a version of PostgreSQL that has the appropriate native binary JSON types. -Otherwise, review -\fI\%returners.postgres\fP and -\fI\%returners.postgres_local_cache\fP -to see which module best suits your particular needs. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -\fI\%gjredelinghuys@gmail.com\fP -.TP -.B maturity -Stable -.TP -.B depends -psycopg2 -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner the minion will need the psycopg2 installed and -the following values configured in the master config: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -master_job_cache: postgres_local_cache -master_job_cache.postgres.host: \(aqsalt\(aq -master_job_cache.postgres.user: \(aqsalt\(aq -master_job_cache.postgres.passwd: \(aqsalt\(aq -master_job_cache.postgres.db: \(aqsalt\(aq -master_job_cache.postgres.port: 5432 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Running the following command as the postgres user should create the database -correctly: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -psql << EOF -CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; -CREATE DATABASE salt WITH OWNER salt; -EOF -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -In case the postgres database is a remote host, you\(aqll need this command also: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -ALTER ROLE salt WITH LOGIN; -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -and then: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -psql \-h localhost \-U salt << EOF -\-\- -\-\- Table structure for table \(aqjids\(aq -\-\- - -DROP TABLE IF EXISTS jids; -CREATE TABLE jids ( - jid varchar(20) PRIMARY KEY, - started TIMESTAMP WITH TIME ZONE DEFAULT now(), - tgt_type text NOT NULL, - cmd text NOT NULL, - tgt text NOT NULL, - kwargs text NOT NULL, - ret text NOT NULL, - username text NOT NULL, - arg text NOT NULL, - fun text NOT NULL -); - -\-\- -\-\- Table structure for table \(aqsalt_returns\(aq -\-\- -\-\- note that \(aqsuccess\(aq must not have NOT NULL constraint, since -\-\- some functions don\(aqt provide it. - -DROP TABLE IF EXISTS salt_returns; -CREATE TABLE salt_returns ( - added TIMESTAMP WITH TIME ZONE DEFAULT now(), - fun text NOT NULL, - jid varchar(20) NOT NULL, - return text NOT NULL, - id text NOT NULL, - success boolean -); -CREATE INDEX ON salt_returns (added); -CREATE INDEX ON salt_returns (id); -CREATE INDEX ON salt_returns (jid); -CREATE INDEX ON salt_returns (fun); - -DROP TABLE IF EXISTS salt_events; -CREATE TABLE salt_events ( - id SERIAL, - tag text NOT NULL, - data text NOT NULL, - alter_time TIMESTAMP WITH TIME ZONE DEFAULT now(), - master_id text NOT NULL -); -CREATE INDEX ON salt_events (tag); -CREATE INDEX ON salt_events (data); -CREATE INDEX ON salt_events (id); -CREATE INDEX ON salt_events (master_id); -EOF -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Required python modules: psycopg2 -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.clean_old_jobs() -Clean out the old jobs from the job cache -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.event_return(events) -Return event to a postgres server -.sp -Require that configuration be enabled via \(aqevent_return\(aq -option in master config. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.get_jids() -Return a list of all job ids -For master job cache this also formats the output and returns a string -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.prep_jid(nocache=False, passed_jid=None) -Return a job id and prepare the job id directory -This is the function responsible for making sure jids don\(aqt collide -(unless its passed a jid). So do what you have to do to make sure that -stays the case -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.returner(load) -Return data to a postgres server -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.save_load(jid, clear_load, minions=None) -Save the load to the specified jid id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.postgres_local_cache.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.pushover_returner -.sp -Return salt data via pushover (\fI\%http://www.pushover.net\fP) -.sp -New in version 2016.3.0. - -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pushover.user (required) -pushover.token (required) -pushover.title (optional) -pushover.device (optional) -pushover.priority (optional) -pushover.expire (optional) -pushover.retry (optional) -pushover.profile (optional) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fBuser\fP here is your \fBuser key\fP, \fInot\fP the email address you use to -login to pushover.net. -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.pushover.user -alternative.pushover.token -alternative.pushover.title -alternative.pushover.device -alternative.pushover.priority -alternative.pushover.expire -alternative.pushover.retry -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -PushOver settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C - pushover: - user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - title: Salt Returner - device: phone - priority: \-1 - expire: 3600 - retry: 5 - - alternative.pushover: - user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - title: Salt Returner - device: phone - priority: 1 - expire: 4800 - retry: 2 - - pushover_profile: - pushover.token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - - pushover: - user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - profile: pushover_profile - - alternative.pushover: - user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - profile: pushover_profile - -To use the PushOver returner, append \(aq\-\-return pushover\(aq to the salt command. ex: - -\&.. code\-block:: bash - - salt \(aq*\(aq test.ping \-\-return pushover - -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: - - salt \(aq*\(aq test.ping \-\-return pushover \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return pushover \-\-return_kwargs \(aq{\(dqtitle\(dq: \(dqSalt is awesome!\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.pushover_returner.returner(ret) -Send an PushOver message with the data -.UNINDENT -.SS salt.returners.rawfile_json -.sp -Take data from salt and \(dqreturn\(dq it into a raw file containing the json, with -one line per event. -.sp -Add the following to the minion or master configuration file. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -rawfile_json.filename: -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Default is \fB/var/log/salt/events\fP\&. -.sp -Common use is to log all events on the master. This can generate a lot of -noise, so you may wish to configure batch processing and/or configure the -\fI\%event_return_whitelist\fP or \fI\%event_return_blacklist\fP -to restrict the events that are written. -.INDENT 0.0 -.TP -.B salt.returners.rawfile_json.event_return(events) -Write event data (return data and non\-return data) to file on the master. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.rawfile_json.returner(ret) -Write the return data to a file on the minion. -.UNINDENT -.SS salt.returners.redis_return -.sp -Return data to a redis server -.sp -To enable this returner the minion will need the python client for redis -installed and the following values configured in the minion or master -config, these are the defaults: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -redis.db: \(aq0\(aq -redis.host: \(aqsalt\(aq -redis.port: 6379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2018.3.1: Alternatively a UNIX socket can be specified by \fIunix_socket_path\fP: - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -redis.db: \(aq0\(aq -redis.unix_socket_path: /var/run/redis/redis.sock -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Cluster Mode Example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -redis.db: \(aq0\(aq -redis.cluster_mode: true -redis.cluster.skip_full_coverage_check: true -redis.cluster.startup_nodes: - \- host: redis\-member\-1 - port: 6379 - \- host: redis\-member\-2 - port: 6379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.redis.db: \(aq0\(aq -alternative.redis.host: \(aqsalt\(aq -alternative.redis.port: 6379 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the redis returner, append \(aq\-\-return redis\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return redis -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return redis \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return redis \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Redis Cluster Mode Options: -.INDENT 0.0 -.TP -.B cluster_mode: \fBFalse\fP -Whether cluster_mode is enabled or not -.TP -.B cluster.startup_nodes: -A list of host, port dictionaries pointing to cluster members. At least one is required -but multiple nodes are better -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -redis.cluster.startup_nodes - \- host: redis\-member\-1 - port: 6379 - \- host: redis\-member\-2 - port: 6379 -.ft P -.fi -.UNINDENT -.UNINDENT -.TP -.B cluster.skip_full_coverage_check: \fBFalse\fP -Some cluster providers restrict certain redis commands such as CONFIG for enhanced security. -Set this option to true to skip checks that required advanced privileges. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Most cloud hosted redis clusters will require this to be set to \fBTrue\fP -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.clean_old_jobs() -Clean out minions\(aqs return data for old jobs. -.sp -Normally, hset \(aqret:\(aq are saved with a TTL, and will eventually -get cleaned by redis.But for jobs with some very late minion return, the -corresponding hset\(aqs TTL will be refreshed to a too late timestamp, we\(aqll -do manually cleaning here. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.get_jid(jid) -Return the information returned when the specified job id was executed -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.get_jids() -Return a dict mapping all job ids to job information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.get_load(jid) -Return the load data that marks a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.returner(ret) -Return data to a redis data store -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.redis_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.sentry_return -.sp -Salt returner that reports execution results back to sentry. The returner will -inspect the payload to identify errors and flag them as such. -.sp -Pillar needs something like: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -raven: - servers: - \- http://192.168.1.1 - \- https://sentry.example.com - public_key: deadbeefdeadbeefdeadbeefdeadbeef - secret_key: beefdeadbeefdeadbeefdeadbeefdead - project: 1 - tags: - \- os - \- master - \- saltversion - \- cpuarch -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -or using a dsn: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -raven: - dsn: https://aaaa:bbbb@app.getsentry.com/12345 - tags: - \- os - \- master - \- saltversion - \- cpuarch -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fI\%https://pypi.python.org/pypi/raven\fP must be installed. -.sp -The pillar can be hidden on sentry return by setting hide_pillar: true. -.sp -The tags list (optional) specifies grains items that will be used as sentry -tags, allowing tagging of events in the sentry ui. -.sp -To report only errors to sentry, set report_errors_only: true. -.INDENT 0.0 -.TP -.B salt.returners.sentry_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sentry_return.returner(ret) -Log outcome to sentry. The returner tries to identify errors and report -them as such. All other messages will be reported at info level. -Failed states will be appended as separate list for convenience. -.UNINDENT -.SS salt.returners.slack_returner -.sp -Return salt data via slack -.sp -New in version 2015.5.0. - -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack.channel (required) -slack.api_key (required) -slack.username (required) -slack.as_user (required to see the profile picture of your bot) -slack.profile (optional) -slack.changes(optional, only show changes and failed states) -slack.only_show_failed(optional, only show failed states) -slack.yaml_format(optional, format the json in yaml format) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack.channel -slack.api_key -slack.username -slack.as_user -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Slack settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack: - channel: RoomName - api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - username: user - as_user: true - -alternative.slack: - room_id: RoomName - api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - from_name: user@email.com - -slack_profile: - slack.api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - slack.from_name: user@email.com - -slack: - profile: slack_profile - channel: RoomName - -alternative.slack: - profile: slack_profile - channel: RoomName -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the Slack returner, append \(aq\-\-return slack\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return slack -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return slack \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return slack \-\-return_kwargs \(aq{\(dqchannel\(dq: \(dq#random\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.slack_returner.returner(ret) -Send an slack message with the data -.UNINDENT -.SS salt.returners.slack_webhook_return -.sp -Return salt data via Slack using Incoming Webhooks -.INDENT 0.0 -.TP -.B codeauthor -\fICarlos D. Álvaro \fP -.UNINDENT -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack_webhook.webhook (required, the webhook id. Just the part after: \(aqhttps://hooks.slack.com/services/\(aq) -slack_webhook.success_title (optional, short title for succeeded states. By default: \(aq{id} | Succeeded\(aq) -slack_webhook.failure_title (optional, short title for failed states. By default: \(aq{id} | Failed\(aq) -slack_webhook.author_icon (optional, a URL that with a small 16x16px image. Must be of type: GIF, JPEG, PNG, and BMP) -slack_webhook.show_tasks (optional, show identifiers for changed and failed tasks. By default: False) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack_webhook.webhook -slack_webhook.success_title -slack_webhook.failure_title -slack_webhook.author_icon -slack_webhook.show_tasks -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Slack settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -slack_webhook: - webhook: T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX - success_title: \(aq[{id}] | Success\(aq - failure_title: \(aq[{id}] | Failure\(aq - author_icon: https://platform.slack\-edge.com/img/default_application_icon.png - show_tasks: true - -alternative.slack_webhook: - webhook: T00000000/C00000000/YYYYYYYYYYYYYYYYYYYYYYYY - show_tasks: false -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the Slack returner, -append \(aq\-\-return slack_webhook\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return slack_webhook -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, -append \(aq\-\-return_config alternative\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return slack_webhook \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.slack_webhook_return.event_return(events) -Send event data to returner function -:param events: The Salt event return -:return: The result of the post -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.slack_webhook_return.returner(ret, **kwargs) -Send a slack message with the data through a webhook -:param ret: The Salt return -:return: The result of the post -.UNINDENT -.SS salt.returners.sms_return -.sp -Return data by SMS. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.TP -.B maintainer -Damian Myerscough -.TP -.B maturity -new -.TP -.B depends -twilio -.TP -.B platform -all -.UNINDENT -.sp -To enable this returner the minion will need the python twilio library -installed and the following values configured in the minion or master -config: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -twilio.sid: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq -twilio.token: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq -twilio.to: \(aq+1415XXXXXXX\(aq -twilio.from: \(aq+1650XXXXXXX\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the sms returner, append \(aq\-\-return sms\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return sms -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sms_return.returner(ret) -Return a response in an SMS message -.UNINDENT -.SS salt.returners.smtp_return -.sp -Return salt data via email -.sp -The following fields can be set in the minion conf file. Fields are optional -unless noted otherwise. -.INDENT 0.0 -.IP \(bu 2 -\fBfrom\fP (required) The name/address of the email sender. -.IP \(bu 2 -.INDENT 2.0 -.TP -.B \fBto\fP (required) The names/addresses of the email recipients; -comma\-delimited. For example: \fByou@example.com,someoneelse@example.com\fP\&. -.UNINDENT -.IP \(bu 2 -\fBhost\fP (required) The SMTP server hostname or address. -.IP \(bu 2 -\fBport\fP The SMTP server port; defaults to \fB25\fP\&. -.IP \(bu 2 -.INDENT 2.0 -.TP -.B \fBusername\fP The username used to authenticate to the server. If specified a -password is also required. It is recommended but not required to also use -TLS with this option. -.UNINDENT -.IP \(bu 2 -\fBpassword\fP The password used to authenticate to the server. -.IP \(bu 2 -\fBtls\fP Whether to secure the connection using TLS; defaults to \fBFalse\fP -.IP \(bu 2 -\fBsubject\fP The email subject line. -.IP \(bu 2 -.INDENT 2.0 -.TP -.B \fBfields\fP Which fields from the returned data to include in the subject line -of the email; comma\-delimited. For example: \fBid,fun\fP\&. Please note, \fIthe -subject line is not encrypted\fP\&. -.UNINDENT -.IP \(bu 2 -.INDENT 2.0 -.TP -.B \fBgpgowner\fP A user\(aqs \fB~/.gpg\fP directory. This must contain a gpg -public key matching the address the mail is sent to. If left unset, no -encryption will be used. Requires \fBpython\-gnupg\fP to be installed. -.UNINDENT -.IP \(bu 2 -\fBtemplate\fP The path to a file to be used as a template for the email body. -.IP \(bu 2 -.INDENT 2.0 -.TP -.B \fBrenderer\fP A Salt renderer, or render\-pipe, to use to render the email -template. Default \fBjinja\fP\&. -.UNINDENT -.UNINDENT -.sp -Below is an example of the above settings in a Salt Minion configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -smtp.from: me@example.net -smtp.to: you@example.com -smtp.host: localhost -smtp.port: 1025 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location. For example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.smtp.username: saltdev -alternative.smtp.password: saltdev -alternative.smtp.tls: True -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the SMTP returner, append \(aq\-\-return smtp\(aq to the \fBsalt\fP command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return smtp -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the \fBsalt\fP command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return smtp \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the -\fBsalt\fP command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return smtp \-\-return_kwargs \(aq{\(dqto\(dq: \(dquser@domain.com\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -An easy way to test the SMTP returner is to use the development SMTP server -built into Python. The command below will start a single\-threaded SMTP server -that prints any email it receives to the console. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -python \-m smtpd \-n \-c DebuggingServer localhost:1025 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -New in version 2016.11.0. - -.sp -It is possible to send emails with selected Salt events by configuring \fBevent_return\fP option -for Salt Master. For example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -event_return: smtp - -event_return_whitelist: - \- salt/key - -smtp.from: me@example.net -smtp.to: you@example.com -smtp.host: localhost -smtp.subject: \(aqSalt Master {{act}}ed key from Minion ID: {{id}}\(aq -smtp.template: /srv/salt/templates/email.j2 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Also you need to create additional file \fB/srv/salt/templates/email.j2\fP with email body template: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -act: {{act}} -id: {{id}} -result: {{result}} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This configuration enables Salt Master to send an email when accepting or rejecting minions keys. -.INDENT 0.0 -.TP -.B salt.returners.smtp_return.event_return(events) -Return event data via SMTP -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.smtp_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.smtp_return.returner(ret) -Send an email with the data -.UNINDENT -.SS salt.returners.splunk -.sp -Send json response data to Splunk via the HTTP Event Collector -Requires the following config values to be specified in config or pillar: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -splunk_http_forwarder: - token: - indexer: - sourcetype: - index: - verify_ssl: true -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Run a test by using \fBsalt\-call test.ping \-\-return splunk\fP -.sp -Written by Scott Pack (github.com/scottjpack) -.INDENT 0.0 -.TP -.B salt.returners.splunk.event_return(events) -Return events to Splunk via the HTTP Event Collector. -Requires the Splunk HTTP Event Collector running on port 8088. -This is available on Splunk Enterprise version 6.3 or higher. -.UNINDENT -.INDENT 0.0 -.TP -.B class salt.returners.splunk.http_event_collector(token, http_event_server, host=\(aq\(aq, http_event_port=\(aq8088\(aq, http_event_server_ssl=True, max_bytes=100000, verify_ssl=True) -.INDENT 7.0 -.TP -.B sendEvent(payload, eventtime=\(aq\(aq) -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.splunk.returner(ret) -Send a message to Splunk via the HTTP Event Collector. -Requires the Splunk HTTP Event Collector running on port 8088. -This is available on Splunk Enterprise version 6.3 or higher. -.UNINDENT -.SS salt.returners.sqlite3 -.sp -Insert minion return data into a sqlite3 database -.INDENT 0.0 -.TP -.B maintainer -Mickey Malone <\fI\%mickey.malone@gmail.com\fP> -.TP -.B maturity -New -.TP -.B depends -None -.TP -.B platform -All -.UNINDENT -.sp -Sqlite3 is a serverless database that lives in a single file. -In order to use this returner the database file must exist, -have the appropriate schema defined, and be accessible to the -user whom the minion process is running as. This returner -requires the following values configured in the master or -minion config: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -sqlite3.database: /usr/lib/salt/salt.db -sqlite3.timeout: 5.0 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.sqlite3.database: /usr/lib/salt/salt.db -alternative.sqlite3.timeout: 5.0 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Use the commands to create the sqlite3 database and tables: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -sqlite3 /usr/lib/salt/salt.db << EOF -\-\- -\-\- Table structure for table \(aqjids\(aq -\-\- - -CREATE TABLE jids ( - jid TEXT PRIMARY KEY, - load TEXT NOT NULL - ); - -\-\- -\-\- Table structure for table \(aqsalt_returns\(aq -\-\- - -CREATE TABLE salt_returns ( - fun TEXT KEY, - jid TEXT KEY, - id TEXT KEY, - fun_args TEXT, - date TEXT NOT NULL, - full_ret TEXT NOT NULL, - success TEXT NOT NULL - ); -EOF -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the sqlite returner, append \(aq\-\-return sqlite3\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return sqlite3 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_kwargs \(aq{\(dqdb\(dq: \(dq/var/lib/salt/another\-salt.db\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.get_fun(fun) -Return a dict of the last function called for all minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.get_jid(jid) -Return the information returned from a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.get_jids() -Return a list of all job ids -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.get_load(jid) -Return the load from a specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.get_minions() -Return a list of minions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.returner(ret) -Insert minion return data into the sqlite3 database -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.save_load(jid, load, minions=None) -Save the load to the specified jid -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.sqlite3_return.save_minions(jid, minions, syndic_id=None) -Included for API consistency -.UNINDENT -.SS salt.returners.syslog_return -.sp -Return data to the host operating system\(aqs syslog facility -.sp -To use the syslog returner, append \(aq\-\-return syslog\(aq to the -salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return syslog -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -syslog.level (optional, Default: LOG_INFO) -syslog.facility (optional, Default: LOG_USER) -syslog.tag (optional, Default: salt\-minion) -syslog.options (list, optional, Default: []) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Available levels, facilities, and options can be found in the -\fBsyslog\fP docs for your python version. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The default tag comes from \fBsys.argv[0]\fP which is -usually \(dqsalt\-minion\(dq but could be different based on -the specific environment. -.UNINDENT -.UNINDENT -.sp -Configuration example: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -syslog.level: \(aqLOG_ERR\(aq -syslog.facility: \(aqLOG_DAEMON\(aq -syslog.tag: \(aqmysalt\(aq -syslog.options: - \- LOG_PID -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Of course you can also nest the options: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -syslog: - level: \(aqLOG_ERR\(aq - facility: \(aqLOG_DAEMON\(aq - tag: \(aqmysalt\(aq - options: - \- LOG_PID -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by -prefacing the configuration. Any values not found -in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -alternative.syslog.level: \(aqLOG_WARN\(aq -alternative.syslog.facility: \(aqLOG_NEWS\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append -\fB\-\-return_config alternative\fP to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return syslog \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append -\-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return syslog \-\-return_kwargs \(aq{\(dqlevel\(dq: \(dqLOG_DEBUG\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Syslog server implementations may have limits on the maximum -record size received by the client. This may lead to job -return data being truncated in the syslog server\(aqs logs. For -example, for rsyslog on RHEL\-based systems, the default -maximum record size is approximately 2KB (which return data -can easily exceed). This is configurable in rsyslog.conf via -the $MaxMessageSize config parameter. Please consult your syslog -implmentation\(aqs documentation to determine how to adjust this limit. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.syslog_return.prep_jid(nocache=False, passed_jid=None) -Do any work necessary to prepare a JID, including sending a custom id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.syslog_return.returner(ret) -Return data to the local syslog -.UNINDENT -.SS salt.returners.telegram_return -.sp -Return salt data via Telegram. -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -telegram.chat_id (required) -telegram.token (required) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Telegram settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -telegram: - chat_id: 000000000 - token: 000000000:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the Telegram return, append \(aq\-\-return telegram\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return telegram -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.telegram_return.returner(ret) -Send a Telegram message with the data. -.INDENT 7.0 -.TP -.B Parameters -\fBret\fP \-\- The data to be sent. -.TP -.B Returns -Boolean if message was sent successfully. -.UNINDENT -.UNINDENT -.SS salt.returners.xmpp_return -.sp -Return salt data via xmpp -.INDENT 0.0 -.TP -.B depends -sleekxmpp >= 1.3.1 -.UNINDENT -.sp -The following fields can be set in the minion conf file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -xmpp.jid (required) -xmpp.password (required) -xmpp.recipient (required) -xmpp.profile (optional) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Alternative configuration values can be used by prefacing the configuration. -Any values not found in the alternative configuration will be pulled from -the default location: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -xmpp.jid -xmpp.password -xmpp.recipient -xmpp.profile -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -XMPP settings may also be configured as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -xmpp: - jid: user@xmpp.domain.com/resource - password: password - recipient: user@xmpp.example.com - -alternative.xmpp: - jid: user@xmpp.domain.com/resource - password: password - recipient: someone@xmpp.example.com - -xmpp_profile: - xmpp.jid: user@xmpp.domain.com/resource - xmpp.password: password - -xmpp: - profile: xmpp_profile - recipient: user@xmpp.example.com - -alternative.xmpp: - profile: xmpp_profile - recipient: someone\-else@xmpp.example.com -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the XMPP returner, append \(aq\-\-return xmpp\(aq to the salt command. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return xmpp -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. -.sp -New in version 2015.5.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_config alternative -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. -.sp -New in version 2016.3.0. - -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_kwargs \(aq{\(dqrecipient\(dq: \(dqsomeone\-else@xmpp.example.com\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B class salt.returners.xmpp_return.SendMsgBot(jid, password, recipient, msg) -.INDENT 7.0 -.TP -.B start(event) -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.xmpp_return.returner(ret) -Send an xmpp message with the data -.UNINDENT -.SS salt.returners.zabbix_return -.sp -Return salt data to Zabbix -.sp -The following Type: \(dqZabbix trapper\(dq with \(dqType of information\(dq Text items are required: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -Key: salt.trap.info -Key: salt.trap.warning -Key: salt.trap.high -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To use the Zabbix returner, append \(aq\-\-return zabbix\(aq to the salt command. ex: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq test.ping \-\-return zabbix -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.zabbix_return.returner(ret) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.zabbix_return.save_load(jid, load, minions=None) -Included for API consistency -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.zabbix_return.zabbix_send(key, output) -.UNINDENT -.INDENT 0.0 -.TP -.B salt.returners.zabbix_return.zbx() -.UNINDENT .SS Renderers .sp The Salt state system operates by gathering information from common data types @@ -39495,6 +34216,72 @@ Example 3: [80, 25, 22] .fi .UNINDENT .UNINDENT +.SS \fBto_entries\fP +.sp +New in version 3007.0. + +.sp +A port of the \fBto_entries\fP function from \fBjq\fP\&. This function converts between an object and an array of key\-value +pairs. If \fBto_entries\fP is passed an object, then for each \fBk: v\fP entry in the input, the output array includes +\fB{\(dqkey\(dq: k, \(dqvalue\(dq: v}\fP\&. The \fBfrom_entries\fP function performs the opposite conversion. \fBfrom_entries\fP accepts +\(dqkey\(dq, \(dqKey\(dq, \(dqname\(dq, \(dqName\(dq, \(dqvalue\(dq, and \(dqValue\(dq as keys. +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{{ {\(dqa\(dq: 1, \(dqb\(dq: 2} | to_entries }} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Returns: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[{\(dqkey\(dq:\(dqa\(dq, \(dqvalue\(dq:1}, {\(dqkey\(dq:\(dqb\(dq, \(dqvalue\(dq:2}] +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBfrom_entries\fP +.sp +New in version 3007.0. + +.sp +A port of the \fBfrom_entries\fP function from \fBjq\fP\&. This function converts between an array of key\-value pairs and an +object. If \fBfrom_entries\fP is passed an object, then the input is expected to be an array of dictionaries in the format +of \fB{\(dqkey\(dq: k, \(dqvalue\(dq: v}\fP\&. The output will be be key\-value pairs \fBk: v\fP\&. \fBfrom_entries\fP accepts \(dqkey\(dq, \(dqKey\(dq, +\(dqname\(dq, \(dqName\(dq, \(dqvalue\(dq, and \(dqValue\(dq as keys. +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{{ [{\(dqkey\(dq:\(dqa\(dq, \(dqvalue\(dq:1}, {\(dqkey\(dq:\(dqb\(dq, \(dqvalue\(dq:2}] | from_entries }} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Returns: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{\(dqa\(dq: 1, \(dqb\(dq: 2} +.ft P +.fi +.UNINDENT +.UNINDENT .SS \fBto_snake_case\fP .sp New in version 3000. @@ -44893,6 +39680,106 @@ web6: .fi .UNINDENT .UNINDENT +.SS Master Cluster +.sp +A clustered Salt Master has several advantages over Salt\(aqs traditional High +Availability options. First, a master cluster is meant to be served behind a +load balancer. Minions only need to know about the load balancer\(aqs IP address. +Therefore, masters can be added and removed from a cluster without the need to +re\-configure minions. Another major benefit of master clusters over Salt\(aqs +older HA implimentations is that Masters in a cluster share the load of all +jobs. This allows Salt administrators to more easily scale their environments +to handle larger numbers of minions and larger jobs. +.SS Minimum Requirements +.sp +Running a cluster master requires all nodes in the cluster to have a shared +filesystem. The \fIcluster_pki_dir\fP, \fIcache_dir\fP, \fIfile_roots\fP and \fIpillar_roots\fP +must all be on a shared filesystem. Most implementations will also serve the +masters publish and request server ports via a tcp load balancer. All of the +masters in a cluster are assumed to be running on a reliable local area +network. +.sp +Each master in a cluster maintains its own public and private key, and an in +memory aes key. Each cluster peer also has access to the \fIcluster_pki_dir\fP +where a cluster wide public and private key are stored. In addition, the cluster +wide aes key is generated and stored in the \fIcluster_pki_dir\fP\&. Further, +when operating as a cluster, minion keys are stored in the \fIcluster_pki_dir\fP +instead of the master\(aqs \fIpki_dir\fP\&. +.SS Reference Implimentation +.sp +Gluster: \fI\%https://docs.gluster.org/en/main/Quick\-Start\-Guide/Quickstart/\fP +.sp +HAProxy: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +frontend salt\-master\-pub + mode tcp + bind 10.27.5.116:4505 + option tcplog + timeout client 1m + default_backend salt\-master\-pub\-backend + +backend salt\-master\-pub\-backend + mode tcp + option tcplog + #option log\-health\-checks + log global + #balance source + balance roundrobin + timeout connect 10s + timeout server 1m + server rserve1 10.27.12.13:4505 check + server rserve2 10.27.7.126:4505 check + server rserve3 10.27.3.73:4505 check + +frontend salt\-master\-req + mode tcp + bind 10.27.5.116:4506 + option tcplog + timeout client 1m + default_backend salt\-master\-req\-backend + +backend salt\-master\-req\-backend + mode tcp + option tcplog + #option log\-health\-checks + log global + balance roundrobin + #balance source + timeout connect 10s + timeout server 1m + server rserve1 10.27.12.13:4506 check + server rserve2 10.27.7.126:4506 check + server rserve3 10.27.3.73:4506 check +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Master Config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +id: 10.27.12.13 +cluster_id: master_cluster +cluster_peers: + \- 10.27.7.126 + \- 10.27.3.73 +cluster_pki_dir: /my/gluster/share/pki +cache_dir: /my/gluster/share/cache +file_roots: + \- /my/gluster/share/srv/salt +pillar_roots: + \- /my/gluster/share/srv/pillar +.ft P +.fi +.UNINDENT +.UNINDENT .SS Remote execution tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by @@ -46527,8 +41414,8 @@ Many of the most powerful and useful engineering solutions are founded on simple principles. Salt States strive to do just that: K.I.S.S. (Keep It Stupidly Simple) .sp -The core of the Salt State system is the SLS, or \fBS\fPa\fBL\fPt -\fBS\fPtate file. The SLS is a representation of the state in which +The core of the Salt State system is the SLS, or \fBS\fPtructured \fBL\fPayered \fBS\fPtate. +The SLS is a representation of the state in which a system should be in, and is set up to contain this data in a simple format. This is often called configuration management. .sp @@ -48841,7 +43728,7 @@ l_gsoc2014: \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Welcome to SaltStack! I am excited that you are interested in Salt and +Welcome to Salt Project! I am excited that you are interested in Salt and starting down the path to better infrastructure management. I developed (and am continuing to develop) Salt with the goal of making the best software available to manage computers of almost any kind. I hope you enjoy @@ -48850,9 +43737,7 @@ working with Salt and that the software can solve your real world needs! .IP \(bu 2 Thomas S Hatch .IP \(bu 2 -Salt creator and Chief Developer -.IP \(bu 2 -CTO of SaltStack, Inc. +Salt Project creator and Chief Developer of Salt Project .UNINDENT .UNINDENT .UNINDENT @@ -49948,51 +44833,18 @@ From the minion folder, type .sp .nf .ft C -vagrant init +vagrant init ubuntu/focal64 .ft P .fi .UNINDENT .UNINDENT .sp -This command creates a default Vagrantfile configuration file. This +This command creates a default Vagrantfile configuration file and import focal64 virtualbox image file to configuration, so it could be used. This configuration file will be used to pass configuration parameters to the Salt provisioner in Step 3. -.SS Import Precise64 Ubuntu Box -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -vagrant box add precise64 http://files.vagrantup.com/precise64.box -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This box is added at the global Vagrant level. You only need to do it -once as each VM will use this same file. -.UNINDENT -.UNINDENT .SS Modify the Vagrantfile .sp -Modify ./minion/Vagrantfile to use th precise64 box. Change the \fBconfig.vm.box\fP -line to: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -config.vm.box = \(dqprecise64\(dq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Uncomment the line creating a host\-only IP. This is the ip of your minion -(you can change it to something else if that IP is already in use): +Modify Vagrantfile to use th private_ip in local network. .INDENT 0.0 .INDENT 3.5 .sp @@ -50048,7 +44900,7 @@ vagrant ssh .UNINDENT .sp You should see the shell prompt change to something similar to -\fBvagrant@precise64:~$\fP meaning you\(aqre inside the VM. From there, enter the +\fBvagrant@focal64:~$\fP meaning you\(aqre inside the VM. From there, enter the following: .INDENT 0.0 .INDENT 3.5 @@ -54509,6 +49361,5650 @@ def foo(): .fi .UNINDENT .UNINDENT +.SS Returners +.sp +By default the return values of the commands sent to the Salt minions are +returned to the Salt master, however anything at all can be done with the results +data. +.sp +By using a Salt returner, results data can be redirected to external data\-stores +for analysis and archival. +.sp +Returners pull their configuration values from the Salt minions. Returners are only +configured once, which is generally at load time. +.sp +The returner interface allows the return data to be sent to any system that +can receive data. This means that return data can be sent to a Redis server, +a MongoDB server, a MySQL server, or any system. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +\fI\%Full list of builtin returners\fP +.UNINDENT +.UNINDENT +.SS Using Returners +.sp +All Salt commands will return the command data back to the master. Specifying +returners will ensure that the data is _also_ sent to the specified returner +interfaces. +.sp +Specifying what returners to use is done when the command is invoked: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.version \-\-return redis_return +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This command will ensure that the redis_return returner is used. +.sp +It is also possible to specify multiple returners: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.version \-\-return mongo_return,redis_return,cassandra_return +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In this scenario all three returners will be called and the data from the +test.version command will be sent out to the three named returners. +.SS Writing a Returner +.sp +Returners are Salt modules that allow the redirection of results data to targets other than the Salt Master. +.SS Returners Are Easy To Write! +.sp +Writing a Salt returner is straightforward. +.sp +A returner is a Python module containing at minimum a \fBreturner\fP function. +Other optional functions can be included to add support for +\fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, and \fI\%Event Returners\fP\&. +.INDENT 0.0 +.TP +.B \fBreturner\fP +The \fBreturner\fP function must accept a single argument. The argument +contains return data from the called minion function. If the minion +function \fBtest.version\fP is called, the value of the argument will be a +dictionary. Run the following command from a Salt master to get a sample +of the dictionary: +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call \-\-local \-\-metadata test.version \-\-out=pprint +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +import redis +import salt.utils.json + + +def returner(ret): + \(dq\(dq\(dq + Return information to a redis server + \(dq\(dq\(dq + # Get a redis connection + serv = redis.Redis(host=\(dqredis\-serv.example.com\(dq, port=6379, db=\(dq0\(dq) + serv.sadd(\(dq%(id)s:jobs\(dq % ret, ret[\(dqjid\(dq]) + serv.set(\(dq%(jid)s:%(id)s\(dq % ret, salt.utils.json.dumps(ret[\(dqreturn\(dq])) + serv.sadd(\(dqjobs\(dq, ret[\(dqjid\(dq]) + serv.sadd(ret[\(dqjid\(dq], ret[\(dqid\(dq]) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The above example of a returner set to send the data to a Redis server +serializes the data as JSON and sets it in redis. +.SS Using Custom Returner Modules +.sp +Place custom returners in a \fB_returners/\fP directory within the +\fI\%file_roots\fP specified by the master config file. +.sp +Like all custom modules, these must be synced to the relevant master or minion +before they can be used. See \fI\%Modular Systems\fP for details. +.sp +Any custom returners which have been synced to a minion that are named the +same as one of Salt\(aqs default set of returners will take the place of the +default returner with the same name. +.SS Naming the Returner +.sp +Note that a returner\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes +returner \fBfoo\fP), but that its name can be overridden by using a +\fI\%__virtual__ function\fP\&. A good example of this can be +found in the \fI\%redis\fP returner, which is named \fBredis_return.py\fP but is +loaded as simply \fBredis\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +try: + import redis + + HAS_REDIS = True +except ImportError: + HAS_REDIS = False + +__virtualname__ = \(dqredis\(dq + + +def __virtual__(): + if not HAS_REDIS: + return False + return __virtualname__ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Master Job Cache Support +.sp +\fI\%master_job_cache\fP, \fI\%Storing Job Results in an External System\fP, and \fI\%Event Returners\fP\&. +Salt\(aqs \fI\%master_job_cache\fP allows returners to be used as a pluggable +replacement for the \fI\%Default Job Cache\fP\&. In order to do so, a returner +must implement the following functions: +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The code samples contained in this section were taken from the cassandra_cql +returner. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBprep_jid\fP +Ensures that job ids (jid) don\(aqt collide, unless passed_jid is provided. +.sp +\fBnocache\fP is an optional boolean that indicates if return data +should be cached. \fBpassed_jid\fP is a caller provided jid which should be +returned unconditionally. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +def prep_jid(nocache, passed_jid=None): # pylint: disable=unused\-argument + \(dq\(dq\(dq + Do any work necessary to prepare a JID, including sending a custom id + \(dq\(dq\(dq + return passed_jid if passed_jid is not None else salt.utils.jid.gen_jid() +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBsave_load\fP +Save job information. The \fBjid\fP is generated by \fBprep_jid\fP and should +be considered a unique identifier for the job. The jid, for example, could +be used as the primary/unique key in a database. The \fBload\fP is what is +returned to a Salt master by a minion. \fBminions\fP is a list of minions +that the job was run against. The following code example stores the load as +a JSON string in the salt.jids table. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +import salt.utils.json + + +def save_load(jid, load, minions=None): + \(dq\(dq\(dq + Save the load to the specified jid id + \(dq\(dq\(dq + query = \(dq\(dq\(dqINSERT INTO salt.jids ( + jid, load + ) VALUES ( + \(aq{0}\(aq, \(aq{1}\(aq + );\(dq\(dq\(dq.format( + jid, salt.utils.json.dumps(load) + ) + + # cassandra_cql.cql_query may raise a CommandExecutionError + try: + __salt__[\(dqcassandra_cql.cql_query\(dq](query) + except CommandExecutionError: + log.critical(\(dqCould not save load in jids table.\(dq) + raise + except Exception as e: + log.critical(\(dqUnexpected error while inserting into jids: {0}\(dq.format(e)) + raise +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBget_load\fP +must accept a job id (jid) and return the job load stored by \fBsave_load\fP, +or an empty dictionary when not found. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +def get_load(jid): + \(dq\(dq\(dq + Return the load data that marks a specified jid + \(dq\(dq\(dq + query = \(dq\(dq\(dqSELECT load FROM salt.jids WHERE jid = \(aq{0}\(aq;\(dq\(dq\(dq.format(jid) + + ret = {} + + # cassandra_cql.cql_query may raise a CommandExecutionError + try: + data = __salt__[\(dqcassandra_cql.cql_query\(dq](query) + if data: + load = data[0].get(\(dqload\(dq) + if load: + ret = json.loads(load) + except CommandExecutionError: + log.critical(\(dqCould not get load from jids table.\(dq) + raise + except Exception as e: + log.critical( + \(dq\(dq\(dqUnexpected error while getting load from + jids: {0}\(dq\(dq\(dq.format( + str(e) + ) + ) + raise + + return ret +.ft P +.fi +.UNINDENT +.UNINDENT +.SS External Job Cache Support +.sp +Salt\(aqs \fI\%Storing Job Results in an External System\fP extends the \fI\%master_job_cache\fP\&. External +Job Cache support requires the following functions in addition to what is +required for Master Job Cache support: +.INDENT 0.0 +.TP +.B \fBget_jid\fP +Return a dictionary containing the information (load) returned by each +minion when the specified job id was executed. +.UNINDENT +.sp +Sample: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + \(dqlocal\(dq: { + \(dqmaster_minion\(dq: { + \(dqfun_args\(dq: [], + \(dqjid\(dq: \(dq20150330121011408195\(dq, + \(dqreturn\(dq: \(dq2018.3.4\(dq, + \(dqretcode\(dq: 0, + \(dqsuccess\(dq: true, + \(dqcmd\(dq: \(dq_return\(dq, + \(dq_stamp\(dq: \(dq2015\-03\-30T12:10:12.708663\(dq, + \(dqfun\(dq: \(dqtest.version\(dq, + \(dqid\(dq: \(dqmaster_minion\(dq + } + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBget_fun\fP +Return a dictionary of minions that called a given Salt function as their +last function call. +.UNINDENT +.sp +Sample: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + \(dqlocal\(dq: { + \(dqminion1\(dq: \(dqtest.version\(dq, + \(dqminion3\(dq: \(dqtest.version\(dq, + \(dqminion2\(dq: \(dqtest.version\(dq + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBget_jids\fP +Return a list of all job ids. +.UNINDENT +.sp +Sample: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + \(dqlocal\(dq: [ + \(dq20150330121011408195\(dq, + \(dq20150330195922139916\(dq + ] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBget_minions\fP +Returns a list of minions +.UNINDENT +.sp +Sample: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ + \(dqlocal\(dq: [ + \(dqminion3\(dq, + \(dqminion2\(dq, + \(dqminion1\(dq, + \(dqmaster_minion\(dq + ] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Please refer to one or more of the existing returners (i.e. mysql, +cassandra_cql) if you need further clarification. +.SS Event Support +.sp +An \fBevent_return\fP function must be added to the returner module to allow +events to be logged from a master via the returner. A list of events are passed +to the function by the master. +.sp +The following example was taken from the MySQL returner. In this example, each +event is inserted into the salt_events table keyed on the event tag. The tag +contains the jid and therefore is guaranteed to be unique. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +import salt.utils.json + + +def event_return(events): + \(dq\(dq\(dq + Return event to mysql server + + Requires that configuration be enabled via \(aqevent_return\(aq + option in master config. + \(dq\(dq\(dq + with _get_serv(events, commit=True) as cur: + for event in events: + tag = event.get(\(dqtag\(dq, \(dq\(dq) + data = event.get(\(dqdata\(dq, \(dq\(dq) + sql = \(dq\(dq\(dqINSERT INTO \(gasalt_events\(ga (\(gatag\(ga, \(gadata\(ga, \(gamaster_id\(ga ) + VALUES (%s, %s, %s)\(dq\(dq\(dq + cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__[\(dqid\(dq])) +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Testing the Returner +.sp +The \fBreturner\fP, \fBprep_jid\fP, \fBsave_load\fP, \fBget_load\fP, and +\fBevent_return\fP functions can be tested by configuring the +\fI\%master_job_cache\fP and \fI\%Event Returners\fP in the master config +file and submitting a job to \fBtest.version\fP each minion from the master. +.sp +Once you have successfully exercised the Master Job Cache functions, test the +External Job Cache functions using the \fBret\fP execution module. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-call ret.get_jids cassandra_cql \-\-output=json +salt\-call ret.get_fun cassandra_cql test.version \-\-output=json +salt\-call ret.get_minions cassandra_cql \-\-output=json +salt\-call ret.get_jid cassandra_cql 20150330121011408195 \-\-output=json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Event Returners +.sp +For maximum visibility into the history of events across a Salt +infrastructure, all events seen by a salt master may be logged to one or +more returners. +.sp +To enable event logging, set the \fBevent_return\fP configuration option in the +master config to the returner(s) which should be designated as the handler +for event returns. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Not all returners support event returns. Verify a returner has an +\fBevent_return()\fP function before using. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +On larger installations, many hundreds of events may be generated on a +busy master every second. Be certain to closely monitor the storage of +a given returner as Salt can easily overwhelm an underpowered server +with thousands of returns. +.UNINDENT +.UNINDENT +.SS Full List of Returners +.SS returner modules +.TS +center; +|l|l|. +_ +T{ +\fI\%appoptics_return\fP +T} T{ +Salt returner to return highstate stats to AppOptics Metrics +T} +_ +T{ +\fI\%carbon_return\fP +T} T{ +Take data from salt and \(dqreturn\(dq it into a carbon receiver +T} +_ +T{ +\fI\%cassandra_cql_return\fP +T} T{ +Return data to a cassandra server +T} +_ +T{ +\fI\%couchbase_return\fP +T} T{ +Simple returner for Couchbase. +T} +_ +T{ +\fI\%couchdb_return\fP +T} T{ +Simple returner for CouchDB. +T} +_ +T{ +\fI\%elasticsearch_return\fP +T} T{ +Return data to an elasticsearch server for indexing. +T} +_ +T{ +\fI\%etcd_return\fP +T} T{ +Return data to an etcd server or cluster +T} +_ +T{ +\fI\%highstate_return\fP +T} T{ +Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file. +T} +_ +T{ +\fI\%influxdb_return\fP +T} T{ +Return data to an influxdb server. +T} +_ +T{ +\fI\%kafka_return\fP +T} T{ +Return data to a Kafka topic +T} +_ +T{ +\fI\%librato_return\fP +T} T{ +Salt returner to return highstate stats to Librato +T} +_ +T{ +\fI\%local\fP +T} T{ +The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly +T} +_ +T{ +\fI\%local_cache\fP +T} T{ +Return data to local job cache +T} +_ +T{ +\fI\%mattermost_returner\fP +T} T{ +Return salt data via mattermost +T} +_ +T{ +\fI\%memcache_return\fP +T} T{ +Return data to a memcache server +T} +_ +T{ +\fI\%mongo_future_return\fP +T} T{ +Return data to a mongodb server +T} +_ +T{ +\fI\%mongo_return\fP +T} T{ +Return data to a mongodb server +T} +_ +T{ +\fI\%multi_returner\fP +T} T{ +Read/Write multiple returners +T} +_ +T{ +\fI\%mysql\fP +T} T{ +Return data to a mysql server +T} +_ +T{ +\fI\%nagios_nrdp_return\fP +T} T{ +Return salt data to Nagios +T} +_ +T{ +\fI\%odbc\fP +T} T{ +Return data to an ODBC compliant server. +T} +_ +T{ +\fI\%pgjsonb\fP +T} T{ +Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type +T} +_ +T{ +\fI\%postgres\fP +T} T{ +Return data to a postgresql server +T} +_ +T{ +\fI\%postgres_local_cache\fP +T} T{ +Use a postgresql server for the master job cache. +T} +_ +T{ +\fI\%pushover_returner\fP +T} T{ +T} +_ +T{ +\fI\%rawfile_json\fP +T} T{ +Take data from salt and \(dqreturn\(dq it into a raw file containing the json, with one line per event. +T} +_ +T{ +\fI\%redis_return\fP +T} T{ +Return data to a redis server +T} +_ +T{ +\fI\%sentry_return\fP +T} T{ +Salt returner that reports execution results back to sentry. +T} +_ +T{ +\fI\%slack_returner\fP +T} T{ +Return salt data via slack +T} +_ +T{ +\fI\%slack_webhook_return\fP +T} T{ +Return salt data via Slack using Incoming Webhooks +T} +_ +T{ +\fI\%sms_return\fP +T} T{ +Return data by SMS. +T} +_ +T{ +\fI\%smtp_return\fP +T} T{ +Return salt data via email +T} +_ +T{ +\fI\%splunk\fP +T} T{ +Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar: +T} +_ +T{ +\fI\%sqlite3_return\fP +T} T{ +Insert minion return data into a sqlite3 database +T} +_ +T{ +\fI\%syslog_return\fP +T} T{ +Return data to the host operating system\(aqs syslog facility +T} +_ +T{ +\fI\%telegram_return\fP +T} T{ +Return salt data via Telegram. +T} +_ +T{ +\fI\%xmpp_return\fP +T} T{ +Return salt data via xmpp +T} +_ +T{ +\fI\%zabbix_return\fP +T} T{ +T} +_ +.TE +.SS salt.returners.appoptics_return +.sp +Salt returner to return highstate stats to AppOptics Metrics +.sp +To enable this returner the minion will need the AppOptics Metrics +client importable on the Python path and the following +values configured in the minion or master config. +.sp +The AppOptics python client can be found at: +.sp +\fI\%https://github.com/appoptics/python\-appoptics\-metrics\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +appoptics.api_token: abc12345def +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +An example configuration that returns the total number of successes +and failures for your salt highstate runs (the default) would look +like this: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +return: appoptics +appoptics.api_token: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The returner publishes the following metrics to AppOptics: +.INDENT 0.0 +.IP \(bu 2 +saltstack.failed +.IP \(bu 2 +saltstack.passed +.IP \(bu 2 +saltstack.retcode +.IP \(bu 2 +saltstack.runtime +.IP \(bu 2 +saltstack.total +.UNINDENT +.sp +You can add a tags section to specify which tags should be attached to +all metrics created by the returner. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +appoptics.tags: + host_hostname_alias: + tier: + cluster: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If no tags are explicitly configured, then the tag key \fBhost_hostname_alias\fP +will be set, with the minion\(aqs \fBid\fP grain being the value. +.sp +In addition to the requested tags, for a highstate run each of these +will be tagged with the \fBkey:value\fP of \fBstate_type: highstate\fP\&. +.sp +In order to return metrics for \fBstate.sls\fP runs (distinct from highstates), you can +specify a list of state names to the key \fBappoptics.sls_states\fP like so: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +appoptics.sls_states: + \- role_salt_master.netapi + \- role_redis.config + \- role_smarty.dummy +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will report success and failure counts on runs of the +\fBrole_salt_master.netapi\fP, \fBrole_redis.config\fP, and +\fBrole_smarty.dummy\fP states in addition to highstates. +.sp +This will report the same metrics as above, but for these runs the +metrics will be tagged with \fBstate_type: sls\fP and \fBstate_name\fP set to +the name of the state that was invoked, e.g. \fBrole_salt_master.netapi\fP\&. +.INDENT 0.0 +.TP +.B salt.returners.appoptics_return.returner(ret) +Parse the return data and return metrics to AppOptics. +.sp +For each state that\(aqs provided in the configuration, return tagged metrics for +the result of that state if it\(aqs present. +.UNINDENT +.SS salt.returners.carbon_return +.sp +Take data from salt and \(dqreturn\(dq it into a carbon receiver +.sp +Add the following configuration to the minion configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +carbon.host: +carbon.port: 2003 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Errors when trying to convert data to numbers may be ignored by setting +\fBcarbon.skip_on_error\fP to \fITrue\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +carbon.skip_on_error: True +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +By default, data will be sent to carbon using the plaintext protocol. To use +the pickle protocol, set \fBcarbon.mode\fP to \fBpickle\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +carbon.mode: pickle +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B You can also specify the pattern used for the metric base path (except for virt modules metrics): +carbon.metric_base_pattern: carbon.[minion_id].[module].[function] +.TP +.B These tokens can used : +[module]: salt module +[function]: salt function +[minion_id]: minion id +.TP +.B Default is : +carbon.metric_base_pattern: [module].[function].[minion_id] +.UNINDENT +.sp +Carbon settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +carbon: + host: + port: + skip_on_error: True + mode: (pickle|text) + metric_base_pattern: | [module].[function].[minion_id] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.carbon: + host: + port: + skip_on_error: True + mode: (pickle|text) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the carbon returner, append \(aq\-\-return carbon\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return carbon +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return carbon \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return carbon \-\-return_kwargs \(aq{\(dqskip_on_error\(dq: False}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.carbon_return.event_return(events) +Return event data to remote carbon server +.sp +Provide a list of events to be stored in carbon +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.carbon_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.carbon_return.returner(ret) +Return data to a remote carbon server using the text metric protocol +.sp +Each metric will look like: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +[module].[function].[minion_id].[metric path [...]].[metric name] +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.SS salt.returners.cassandra_cql_return +.sp +Return data to a cassandra server +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.TP +.B maintainer +Corin Kochenower<\fI\%ckochenower@saltstack.com\fP> +.TP +.B maturity +new as of 2015.2 +.TP +.B depends +salt.modules.cassandra_cql +.TP +.B depends +DataStax Python Driver for Apache Cassandra +\fI\%https://github.com/datastax/python\-driver\fP +pip install cassandra\-driver +.TP +.B platform +all +.TP +.B configuration +To enable this returner, the minion will need the DataStax Python Driver +for Apache Cassandra ( \fI\%https://github.com/datastax/python\-driver\fP ) +installed and the following values configured in the minion or master +config. The list of cluster IPs must include at least one cassandra node +IP address. No assumption or default will be used for the cluster IPs. +The cluster IPs will be tried in the order listed. The port, username, +and password values shown below will be the assumed defaults if you do +not provide values.: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +cassandra: + cluster: + \- 192.168.50.11 + \- 192.168.50.12 + \- 192.168.50.13 + port: 9042 + username: salt + password: salt +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Use the following cassandra database schema: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +CREATE KEYSPACE IF NOT EXISTS salt + WITH replication = {\(aqclass\(aq: \(aqSimpleStrategy\(aq, \(aqreplication_factor\(aq : 1}; + +CREATE USER IF NOT EXISTS salt WITH PASSWORD \(aqsalt\(aq NOSUPERUSER; + +GRANT ALL ON KEYSPACE salt TO salt; + +USE salt; + +CREATE TABLE IF NOT EXISTS salt.salt_returns ( + jid text, + minion_id text, + fun text, + alter_time timestamp, + full_ret text, + return text, + success boolean, + PRIMARY KEY (jid, minion_id, fun) +) WITH CLUSTERING ORDER BY (minion_id ASC, fun ASC); +CREATE INDEX IF NOT EXISTS salt_returns_minion_id ON salt.salt_returns (minion_id); +CREATE INDEX IF NOT EXISTS salt_returns_fun ON salt.salt_returns (fun); + +CREATE TABLE IF NOT EXISTS salt.jids ( + jid text PRIMARY KEY, + load text +); + +CREATE TABLE IF NOT EXISTS salt.minions ( + minion_id text PRIMARY KEY, + last_fun text +); +CREATE INDEX IF NOT EXISTS minions_last_fun ON salt.minions (last_fun); + +CREATE TABLE IF NOT EXISTS salt.salt_events ( + id timeuuid, + tag text, + alter_time timestamp, + data text, + master_id text, + PRIMARY KEY (id, tag) +) WITH CLUSTERING ORDER BY (tag ASC); +CREATE INDEX tag ON salt.salt_events (tag); +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Required python modules: cassandra\-driver +.sp +To use the cassandra returner, append \(aq\-\-return cassandra_cql\(aq to the salt command. ex: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return_cql cassandra +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note: if your Cassandra instance has not been tuned much you may benefit from +altering some timeouts in \fIcassandra.yaml\fP like so: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# How long the coordinator should wait for read operations to complete +read_request_timeout_in_ms: 5000 +# How long the coordinator should wait for seq or index scans to complete +range_request_timeout_in_ms: 20000 +# How long the coordinator should wait for writes to complete +write_request_timeout_in_ms: 20000 +# How long the coordinator should wait for counter writes to complete +counter_write_request_timeout_in_ms: 10000 +# How long a coordinator should continue to retry a CAS operation +# that contends with other proposals for the same row +cas_contention_timeout_in_ms: 5000 +# How long the coordinator should wait for truncates to complete +# (This can be much longer, because unless auto_snapshot is disabled +# we need to flush first so we can snapshot before removing the data.) +truncate_request_timeout_in_ms: 60000 +# The default timeout for other, miscellaneous operations +request_timeout_in_ms: 20000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +As always, your mileage may vary and your Cassandra cluster may have different +needs. SaltStack has seen situations where these timeouts can resolve +some stacktraces that appear to come from the Datastax Python driver. +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.event_return(events) +Return event to one of potentially many clustered cassandra nodes +.sp +Requires that configuration be enabled via \(aqevent_return\(aq +option in master config. +.sp +Cassandra does not support an auto\-increment feature due to the +highly inefficient nature of creating a monotonically increasing +number across all nodes in a distributed database. Each event +will be assigned a uuid by the connecting client. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.prep_jid(nocache, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.returner(ret) +Return data to one of potentially many clustered cassandra nodes +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.save_load(jid, load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.cassandra_cql_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.couchbase_return +.sp +Simple returner for Couchbase. Optional configuration +settings are listed below, along with sane defaults. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +couchbase.host: \(aqsalt\(aq +couchbase.port: 8091 +couchbase.bucket: \(aqsalt\(aq +couchbase.ttl: 86400 +couchbase.password: \(aqpassword\(aq +couchbase.skip_verify_views: False +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the couchbase returner, append \(aq\-\-return couchbase\(aq to the salt command. ex: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchbase +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_kwargs \(aq{\(dqbucket\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +All of the return data will be stored in documents as follows: +.SS JID +.sp +load: load obj +tgt_minions: list of minions targeted +nocache: should we not cache the return data +.SS JID/MINION_ID +.sp +return: return_data +full_ret: full load of job return +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.prep_jid(nocache=False, passed_jid=None) +Return a job id and prepare the job id directory +This is the function responsible for making sure jids don\(aqt collide (unless +its passed a jid) +So do what you have to do to make sure that stays the case +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.returner(load) +Return data to couchbase bucket +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.save_load(jid, clear_load, minion=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchbase_return.save_minions(jid, minions, syndic_id=None) +Save/update the minion list for a given jid. The syndic_id argument is +included for API compatibility only. +.UNINDENT +.SS salt.returners.couchdb_return +.sp +Simple returner for CouchDB. Optional configuration +settings are listed below, along with sane defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +couchdb.db: \(aqsalt\(aq +couchdb.url: \(aqhttp://salt:5984/\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.couchdb.db: \(aqsalt\(aq +alternative.couchdb.url: \(aqhttp://salt:5984/\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the couchdb returner, append \fB\-\-return couchdb\fP to the salt command. Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchdb +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \fB\-\-return_config alternative\fP to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SS On concurrent database access +.sp +As this returner creates a couchdb document with the salt job id as document id +and as only one document with a given id can exist in a given couchdb database, +it is advised for most setups that every minion be configured to write to it own +database (the value of \fBcouchdb.db\fP may be suffixed with the minion id), +otherwise multi\-minion targeting can lead to losing output: +.INDENT 0.0 +.IP \(bu 2 +the first returning minion is able to create a document in the database +.IP \(bu 2 +other minions fail with \fB{\(aqerror\(aq: \(aqHTTP Error 409: Conflict\(aq}\fP +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.ensure_views() +This function makes sure that all the views that should +exist in the design document do exist. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.get_fun(fun) +Return a dict with key being minion and value +being the job details of the last run of function \(aqfun\(aq. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.get_jid(jid) +Get the document with a given JID. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.get_jids() +List all the jobs that we have.. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.get_minions() +Return a list of minion identifiers from a request of the view. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.get_valid_salt_views() +Returns a dict object of views that should be +part of the salt design document. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.returner(ret) +Take in the return and shove it into the couchdb database. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.couchdb_return.set_salt_view() +Helper function that sets the salt design +document. Uses get_valid_salt_views and some hardcoded values. +.UNINDENT +.SS salt.returners.elasticsearch_return +.sp +Return data to an elasticsearch server for indexing. +.INDENT 0.0 +.TP +.B maintainer +Jurnell Cockhren <\fI\%jurnell.cockhren@sophicware.com\fP>, Arnold Bechtoldt <\fI\%mail@arnoldbechtoldt.com\fP> +.TP +.B maturity +New +.TP +.B depends +\fI\%elasticsearch\-py\fP +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner the elasticsearch python client must be installed +on the desired minions (all or some subset). +.sp +Please see documentation of \fI\%elasticsearch execution module\fP +for a valid connection configuration. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The index that you wish to store documents will be created by Elasticsearch automatically if +doesn\(aqt exist yet. It is highly recommended to create predefined index templates with appropriate mapping(s) +that will be used by Elasticsearch upon index creation. Otherwise you will have problems as described in #20826. +.UNINDENT +.UNINDENT +.sp +To use the returner per salt call: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return elasticsearch +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In order to have the returner apply to all minions: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ext_job_cache: elasticsearch +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B Minion configuration: +.INDENT 7.0 +.TP +.B debug_returner_payload\(aq: False +Output the payload being posted to the log file in debug mode +.TP +.B doc_type: \(aqdefault\(aq +Document type to use for normal return messages +.TP +.B functions_blacklist +Optional list of functions that should not be returned to elasticsearch +.TP +.B index_date: False +Use a dated index (e.g. \-2016.11.29) +.TP +.B master_event_index: \(aqsalt\-master\-event\-cache\(aq +Index to use when returning master events +.TP +.B master_event_doc_type: \(aqefault\(aq +Document type to use got master events +.TP +.B master_job_cache_index: \(aqsalt\-master\-job\-cache\(aq +Index to use for master job cache +.TP +.B master_job_cache_doc_type: \(aqdefault\(aq +Document type to use for master job cache +.TP +.B number_of_shards: 1 +Number of shards to use for the indexes +.TP +.B number_of_replicas: 0 +Number of replicas to use for the indexes +.UNINDENT +.sp +NOTE: The following options are valid for \(aqstate.apply\(aq, \(aqstate.sls\(aq and \(aqstate.highstate\(aq functions only. +.INDENT 7.0 +.TP +.B states_count: False +Count the number of states which succeeded or failed and return it in top\-level item called \(aqcounts\(aq. +States reporting None (i.e. changes would be made but it ran in test mode) are counted as successes. +.TP +.B states_order_output: False +Prefix the state UID (e.g. file_|\-yum_configured_|\-/etc/yum.conf_|\-managed) with a zero\-padded version +of the \(aq__run_num__\(aq value to allow for easier sorting. Also store the state function (i.e. file.managed) +into a new key \(aq_func\(aq. Change the index to be \(aq\-ordered\(aq (e.g. salt\-state_apply\-ordered). +.TP +.B states_single_index: False +Store results for state.apply, state.sls and state.highstate in the salt\-state_apply index +(or \-ordered/\-) indexes if enabled +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +elasticsearch: + hosts: + \- \(dq10.10.10.10:9200\(dq + \- \(dq10.10.10.11:9200\(dq + \- \(dq10.10.10.12:9200\(dq + index_date: True + number_of_shards: 5 + number_of_replicas: 1 + debug_returner_payload: True + states_count: True + states_order_output: True + states_single_index: True + functions_blacklist: + \- test.ping + \- saltutil.find_job +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.elasticsearch_return.event_return(events) +Return events to Elasticsearch +.sp +Requires that the \fIevent_return\fP configuration be set in master config. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.elasticsearch_return.get_load(jid) +Return the load data that marks a specified jid +.sp +New in version 2015.8.1. + +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.elasticsearch_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.elasticsearch_return.returner(ret) +Process the return from Salt +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.elasticsearch_return.save_load(jid, load, minions=None) +Save the load to the specified jid id +.sp +New in version 2015.8.1. + +.UNINDENT +.SS salt.returners.etcd_return +.sp +Return data to an etcd server or cluster +.INDENT 0.0 +.TP +.B depends +.INDENT 7.0 +.IP \(bu 2 +python\-etcd or etcd3\-py +.UNINDENT +.UNINDENT +.sp +In order to return to an etcd server, a profile should be created in the master +configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +my_etcd_config: + etcd.host: 127.0.0.1 + etcd.port: 2379 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +It is technically possible to configure etcd without using a profile, but this +is not considered to be a best practice, especially when multiple etcd servers +or clusters are available. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.host: 127.0.0.1 +etcd.port: 2379 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In order to choose whether to use etcd API v2 or v3, you can put the following +configuration option in the same place as your etcd configuration. This option +defaults to true, meaning you will use v2 unless you specify otherwise. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.require_v2: True +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +When using API v3, there are some specific options available to be configured +within your etcd profile. They are defaulted to the following... +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.encode_keys: False +etcd.encode_values: True +etcd.raw_keys: False +etcd.raw_values: False +etcd.unicode_errors: \(dqsurrogateescape\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBetcd.encode_keys\fP indicates whether you want to pre\-encode keys using msgpack before +adding them to etcd. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you set \fBetcd.encode_keys\fP to \fBTrue\fP, all recursive functionality will no longer work. +This includes \fBtree\fP and \fBls\fP and all other methods if you set \fBrecurse\fP/\fBrecursive\fP to \fBTrue\fP\&. +This is due to the fact that when encoding with msgpack, keys like \fB/salt\fP and \fB/salt/stack\fP will have +differing byte prefixes, and etcd v3 searches recursively using prefixes. +.UNINDENT +.UNINDENT +.sp +\fBetcd.encode_values\fP indicates whether you want to pre\-encode values using msgpack before +adding them to etcd. This defaults to \fBTrue\fP to avoid data loss on non\-string values wherever possible. +.sp +\fBetcd.raw_keys\fP determines whether you want the raw key or a string returned. +.sp +\fBetcd.raw_values\fP determines whether you want the raw value or a string returned. +.sp +\fBetcd.unicode_errors\fP determines what you policy to follow when there are encoding/decoding errors. +.sp +Additionally, two more options must be specified in the top\-level configuration +in order to use the etcd returner: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.returner: my_etcd_config +etcd.returner_root: /salt/return +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBetcd.returner\fP option specifies which configuration profile to use. The +\fBetcd.returner_root\fP option specifies the path inside etcd to use as the root +of the returner system. +.sp +Once the etcd options are configured, the returner may be used: +.sp +CLI Example: +.INDENT 0.0 +.INDENT 3.5 +salt \(aq*\(aq test.ping \-\-return etcd +.UNINDENT +.UNINDENT +.sp +A username and password can be set: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.username: larry # Optional; requires etcd.password to be set +etcd.password: 123pass # Optional; requires etcd.username to be set +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can also set a TTL (time to live) value for the returner: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.ttl: 5 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Authentication with username and password, and ttl, currently requires the +\fBmaster\fP branch of \fBpython\-etcd\fP\&. +.sp +You may also specify different roles for read and write operations. First, +create the profiles as specified above. Then add: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +etcd.returner_read_profile: my_etcd_read +etcd.returner_write_profile: my_etcd_write +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.clean_old_jobs() +Included for API consistency +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.returner(ret) +Return data to an etcd server or cluster +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.save_load(jid, load, minions=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.etcd_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.highstate_return +.sp +Return the results of a highstate (or any other state function that returns +data in a compatible format) via an HTML email or HTML file. +.sp +New in version 2017.7.0. + +.sp +Similar results can be achieved by using the smtp returner with a custom template, +except an attempt at writing such a template for the complex data structure +returned by highstate function had proven to be a challenge, not to mention +that the smtp module doesn\(aqt support sending HTML mail at the moment. +.sp +The main goal of this returner was to produce an easy to read email similar +to the output of highstate outputter used by the CLI. +.sp +This returner could be very useful during scheduled executions, +but could also be useful for communicating the results of a manual execution. +.sp +Returner configuration is controlled in a standard fashion either via +highstate group or an alternatively named group. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq state.highstate \-\-return highstate +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config config\-name\(aq +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq state.highstate \-\-return highstate \-\-return_config simple +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Here is an example of what the configuration might look like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +simple.highstate: + report_failures: True + report_changes: True + report_everything: False + failure_function: pillar.items + success_function: pillar.items + report_format: html + report_delivery: smtp + smtp_success_subject: \(aqsuccess minion {id} on host {host}\(aq + smtp_failure_subject: \(aqfailure minion {id} on host {host}\(aq + smtp_server: smtp.example.com + smtp_recipients: saltusers@example.com, devops@example.com + smtp_sender: salt@example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fIreport_failures\fP, \fIreport_changes\fP, and \fIreport_everything\fP flags provide +filtering of the results. If you want an email to be sent every time, then +\fIreport_everything\fP is your choice. If you want to be notified only when +changes were successfully made use \fIreport_changes\fP\&. And \fIreport_failures\fP will +generate an email if there were failures. +.sp +The configuration allows you to run a salt module function in case of +success (\fIsuccess_function\fP) or failure (\fIfailure_function\fP). +.sp +Any salt function, including ones defined in the _module folder of your salt +repo, could be used here and its output will be displayed under the \(aqextra\(aq +heading of the email. +.sp +Supported values for \fIreport_format\fP are html, json, and yaml. The latter two +are typically used for debugging purposes, but could be used for applying +a template at some later stage. +.sp +The values for \fIreport_delivery\fP are smtp or file. In case of file delivery +the only other applicable option is \fIfile_output\fP\&. +.sp +In case of smtp delivery, smtp_* options demonstrated by the example above +could be used to customize the email. +.sp +As you might have noticed, the success and failure subjects contain {id} and {host} +values. Any other grain name could be used. As opposed to using +{{grains[\(aqid\(aq]}}, which will be rendered by the master and contain master\(aqs +values at the time of pillar generation, these will contain minion values at +the time of execution. +.INDENT 0.0 +.TP +.B salt.returners.highstate_return.returner(ret) +Check highstate return information and possibly fire off an email +or save a file. +.UNINDENT +.SS salt.returners.influxdb_return +.sp +Return data to an influxdb server. +.sp +New in version 2015.8.0. + +.sp +To enable this returner the minion will need the python client for influxdb +installed and the following values configured in the minion or master +config, these are the defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +influxdb.db: \(aqsalt\(aq +influxdb.user: \(aqsalt\(aq +influxdb.password: \(aqsalt\(aq +influxdb.host: \(aqlocalhost\(aq +influxdb.port: 8086 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.influxdb.db: \(aqsalt\(aq +alternative.influxdb.user: \(aqsalt\(aq +alternative.influxdb.password: \(aqsalt\(aq +alternative.influxdb.host: \(aqlocalhost\(aq +alternative.influxdb.port: 6379 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the influxdb returner, append \(aq\-\-return influxdb\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return influxdb +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.returner(ret) +Return data to a influxdb data store +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.save_load(jid, load, minions=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.influxdb_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.kafka_return +.sp +Return data to a Kafka topic +.INDENT 0.0 +.TP +.B maintainer +Justin Desilets (\fI\%justin.desilets@gmail.com\fP) +.TP +.B maturity +20181119 +.TP +.B depends +confluent\-kafka +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner install confluent\-kafka and enable the following +settings in the minion config: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B returner.kafka.bootstrap: +.INDENT 7.0 +.IP \(bu 2 +\(dqserver1:9092\(dq +.IP \(bu 2 +\(dqserver2:9092\(dq +.IP \(bu 2 +\(dqserver3:9092\(dq +.UNINDENT +.UNINDENT +.sp +returner.kafka.topic: \(aqtopic\(aq +.UNINDENT +.UNINDENT +.sp +To use the kafka returner, append \fI\-\-return kafka\fP to the Salt command, eg; +.INDENT 0.0 +.INDENT 3.5 +salt \(aq*\(aq test.ping \-\-return kafka +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.kafka_return.returner(ret) +Return information to a Kafka server +.UNINDENT +.SS salt.returners.librato_return +.sp +Salt returner to return highstate stats to Librato +.sp +To enable this returner the minion will need the Librato +client importable on the Python path and the following +values configured in the minion or master config. +.sp +The Librato python client can be found at: +\fI\%https://github.com/librato/python\-librato\fP +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +librato.email: example@librato.com +librato.api_token: abc12345def +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This return supports multi\-dimension metrics for Librato. To enable +support for more metrics, the tags JSON object can be modified to include +other tags. +.sp +Adding EC2 Tags example: +If ec2_tags:region were desired within the tags for multi\-dimension. The tags +could be modified to include the ec2 tags. Multiple dimensions are added simply +by adding more tags to the submission. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pillar_data = __salt__[\(aqpillar.raw\(aq]() +q.add(metric.name, value, tags={\(aqName\(aq: ret[\(aqid\(aq],\(aqRegion\(aq: pillar_data[\(aqec2_tags\(aq][\(aqName\(aq]}) +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.librato_return.returner(ret) +Parse the return data and return metrics to Librato. +.UNINDENT +.SS salt.returners.local +.sp +The local returner is used to test the returner interface, it just prints the +return data to the console to verify that it is being passed properly +.sp +To use the local returner, append \(aq\-\-return local\(aq to the salt command. ex: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return local +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local.event_return(event) +Print event return data to the terminal to verify functionality +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local.returner(ret) +Print the return data to the terminal to verify functionality +.UNINDENT +.SS salt.returners.local_cache +.sp +Return data to local job cache +.INDENT 0.0 +.TP +.B salt.returners.local_cache.clean_old_jobs() +Clean out the old jobs from the job cache +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.get_endtime(jid) +Retrieve the stored endtime for a given job +.sp +Returns False if no endtime is present +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.get_jids() +Return a dict mapping all job ids to job information +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.get_jids_filter(count, filter_find_job=True) +Return a list of all jobs information filtered by the given criteria. +:param int count: show not more than the count of most recent jobs +:param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.load_reg() +Load the register from msgpack files +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.prep_jid(nocache=False, passed_jid=None, recurse_count=0) +Return a job id and prepare the job id directory. +.sp +This is the function responsible for making sure jids don\(aqt collide (unless +it is passed a jid). +So do what you have to do to make sure that stays the case +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.returner(load) +Return data to the local job cache +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.save_load(jid, clear_load, minions=None, recurse_count=0) +Save the load to the specified jid +.sp +minions argument is to provide a pre\-computed list of matched minions for +the job, for cases when this function can\(aqt compute that list itself (such +as for salt\-ssh) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.save_minions(jid, minions, syndic_id=None) +Save/update the serialized list of minions for a given job +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.save_reg(data) +Save the register to msgpack files +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.local_cache.update_endtime(jid, time) +Update (or store) the end time for a given job +.sp +Endtime is stored as a plain text string +.UNINDENT +.SS salt.returners.mattermost_returner +.sp +Return salt data via mattermost +.sp +New in version 2017.7.0. + +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mattermost.hook (required) +mattermost.username (optional) +mattermost.channel (optional) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mattermost.channel +mattermost.hook +mattermost.username +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +mattermost settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mattermost: + channel: RoomName + hook: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + username: user +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the mattermost returner, append \(aq\-\-return mattermost\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mattermost +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(aqkey:\(aq: \(aqvalue\(aq}\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mattermost \-\-return_kwargs \(aq{\(aqchannel\(aq: \(aq#random\(aq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mattermost_returner.event_return(events) +Send the events to a mattermost room. +.INDENT 7.0 +.TP +.B Parameters +\fBevents\fP \-\- List of events +.TP +.B Returns +Boolean if messages were sent successfully. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mattermost_returner.post_message(channel, message, username, api_url, hook) +Send a message to a mattermost room. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBchannel\fP \-\- The room name. +.IP \(bu 2 +\fBmessage\fP \-\- The message to send to the mattermost room. +.IP \(bu 2 +\fBusername\fP \-\- Specify who the message is from. +.IP \(bu 2 +\fBhook\fP \-\- The mattermost hook, if not specified in the configuration. +.UNINDENT +.TP +.B Returns +Boolean if message was sent successfully. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mattermost_returner.returner(ret) +Send an mattermost message with the data +.UNINDENT +.SS salt.returners.memcache_return +.sp +Return data to a memcache server +.sp +To enable this returner the minion will need the python client for memcache +installed and the following values configured in the minion or master +config, these are the defaults. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +memcache.host: \(aqlocalhost\(aq +memcache.port: \(aq11211\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.memcache.host: \(aqlocalhost\(aq +alternative.memcache.port: \(aq11211\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +python2\-memcache uses \(aqlocalhost\(aq and \(aq11211\(aq as syntax on connection. +.sp +To use the memcache returner, append \(aq\-\-return memcache\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return memcache +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return memcache \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return memcache \-\-return_kwargs \(aq{\(dqhost\(dq: \(dqhostname.domain.com\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.returner(ret) +Return data to a memcache data store +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.save_load(jid, load, minions=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.memcache_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.mongo_future_return +.sp +Return data to a mongodb server +.sp +Required python modules: pymongo +.sp +This returner will send data from the minions to a MongoDB server. MongoDB +server can be configured by using host, port, db, user and password settings +or by connection string URI (for pymongo > 2.3). To configure the settings +for your MongoDB server, add the following lines to the minion config files: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongo.db: +mongo.host: +mongo.user: +mongo.password: +mongo.port: 27017 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Or single URI: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongo.uri: URI +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where uri is in the format: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongodb://db1.example.net:27017/mydatabase +mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test +mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +More information on URI format can be found in +\fI\%https://docs.mongodb.com/manual/reference/connection\-string/\fP +.sp +You can also ask for indexes creation on the most common used fields, which +should greatly improve performance. Indexes are not created by default. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongo.indexes: true +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.mongo.db: +alternative.mongo.host: +alternative.mongo.user: +alternative.mongo.password: +alternative.mongo.port: 27017 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Or single URI: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.mongo.uri: URI +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This mongo returner is being developed to replace the default mongodb returner +in the future and should not be considered API stable yet. +.sp +To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.event_return(events) +Return events to Mongodb server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.get_fun(fun) +Return the most recent jobs that have executed the named function +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.get_jid(jid) +Return the return information associated with a jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.get_jids() +Return a list of job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.get_load(jid) +Return the load associated with a given job id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.returner(ret) +Return data to a mongodb server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.save_load(jid, load, minions=None) +Save the load for a given job id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_future_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.mongo_return +.sp +Return data to a mongodb server +.sp +Required python modules: pymongo +.sp +This returner will send data from the minions to a MongoDB server. To +configure the settings for your MongoDB server, add the following lines +to the minion config files. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongo.db: +mongo.host: +mongo.user: +mongo.password: +mongo.port: 27017 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.mongo.db: +alternative.mongo.host: +alternative.mongo.user: +alternative.mongo.password: +alternative.mongo.port: 27017 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo_return +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo_return \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_return.get_fun(fun) +Return the most recent jobs that have executed the named function +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_return.get_jid(jid) +Return the return information associated with a jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_return.returner(ret) +Return data to a mongodb server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mongo_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.multi_returner +.sp +Read/Write multiple returners +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.clean_old_jobs() +Clean out the old jobs from all returners (if you have it) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.get_jid(jid) +Merge the return data from all returners +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.get_jids() +Return all job data from all returners +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.get_load(jid) +Merge the load data from all returners +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.prep_jid(nocache=False, passed_jid=None) +Call both with prep_jid on all returners in multi_returner +.sp +TODO: finish this, what do do when you get different jids from 2 returners... +since our jids are time based, this make this problem hard, because they +aren\(aqt unique, meaning that we have to make sure that no one else got the jid +and if they did we spin to get a new one, which means \(dqlocking\(dq the jid in 2 +returners is non\-trivial +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.returner(load) +Write return to all returners in multi_returner +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.save_load(jid, clear_load, minions=None) +Write load to all returners in multi_returner +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.multi_returner.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.mysql +.sp +Return data to a mysql server +.INDENT 0.0 +.TP +.B maintainer +Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP> +.TP +.B maturity +mature +.TP +.B depends +python\-mysqldb +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner, the minion will need the python client for mysql +installed and the following values configured in the minion or master +config. These are the defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mysql.host: \(aqsalt\(aq +mysql.user: \(aqsalt\(aq +mysql.pass: \(aqsalt\(aq +mysql.db: \(aqsalt\(aq +mysql.port: 3306 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +SSL is optional. The defaults are set to None. If you do not want to use SSL, +either exclude these options or set them to None. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mysql.ssl_ca: None +mysql.ssl_cert: None +mysql.ssl_key: None +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration +with \fIalternative.\fP\&. Any values not found in the alternative configuration will +be pulled from the default location. As stated above, SSL configuration is +optional. The following ssl options are simply for illustration purposes: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.mysql.host: \(aqsalt\(aq +alternative.mysql.user: \(aqsalt\(aq +alternative.mysql.pass: \(aqsalt\(aq +alternative.mysql.db: \(aqsalt\(aq +alternative.mysql.port: 3306 +alternative.mysql.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq +alternative.mysql.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq +alternative.mysql.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Should you wish the returner data to be cleaned out every so often, set +\fIkeep_jobs_seconds\fP to the number of hours for the jobs to live in the +tables. Setting it to \fI0\fP will cause the data to stay in the tables. The +default setting for \fIkeep_jobs_seconds\fP is set to \fI86400\fP\&. +.sp +Should you wish to archive jobs in a different table for later processing, +set \fIarchive_jobs\fP to True. Salt will create 3 archive tables +.INDENT 0.0 +.IP \(bu 2 +\fIjids_archive\fP +.IP \(bu 2 +\fIsalt_returns_archive\fP +.IP \(bu 2 +\fIsalt_events_archive\fP +.UNINDENT +.sp +and move the contents of \fIjids\fP, \fIsalt_returns\fP, and \fIsalt_events\fP that are +more than \fIkeep_jobs_seconds\fP seconds old to these tables. +.sp +Use the following mysql database schema: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +CREATE DATABASE \(gasalt\(ga + DEFAULT CHARACTER SET utf8 + DEFAULT COLLATE utf8_general_ci; + +USE \(gasalt\(ga; + +\-\- +\-\- Table structure for table \(gajids\(ga +\-\- + +DROP TABLE IF EXISTS \(gajids\(ga; +CREATE TABLE \(gajids\(ga ( + \(gajid\(ga varchar(255) NOT NULL, + \(gaload\(ga mediumtext NOT NULL, + UNIQUE KEY \(gajid\(ga (\(gajid\(ga) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +\-\- +\-\- Table structure for table \(gasalt_returns\(ga +\-\- + +DROP TABLE IF EXISTS \(gasalt_returns\(ga; +CREATE TABLE \(gasalt_returns\(ga ( + \(gafun\(ga varchar(50) NOT NULL, + \(gajid\(ga varchar(255) NOT NULL, + \(gareturn\(ga mediumtext NOT NULL, + \(gaid\(ga varchar(255) NOT NULL, + \(gasuccess\(ga varchar(10) NOT NULL, + \(gafull_ret\(ga mediumtext NOT NULL, + \(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + KEY \(gaid\(ga (\(gaid\(ga), + KEY \(gajid\(ga (\(gajid\(ga), + KEY \(gafun\(ga (\(gafun\(ga) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +\-\- +\-\- Table structure for table \(gasalt_events\(ga +\-\- + +DROP TABLE IF EXISTS \(gasalt_events\(ga; +CREATE TABLE \(gasalt_events\(ga ( +\(gaid\(ga BIGINT NOT NULL AUTO_INCREMENT, +\(gatag\(ga varchar(255) NOT NULL, +\(gadata\(ga mediumtext NOT NULL, +\(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +\(gamaster_id\(ga varchar(255) NOT NULL, +PRIMARY KEY (\(gaid\(ga), +KEY \(gatag\(ga (\(gatag\(ga) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required python modules: MySQLdb +.sp +To use the mysql returner, append \(aq\-\-return mysql\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mysql +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mysql \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return mysql \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.clean_old_jobs() +Called in the master\(aqs event loop every loop_interval. Archives and/or +deletes the events and job details from the database. +:return: +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.event_return(events) +Return event to mysql server +.sp +Requires that configuration be enabled via \(aqevent_return\(aq +option in master config. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_jids_filter(count, filter_find_job=True) +Return a list of all job ids +:param int count: show not more than the count of most recent jobs +:param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.returner(ret) +Return data to a mysql server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.save_load(jid, load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.mysql.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.nagios_nrdp_return +.sp +Return salt data to Nagios +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nagios.url (required) +nagios.token (required) +nagios.service (optional) +nagios.check_type (optional) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +nagios.url +nagios.token +nagios.service +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Nagios settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + nagios: + url: http://localhost/nrdp + token: r4nd0mt0k3n + service: service\-check + + alternative.nagios: + url: http://localhost/nrdp + token: r4nd0mt0k3n + service: another\-service\-check + +To use the Nagios returner, append \(aq\-\-return nagios\(aq to the salt command. ex: + +\&.. code\-block:: bash + + salt \(aq*\(aq test.ping \-\-return nagios + +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: + + salt \(aq*\(aq test.ping \-\-return nagios \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return nagios \-\-return_kwargs \(aq{\(dqservice\(dq: \(dqservice\-name\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.nagios_nrdp_return.returner(ret) +Send a message to Nagios with the data +.UNINDENT +.SS salt.returners.odbc +.sp +Return data to an ODBC compliant server. This driver was +developed with Microsoft SQL Server in mind, but theoretically +could be used to return data to any compliant ODBC database +as long as there is a working ODBC driver for it on your +minion platform. +.INDENT 0.0 +.TP +.B maintainer +.INDENT 7.0 +.IP C. 3 +.INDENT 3.0 +.IP R. 3 +Oldham (\fI\%cr@saltstack.com\fP) +.UNINDENT +.UNINDENT +.TP +.B maturity +New +.TP +.B depends +unixodbc, pyodbc, freetds (for SQL Server) +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner the minion will need +.sp +On Linux: +.INDENT 0.0 +.INDENT 3.5 +unixodbc (\fI\%http://www.unixodbc.org\fP) +pyodbc (\fIpip install pyodbc\fP) +The FreeTDS ODBC driver for SQL Server (\fI\%http://www.freetds.org\fP) +or another compatible ODBC driver +.UNINDENT +.UNINDENT +.sp +On Windows: +.INDENT 0.0 +.INDENT 3.5 +TBD +.UNINDENT +.UNINDENT +.sp +unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and +/etc/odbc.ini. +.sp +/etc/odbcinst.ini: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[TDS] +Description=TDS +Driver=/usr/lib/x86_64\-linux\-gnu/odbc/libtdsodbc.so +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +(Note the above Driver line needs to point to the location of the FreeTDS +shared library. This example is for Ubuntu 14.04.) +.sp +/etc/odbc.ini: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[TS] +Description = \(dqSalt Returner\(dq +Driver=TDS +Server = +Port = 1433 +Database = salt +Trace = No +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Also you need the following values configured in the minion or master config. +Configure as you see fit: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +returner.odbc.dsn: \(aqTS\(aq +returner.odbc.user: \(aqsalt\(aq +returner.odbc.passwd: \(aqsalt\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.returner.odbc.dsn: \(aqTS\(aq +alternative.returner.odbc.user: \(aqsalt\(aq +alternative.returner.odbc.passwd: \(aqsalt\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Running the following commands against Microsoft SQL Server in the desired +database as the appropriate user should create the database tables +correctly. Replace with equivalent SQL for other ODBC\-compliant servers +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + \-\- + \-\- Table structure for table \(aqjids\(aq + \-\- + + if OBJECT_ID(\(aqdbo.jids\(aq, \(aqU\(aq) is not null + DROP TABLE dbo.jids + + CREATE TABLE dbo.jids ( + jid varchar(255) PRIMARY KEY, + load varchar(MAX) NOT NULL + ); + + \-\- + \-\- Table structure for table \(aqsalt_returns\(aq + \-\- + IF OBJECT_ID(\(aqdbo.salt_returns\(aq, \(aqU\(aq) IS NOT NULL + DROP TABLE dbo.salt_returns; + + CREATE TABLE dbo.salt_returns ( + added datetime not null default (getdate()), + fun varchar(100) NOT NULL, + jid varchar(255) NOT NULL, + retval varchar(MAX) NOT NULL, + id varchar(255) NOT NULL, + success bit default(0) NOT NULL, + full_ret varchar(MAX) + ); + + CREATE INDEX salt_returns_added on dbo.salt_returns(added); + CREATE INDEX salt_returns_id on dbo.salt_returns(id); + CREATE INDEX salt_returns_jid on dbo.salt_returns(jid); + CREATE INDEX salt_returns_fun on dbo.salt_returns(fun); + +To use this returner, append \(aq\-\-return odbc\(aq to the salt command. + +\&.. code\-block:: bash + + salt \(aq*\(aq status.diskusage \-\-return odbc + +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. + +\&.. versionadded:: 2015.5.0 + +\&.. code\-block:: bash + + salt \(aq*\(aq test.ping \-\-return odbc \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return odbc \-\-return_kwargs \(aq{\(dqdsn\(dq: \(dqdsn\-name\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.returner(ret) +Return data to an odbc server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.save_load(jid, load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.odbc.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.pgjsonb +.sp +Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type +.INDENT 0.0 +.TP +.B maintainer +Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP>, C. R. Oldham <\fI\%cr@saltstack.com\fP> +.TP +.B maturity +Stable +.TP +.B depends +python\-psycopg2 +.TP +.B platform +all +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There are three PostgreSQL returners. Any can function as an external +\fI\%master job cache\fP\&. but each has different +features. SaltStack recommends +\fI\%returners.pgjsonb\fP if you are working with +a version of PostgreSQL that has the appropriate native binary JSON types. +Otherwise, review +\fI\%returners.postgres\fP and +\fI\%returners.postgres_local_cache\fP +to see which module best suits your particular needs. +.UNINDENT +.UNINDENT +.sp +To enable this returner, the minion will need the python client for PostgreSQL +installed and the following values configured in the minion or master +config. These are the defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +returner.pgjsonb.host: \(aqsalt\(aq +returner.pgjsonb.user: \(aqsalt\(aq +returner.pgjsonb.pass: \(aqsalt\(aq +returner.pgjsonb.db: \(aqsalt\(aq +returner.pgjsonb.port: 5432 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +SSL is optional. The defaults are set to None. If you do not want to use SSL, +either exclude these options or set them to None. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +returner.pgjsonb.sslmode: None +returner.pgjsonb.sslcert: None +returner.pgjsonb.sslkey: None +returner.pgjsonb.sslrootcert: None +returner.pgjsonb.sslcrl: None +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 2017.5.0. + +.sp +Alternative configuration values can be used by prefacing the configuration +with \fIalternative.\fP\&. Any values not found in the alternative configuration will +be pulled from the default location. As stated above, SSL configuration is +optional. The following ssl options are simply for illustration purposes: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.pgjsonb.host: \(aqsalt\(aq +alternative.pgjsonb.user: \(aqsalt\(aq +alternative.pgjsonb.pass: \(aqsalt\(aq +alternative.pgjsonb.db: \(aqsalt\(aq +alternative.pgjsonb.port: 5432 +alternative.pgjsonb.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq +alternative.pgjsonb.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq +alternative.pgjsonb.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Should you wish the returner data to be cleaned out every so often, set +\fBkeep_jobs_seconds\fP to the number of seconds for the jobs to live in the tables. +Setting it to \fB0\fP or leaving it unset will cause the data to stay in the tables. +.sp +Should you wish to archive jobs in a different table for later processing, +set \fBarchive_jobs\fP to True. Salt will create 3 archive tables; +.INDENT 0.0 +.IP \(bu 2 +\fBjids_archive\fP +.IP \(bu 2 +\fBsalt_returns_archive\fP +.IP \(bu 2 +\fBsalt_events_archive\fP +.UNINDENT +.sp +and move the contents of \fBjids\fP, \fBsalt_returns\fP, and \fBsalt_events\fP that are +more than \fBkeep_jobs_seconds\fP seconds old to these tables. +.sp +New in version 2019.2.0. + +.sp +Use the following Pg database schema: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +CREATE DATABASE salt + WITH ENCODING \(aqutf\-8\(aq; + +\-\- +\-\- Table structure for table \(gajids\(ga +\-\- +DROP TABLE IF EXISTS jids; +CREATE TABLE jids ( + jid varchar(255) NOT NULL primary key, + load jsonb NOT NULL +); +CREATE INDEX idx_jids_jsonb on jids + USING gin (load) + WITH (fastupdate=on); + +\-\- +\-\- Table structure for table \(gasalt_returns\(ga +\-\- + +DROP TABLE IF EXISTS salt_returns; +CREATE TABLE salt_returns ( + fun varchar(50) NOT NULL, + jid varchar(255) NOT NULL, + return jsonb NOT NULL, + id varchar(255) NOT NULL, + success varchar(10) NOT NULL, + full_ret jsonb NOT NULL, + alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW()); + +CREATE INDEX idx_salt_returns_id ON salt_returns (id); +CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); +CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); +CREATE INDEX idx_salt_returns_return ON salt_returns + USING gin (return) with (fastupdate=on); +CREATE INDEX idx_salt_returns_full_ret ON salt_returns + USING gin (full_ret) with (fastupdate=on); + +\-\- +\-\- Table structure for table \(gasalt_events\(ga +\-\- + +DROP TABLE IF EXISTS salt_events; +DROP SEQUENCE IF EXISTS seq_salt_events_id; +CREATE SEQUENCE seq_salt_events_id; +CREATE TABLE salt_events ( + id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), + tag varchar(255) NOT NULL, + data jsonb NOT NULL, + alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + master_id varchar(255) NOT NULL); + +CREATE INDEX idx_salt_events_tag on + salt_events (tag); +CREATE INDEX idx_salt_events_data ON salt_events + USING gin (data) with (fastupdate=on); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required python modules: Psycopg2 +.sp +To use this returner, append \(aq\-\-return pgjsonb\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return pgjsonb +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.clean_old_jobs() +Called in the master\(aqs event loop every loop_interval. Archives and/or +deletes the events and job details from the database. +:return: +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.event_return(events) +Return event to Pg server +.sp +Requires that configuration be enabled via \(aqevent_return\(aq +option in master config. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.returner(ret) +Return data to a Pg server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.save_load(jid, load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pgjsonb.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.postgres +.sp +Return data to a postgresql server +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There are three PostgreSQL returners. Any can function as an external +\fI\%master job cache\fP\&. but each has different +features. SaltStack recommends +\fI\%returners.pgjsonb\fP if you are working with +a version of PostgreSQL that has the appropriate native binary JSON types. +Otherwise, review +\fI\%returners.postgres\fP and +\fI\%returners.postgres_local_cache\fP +to see which module best suits your particular needs. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B maintainer +None +.TP +.B maturity +New +.TP +.B depends +psycopg2 +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner the minion will need the psycopg2 installed and +the following values configured in the minion or master config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +returner.postgres.host: \(aqsalt\(aq +returner.postgres.user: \(aqsalt\(aq +returner.postgres.passwd: \(aqsalt\(aq +returner.postgres.db: \(aqsalt\(aq +returner.postgres.port: 5432 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.returner.postgres.host: \(aqsalt\(aq +alternative.returner.postgres.user: \(aqsalt\(aq +alternative.returner.postgres.passwd: \(aqsalt\(aq +alternative.returner.postgres.db: \(aqsalt\(aq +alternative.returner.postgres.port: 5432 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Running the following commands as the postgres user should create the database +correctly: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +psql << EOF +CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; +CREATE DATABASE salt WITH OWNER salt; +EOF + +psql \-h localhost \-U salt << EOF +\-\- +\-\- Table structure for table \(aqjids\(aq +\-\- + +DROP TABLE IF EXISTS jids; +CREATE TABLE jids ( + jid varchar(20) PRIMARY KEY, + load text NOT NULL +); + +\-\- +\-\- Table structure for table \(aqsalt_returns\(aq +\-\- + +DROP TABLE IF EXISTS salt_returns; +CREATE TABLE salt_returns ( + fun varchar(50) NOT NULL, + jid varchar(255) NOT NULL, + return text NOT NULL, + full_ret text, + id varchar(255) NOT NULL, + success varchar(10) NOT NULL, + alter_time TIMESTAMP WITH TIME ZONE DEFAULT now() +); + +CREATE INDEX idx_salt_returns_id ON salt_returns (id); +CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); +CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); +CREATE INDEX idx_salt_returns_updated ON salt_returns (alter_time); + +\-\- +\-\- Table structure for table \(gasalt_events\(ga +\-\- + +DROP TABLE IF EXISTS salt_events; +DROP SEQUENCE IF EXISTS seq_salt_events_id; +CREATE SEQUENCE seq_salt_events_id; +CREATE TABLE salt_events ( + id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), + tag varchar(255) NOT NULL, + data text NOT NULL, + alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), + master_id varchar(255) NOT NULL +); + +CREATE INDEX idx_salt_events_tag on salt_events (tag); + +EOF +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required python modules: psycopg2 +.sp +To use the postgres returner, append \(aq\-\-return postgres\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return postgres +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return postgres \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return postgres \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.event_return(events) +Return event to Pg server +.sp +Requires that configuration be enabled via \(aqevent_return\(aq +option in master config. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.returner(ret) +Return data to a postgres server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.save_load(jid, load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.postgres_local_cache +.sp +Use a postgresql server for the master job cache. This helps the job cache to +cope with scale. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +There are three PostgreSQL returners. Any can function as an external +\fI\%master job cache\fP\&. but each has different +features. SaltStack recommends +\fI\%returners.pgjsonb\fP if you are working with +a version of PostgreSQL that has the appropriate native binary JSON types. +Otherwise, review +\fI\%returners.postgres\fP and +\fI\%returners.postgres_local_cache\fP +to see which module best suits your particular needs. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B maintainer +\fI\%gjredelinghuys@gmail.com\fP +.TP +.B maturity +Stable +.TP +.B depends +psycopg2 +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner the minion will need the psycopg2 installed and +the following values configured in the master config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +master_job_cache: postgres_local_cache +master_job_cache.postgres.host: \(aqsalt\(aq +master_job_cache.postgres.user: \(aqsalt\(aq +master_job_cache.postgres.passwd: \(aqsalt\(aq +master_job_cache.postgres.db: \(aqsalt\(aq +master_job_cache.postgres.port: 5432 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Running the following command as the postgres user should create the database +correctly: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +psql << EOF +CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; +CREATE DATABASE salt WITH OWNER salt; +EOF +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In case the postgres database is a remote host, you\(aqll need this command also: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ALTER ROLE salt WITH LOGIN; +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +and then: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +psql \-h localhost \-U salt << EOF +\-\- +\-\- Table structure for table \(aqjids\(aq +\-\- + +DROP TABLE IF EXISTS jids; +CREATE TABLE jids ( + jid varchar(20) PRIMARY KEY, + started TIMESTAMP WITH TIME ZONE DEFAULT now(), + tgt_type text NOT NULL, + cmd text NOT NULL, + tgt text NOT NULL, + kwargs text NOT NULL, + ret text NOT NULL, + username text NOT NULL, + arg text NOT NULL, + fun text NOT NULL +); + +\-\- +\-\- Table structure for table \(aqsalt_returns\(aq +\-\- +\-\- note that \(aqsuccess\(aq must not have NOT NULL constraint, since +\-\- some functions don\(aqt provide it. + +DROP TABLE IF EXISTS salt_returns; +CREATE TABLE salt_returns ( + added TIMESTAMP WITH TIME ZONE DEFAULT now(), + fun text NOT NULL, + jid varchar(20) NOT NULL, + return text NOT NULL, + id text NOT NULL, + success boolean +); +CREATE INDEX ON salt_returns (added); +CREATE INDEX ON salt_returns (id); +CREATE INDEX ON salt_returns (jid); +CREATE INDEX ON salt_returns (fun); + +DROP TABLE IF EXISTS salt_events; +CREATE TABLE salt_events ( + id SERIAL, + tag text NOT NULL, + data text NOT NULL, + alter_time TIMESTAMP WITH TIME ZONE DEFAULT now(), + master_id text NOT NULL +); +CREATE INDEX ON salt_events (tag); +CREATE INDEX ON salt_events (data); +CREATE INDEX ON salt_events (id); +CREATE INDEX ON salt_events (master_id); +EOF +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required python modules: psycopg2 +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.clean_old_jobs() +Clean out the old jobs from the job cache +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.event_return(events) +Return event to a postgres server +.sp +Require that configuration be enabled via \(aqevent_return\(aq +option in master config. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.get_jids() +Return a list of all job ids +For master job cache this also formats the output and returns a string +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.prep_jid(nocache=False, passed_jid=None) +Return a job id and prepare the job id directory +This is the function responsible for making sure jids don\(aqt collide +(unless its passed a jid). So do what you have to do to make sure that +stays the case +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.returner(load) +Return data to a postgres server +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.save_load(jid, clear_load, minions=None) +Save the load to the specified jid id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.postgres_local_cache.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.pushover_returner +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%pushover Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp +Return salt data via pushover (\fI\%http://www.pushover.net\fP) +.sp +New in version 2016.3.0. + +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +pushover.user (required) +pushover.token (required) +pushover.title (optional) +pushover.device (optional) +pushover.priority (optional) +pushover.expire (optional) +pushover.retry (optional) +pushover.profile (optional) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBuser\fP here is your \fBuser key\fP, \fInot\fP the email address you use to +login to pushover.net. +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.pushover.user +alternative.pushover.token +alternative.pushover.title +alternative.pushover.device +alternative.pushover.priority +alternative.pushover.expire +alternative.pushover.retry +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +PushOver settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + pushover: + user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + title: Salt Returner + device: phone + priority: \-1 + expire: 3600 + retry: 5 + + alternative.pushover: + user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + title: Salt Returner + device: phone + priority: 1 + expire: 4800 + retry: 2 + + pushover_profile: + pushover.token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + + pushover: + user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + profile: pushover_profile + + alternative.pushover: + user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + profile: pushover_profile + +To use the PushOver returner, append \(aq\-\-return pushover\(aq to the salt command. ex: + +\&.. code\-block:: bash + + salt \(aq*\(aq test.ping \-\-return pushover + +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: + + salt \(aq*\(aq test.ping \-\-return pushover \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return pushover \-\-return_kwargs \(aq{\(dqtitle\(dq: \(dqSalt is awesome!\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.pushover_returner.returner(ret) +Send an PushOver message with the data +.UNINDENT +.SS salt.returners.rawfile_json +.sp +Take data from salt and \(dqreturn\(dq it into a raw file containing the json, with +one line per event. +.sp +Add the following to the minion or master configuration file. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +rawfile_json.filename: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Default is \fB/var/log/salt/events\fP\&. +.sp +Common use is to log all events on the master. This can generate a lot of +noise, so you may wish to configure batch processing and/or configure the +\fI\%event_return_whitelist\fP or \fI\%event_return_blacklist\fP +to restrict the events that are written. +.INDENT 0.0 +.TP +.B salt.returners.rawfile_json.event_return(events) +Write event data (return data and non\-return data) to file on the master. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.rawfile_json.returner(ret) +Write the return data to a file on the minion. +.UNINDENT +.SS salt.returners.redis_return +.sp +Return data to a redis server +.sp +To enable this returner the minion will need the python client for redis +installed and the following values configured in the minion or master +config, these are the defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +redis.db: \(aq0\(aq +redis.host: \(aqsalt\(aq +redis.port: 6379 +redis.password: \(aq\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 2018.3.1: Alternatively a UNIX socket can be specified by \fIunix_socket_path\fP: + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +redis.db: \(aq0\(aq +redis.unix_socket_path: /var/run/redis/redis.sock +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Cluster Mode Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +redis.db: \(aq0\(aq +redis.cluster_mode: true +redis.cluster.skip_full_coverage_check: true +redis.cluster.startup_nodes: + \- host: redis\-member\-1 + port: 6379 + \- host: redis\-member\-2 + port: 6379 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.redis.db: \(aq0\(aq +alternative.redis.host: \(aqsalt\(aq +alternative.redis.port: 6379 +alternative.redis.password: \(aq\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the redis returner, append \(aq\-\-return redis\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return redis +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return redis \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return redis \-\-return_kwargs \(aq{\(dqdb\(dq: \(dqanother\-salt\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Redis Cluster Mode Options: +.INDENT 0.0 +.TP +.B cluster_mode: \fBFalse\fP +Whether cluster_mode is enabled or not +.TP +.B cluster.startup_nodes: +A list of host, port dictionaries pointing to cluster members. At least one is required +but multiple nodes are better +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +redis.cluster.startup_nodes + \- host: redis\-member\-1 + port: 6379 + \- host: redis\-member\-2 + port: 6379 +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B cluster.skip_full_coverage_check: \fBFalse\fP +Some cluster providers restrict certain redis commands such as CONFIG for enhanced security. +Set this option to true to skip checks that required advanced privileges. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Most cloud hosted redis clusters will require this to be set to \fBTrue\fP +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.clean_old_jobs() +Clean out minions\(aqs return data for old jobs. +.sp +Normally, hset \(aqret:\(aq are saved with a TTL, and will eventually +get cleaned by redis.But for jobs with some very late minion return, the +corresponding hset\(aqs TTL will be refreshed to a too late timestamp, we\(aqll +do manually cleaning here. +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.get_jid(jid) +Return the information returned when the specified job id was executed +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.get_jids() +Return a dict mapping all job ids to job information +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.get_load(jid) +Return the load data that marks a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.returner(ret) +Return data to a redis data store +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.save_load(jid, load, minions=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.redis_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.sentry_return +.sp +Salt returner that reports execution results back to sentry. The returner will +inspect the payload to identify errors and flag them as such. +.sp +Pillar needs something like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +raven: + servers: + \- http://192.168.1.1 + \- https://sentry.example.com + public_key: deadbeefdeadbeefdeadbeefdeadbeef + secret_key: beefdeadbeefdeadbeefdeadbeefdead + project: 1 + tags: + \- os + \- master + \- saltversion + \- cpuarch +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or using a dsn: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +raven: + dsn: https://aaaa:bbbb@app.getsentry.com/12345 + tags: + \- os + \- master + \- saltversion + \- cpuarch +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fI\%https://pypi.python.org/pypi/raven\fP must be installed. +.sp +The pillar can be hidden on sentry return by setting hide_pillar: true. +.sp +The tags list (optional) specifies grains items that will be used as sentry +tags, allowing tagging of events in the sentry ui. +.sp +To report only errors to sentry, set report_errors_only: true. +.INDENT 0.0 +.TP +.B salt.returners.sentry_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sentry_return.returner(ret) +Log outcome to sentry. The returner tries to identify errors and report +them as such. All other messages will be reported at info level. +Failed states will be appended as separate list for convenience. +.UNINDENT +.SS salt.returners.slack_returner +.sp +Return salt data via slack +.sp +New in version 2015.5.0. + +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack.channel (required) +slack.api_key (required) +slack.username (required) +slack.as_user (required to see the profile picture of your bot) +slack.profile (optional) +slack.changes(optional, only show changes and failed states) +slack.only_show_failed(optional, only show failed states) +slack.yaml_format(optional, format the json in yaml format) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack.channel +slack.api_key +slack.username +slack.as_user +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Slack settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack: + channel: RoomName + api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + username: user + as_user: true + +alternative.slack: + room_id: RoomName + api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + from_name: user@email.com + +slack_profile: + slack.api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + slack.from_name: user@email.com + +slack: + profile: slack_profile + channel: RoomName + +alternative.slack: + profile: slack_profile + channel: RoomName +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the Slack returner, append \(aq\-\-return slack\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return slack +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return slack \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return slack \-\-return_kwargs \(aq{\(dqchannel\(dq: \(dq#random\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.slack_returner.returner(ret) +Send an slack message with the data +.UNINDENT +.SS salt.returners.slack_webhook_return +.sp +Return salt data via Slack using Incoming Webhooks +.INDENT 0.0 +.TP +.B codeauthor +\fICarlos D. Álvaro \fP +.UNINDENT +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack_webhook.webhook (required, the webhook id. Just the part after: \(aqhttps://hooks.slack.com/services/\(aq) +slack_webhook.success_title (optional, short title for succeeded states. By default: \(aq{id} | Succeeded\(aq) +slack_webhook.failure_title (optional, short title for failed states. By default: \(aq{id} | Failed\(aq) +slack_webhook.author_icon (optional, a URL that with a small 16x16px image. Must be of type: GIF, JPEG, PNG, and BMP) +slack_webhook.show_tasks (optional, show identifiers for changed and failed tasks. By default: False) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack_webhook.webhook +slack_webhook.success_title +slack_webhook.failure_title +slack_webhook.author_icon +slack_webhook.show_tasks +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Slack settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +slack_webhook: + webhook: T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX + success_title: \(aq[{id}] | Success\(aq + failure_title: \(aq[{id}] | Failure\(aq + author_icon: https://platform.slack\-edge.com/img/default_application_icon.png + show_tasks: true + +alternative.slack_webhook: + webhook: T00000000/C00000000/YYYYYYYYYYYYYYYYYYYYYYYY + show_tasks: false +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the Slack returner, +append \(aq\-\-return slack_webhook\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return slack_webhook +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, +append \(aq\-\-return_config alternative\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return slack_webhook \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.slack_webhook_return.event_return(events) +Send event data to returner function +:param events: The Salt event return +:return: The result of the post +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.slack_webhook_return.returner(ret, **kwargs) +Send a slack message with the data through a webhook +:param ret: The Salt return +:return: The result of the post +.UNINDENT +.SS salt.returners.sms_return +.sp +Return data by SMS. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.TP +.B maintainer +Damian Myerscough +.TP +.B maturity +new +.TP +.B depends +twilio +.TP +.B platform +all +.UNINDENT +.sp +To enable this returner the minion will need the python twilio library +installed and the following values configured in the minion or master +config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +twilio.sid: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq +twilio.token: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq +twilio.to: \(aq+1415XXXXXXX\(aq +twilio.from: \(aq+1650XXXXXXX\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the sms returner, append \(aq\-\-return sms\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return sms +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sms_return.returner(ret) +Return a response in an SMS message +.UNINDENT +.SS salt.returners.smtp_return +.sp +Return salt data via email +.sp +The following fields can be set in the minion conf file. Fields are optional +unless noted otherwise. +.INDENT 0.0 +.IP \(bu 2 +\fBfrom\fP (required) The name/address of the email sender. +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBto\fP (required) The names/addresses of the email recipients; +comma\-delimited. For example: \fByou@example.com,someoneelse@example.com\fP\&. +.UNINDENT +.IP \(bu 2 +\fBhost\fP (required) The SMTP server hostname or address. +.IP \(bu 2 +\fBport\fP The SMTP server port; defaults to \fB25\fP\&. +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBusername\fP The username used to authenticate to the server. If specified a +password is also required. It is recommended but not required to also use +TLS with this option. +.UNINDENT +.IP \(bu 2 +\fBpassword\fP The password used to authenticate to the server. +.IP \(bu 2 +\fBtls\fP Whether to secure the connection using TLS; defaults to \fBFalse\fP +.IP \(bu 2 +\fBsubject\fP The email subject line. +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBfields\fP Which fields from the returned data to include in the subject line +of the email; comma\-delimited. For example: \fBid,fun\fP\&. Please note, \fIthe +subject line is not encrypted\fP\&. +.UNINDENT +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBgpgowner\fP A user\(aqs \fB~/.gpg\fP directory. This must contain a gpg +public key matching the address the mail is sent to. If left unset, no +encryption will be used. Requires \fBpython\-gnupg\fP to be installed. +.UNINDENT +.IP \(bu 2 +\fBtemplate\fP The path to a file to be used as a template for the email body. +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fBrenderer\fP A Salt renderer, or render\-pipe, to use to render the email +template. Default \fBjinja\fP\&. +.UNINDENT +.UNINDENT +.sp +Below is an example of the above settings in a Salt Minion configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +smtp.from: me@example.net +smtp.to: you@example.com +smtp.host: localhost +smtp.port: 1025 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.smtp.username: saltdev +alternative.smtp.password: saltdev +alternative.smtp.tls: True +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the SMTP returner, append \(aq\-\-return smtp\(aq to the \fBsalt\fP command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return smtp +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the \fBsalt\fP command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return smtp \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the +\fBsalt\fP command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return smtp \-\-return_kwargs \(aq{\(dqto\(dq: \(dquser@domain.com\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +An easy way to test the SMTP returner is to use the development SMTP server +built into Python. The command below will start a single\-threaded SMTP server +that prints any email it receives to the console. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +python \-m smtpd \-n \-c DebuggingServer localhost:1025 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +New in version 2016.11.0. + +.sp +It is possible to send emails with selected Salt events by configuring \fBevent_return\fP option +for Salt Master. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +event_return: smtp + +event_return_whitelist: + \- salt/key + +smtp.from: me@example.net +smtp.to: you@example.com +smtp.host: localhost +smtp.subject: \(aqSalt Master {{act}}ed key from Minion ID: {{id}}\(aq +smtp.template: /srv/salt/templates/email.j2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Also you need to create additional file \fB/srv/salt/templates/email.j2\fP with email body template: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +act: {{act}} +id: {{id}} +result: {{result}} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This configuration enables Salt Master to send an email when accepting or rejecting minions keys. +.INDENT 0.0 +.TP +.B salt.returners.smtp_return.event_return(events) +Return event data via SMTP +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.smtp_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.smtp_return.returner(ret) +Send an email with the data +.UNINDENT +.SS salt.returners.splunk +.sp +Send json response data to Splunk via the HTTP Event Collector +Requires the following config values to be specified in config or pillar: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +splunk_http_forwarder: + token: + indexer: + sourcetype: + index: + verify_ssl: true +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Run a test by using \fBsalt\-call test.ping \-\-return splunk\fP +.sp +Written by Scott Pack (github.com/scottjpack) +.INDENT 0.0 +.TP +.B salt.returners.splunk.event_return(events) +Return events to Splunk via the HTTP Event Collector. +Requires the Splunk HTTP Event Collector running on port 8088. +This is available on Splunk Enterprise version 6.3 or higher. +.UNINDENT +.INDENT 0.0 +.TP +.B class salt.returners.splunk.http_event_collector(token, http_event_server, host=\(aq\(aq, http_event_port=\(aq8088\(aq, http_event_server_ssl=True, max_bytes=100000, verify_ssl=True) +.INDENT 7.0 +.TP +.B sendEvent(payload, eventtime=\(aq\(aq) +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.splunk.returner(ret) +Send a message to Splunk via the HTTP Event Collector. +Requires the Splunk HTTP Event Collector running on port 8088. +This is available on Splunk Enterprise version 6.3 or higher. +.UNINDENT +.SS salt.returners.sqlite3 +.sp +Insert minion return data into a sqlite3 database +.INDENT 0.0 +.TP +.B maintainer +Mickey Malone <\fI\%mickey.malone@gmail.com\fP> +.TP +.B maturity +New +.TP +.B depends +None +.TP +.B platform +All +.UNINDENT +.sp +Sqlite3 is a serverless database that lives in a single file. +In order to use this returner the database file must exist, +have the appropriate schema defined, and be accessible to the +user whom the minion process is running as. This returner +requires the following values configured in the master or +minion config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +sqlite3.database: /usr/lib/salt/salt.db +sqlite3.timeout: 5.0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.sqlite3.database: /usr/lib/salt/salt.db +alternative.sqlite3.timeout: 5.0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Use the commands to create the sqlite3 database and tables: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +sqlite3 /usr/lib/salt/salt.db << EOF +\-\- +\-\- Table structure for table \(aqjids\(aq +\-\- + +CREATE TABLE jids ( + jid TEXT PRIMARY KEY, + load TEXT NOT NULL + ); + +\-\- +\-\- Table structure for table \(aqsalt_returns\(aq +\-\- + +CREATE TABLE salt_returns ( + fun TEXT KEY, + jid TEXT KEY, + id TEXT KEY, + fun_args TEXT, + date TEXT NOT NULL, + full_ret TEXT NOT NULL, + success TEXT NOT NULL + ); +EOF +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the sqlite returner, append \(aq\-\-return sqlite3\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return sqlite3 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_kwargs \(aq{\(dqdb\(dq: \(dq/var/lib/salt/another\-salt.db\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.get_fun(fun) +Return a dict of the last function called for all minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.get_jid(jid) +Return the information returned from a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.get_jids() +Return a list of all job ids +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.get_load(jid) +Return the load from a specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.get_minions() +Return a list of minions +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.returner(ret) +Insert minion return data into the sqlite3 database +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.save_load(jid, load, minions=None) +Save the load to the specified jid +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.sqlite3_return.save_minions(jid, minions, syndic_id=None) +Included for API consistency +.UNINDENT +.SS salt.returners.syslog_return +.sp +Return data to the host operating system\(aqs syslog facility +.sp +To use the syslog returner, append \(aq\-\-return syslog\(aq to the +salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return syslog +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +syslog.level (optional, Default: LOG_INFO) +syslog.facility (optional, Default: LOG_USER) +syslog.tag (optional, Default: salt\-minion) +syslog.options (list, optional, Default: []) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Available levels, facilities, and options can be found in the +\fBsyslog\fP docs for your python version. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The default tag comes from \fBsys.argv[0]\fP which is +usually \(dqsalt\-minion\(dq but could be different based on +the specific environment. +.UNINDENT +.UNINDENT +.sp +Configuration example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +syslog.level: \(aqLOG_ERR\(aq +syslog.facility: \(aqLOG_DAEMON\(aq +syslog.tag: \(aqmysalt\(aq +syslog.options: + \- LOG_PID +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Of course you can also nest the options: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +syslog: + level: \(aqLOG_ERR\(aq + facility: \(aqLOG_DAEMON\(aq + tag: \(aqmysalt\(aq + options: + \- LOG_PID +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by +prefacing the configuration. Any values not found +in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +alternative.syslog.level: \(aqLOG_WARN\(aq +alternative.syslog.facility: \(aqLOG_NEWS\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append +\fB\-\-return_config alternative\fP to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return syslog \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append +\-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return syslog \-\-return_kwargs \(aq{\(dqlevel\(dq: \(dqLOG_DEBUG\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Syslog server implementations may have limits on the maximum +record size received by the client. This may lead to job +return data being truncated in the syslog server\(aqs logs. For +example, for rsyslog on RHEL\-based systems, the default +maximum record size is approximately 2KB (which return data +can easily exceed). This is configurable in rsyslog.conf via +the $MaxMessageSize config parameter. Please consult your syslog +implmentation\(aqs documentation to determine how to adjust this limit. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.syslog_return.prep_jid(nocache=False, passed_jid=None) +Do any work necessary to prepare a JID, including sending a custom id +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.syslog_return.returner(ret) +Return data to the local syslog +.UNINDENT +.SS salt.returners.telegram_return +.sp +Return salt data via Telegram. +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +telegram.chat_id (required) +telegram.token (required) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Telegram settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +telegram: + chat_id: 000000000 + token: 000000000:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the Telegram return, append \(aq\-\-return telegram\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return telegram +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.telegram_return.returner(ret) +Send a Telegram message with the data. +.INDENT 7.0 +.TP +.B Parameters +\fBret\fP \-\- The data to be sent. +.TP +.B Returns +Boolean if message was sent successfully. +.UNINDENT +.UNINDENT +.SS salt.returners.xmpp_return +.sp +Return salt data via xmpp +.INDENT 0.0 +.TP +.B depends +sleekxmpp >= 1.3.1 +.UNINDENT +.sp +The following fields can be set in the minion conf file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xmpp.jid (required) +xmpp.password (required) +xmpp.recipient (required) +xmpp.profile (optional) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Alternative configuration values can be used by prefacing the configuration. +Any values not found in the alternative configuration will be pulled from +the default location: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xmpp.jid +xmpp.password +xmpp.recipient +xmpp.profile +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +XMPP settings may also be configured as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xmpp: + jid: user@xmpp.domain.com/resource + password: password + recipient: user@xmpp.example.com + +alternative.xmpp: + jid: user@xmpp.domain.com/resource + password: password + recipient: someone@xmpp.example.com + +xmpp_profile: + xmpp.jid: user@xmpp.domain.com/resource + xmpp.password: password + +xmpp: + profile: xmpp_profile + recipient: user@xmpp.example.com + +alternative.xmpp: + profile: xmpp_profile + recipient: someone\-else@xmpp.example.com +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the XMPP returner, append \(aq\-\-return xmpp\(aq to the salt command. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return xmpp +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. +.sp +New in version 2015.5.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_config alternative +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To override individual configuration items, append \-\-return_kwargs \(aq{\(dqkey:\(dq: \(dqvalue\(dq}\(aq to the salt command. +.sp +New in version 2016.3.0. + +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_kwargs \(aq{\(dqrecipient\(dq: \(dqsomeone\-else@xmpp.example.com\(dq}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B class salt.returners.xmpp_return.SendMsgBot(jid, password, recipient, msg) +.INDENT 7.0 +.TP +.B start(event) +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.xmpp_return.returner(ret) +Send an xmpp message with the data +.UNINDENT +.SS salt.returners.zabbix_return +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp +Return salt data to Zabbix +.sp +The following Type: \(dqZabbix trapper\(dq with \(dqType of information\(dq Text items are required: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Key: salt.trap.info +Key: salt.trap.warning +Key: salt.trap.high +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To use the Zabbix returner, append \(aq\-\-return zabbix\(aq to the salt command. ex: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq test.ping \-\-return zabbix +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.zabbix_return.returner(ret) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.zabbix_return.save_load(jid, load, minions=None) +Included for API consistency +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.zabbix_return.zabbix_send(key, output) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.returners.zabbix_return.zbx() +.UNINDENT .SS Executors .sp Executors are used by minion to execute module functions. Executors can be used @@ -56374,17 +56870,17 @@ exist on the subject, to either execute in an imperative fashion where things are executed in the order in which they are defined, or in a declarative fashion where dependencies need to be mapped between objects. .sp -Imperative ordering is finite and generally considered easier to write, but +Imperative ordering is deterministic and generally considered easier to write, but declarative ordering is much more powerful and flexible but generally considered more difficult to create. .sp Salt has been created to get the best of both worlds. States are evaluated in -a finite order, which guarantees that states are always executed in the same +a deterministic order, which guarantees that states are always executed in the same order, and the states runtime is declarative, making Salt fully aware of dependencies via the \fIrequisite\fP system. .SS State Auto Ordering .sp -Salt always executes states in a finite manner, meaning that they will always +Salt always executes states in a deterministic manner, meaning that they will always execute in the same order regardless of the system that is executing them. This evaluation order makes it easy to know what order the states will be executed in, but it is important to note that the requisite system will override the ordering @@ -66117,8 +66613,8 @@ be set: .nf .ft C my\-linode\-config: - apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf - password: F00barbaz + apikey: asldkgfaklsdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf + password: F00barbazlonglongp@ssword ssh_pubkey: ssh\-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host ssh_key_file: ~/.ssh/id_ed25519 driver: linode @@ -66575,64 +67071,28 @@ It is possible to use Salt Cloud to spin up Windows instances, and then install Salt on them. This functionality is available on all cloud providers that are supported by Salt Cloud. However, it may not necessarily be available on all Windows images. +.SS Dependencies +.sp +Salt Cloud needs the following packages: +.INDENT 0.0 +.IP \(bu 2 +\fI\%pypsexec\fP\&. +.IP \(bu 2 +\fI\%smbprotocol\fP\&. +.UNINDENT +.sp +For versions of Salt prior to 3006, Salt Cloud has a dependency on the +\fBimpacket\fP library to set up the Windows Salt Minion installer: +.INDENT 0.0 +.IP \(bu 2 +\fI\%impacket\fP\&. +.UNINDENT .SS Requirements .sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Support \fBwinexe\fP and \fBimpacket\fP has been deprecated and will be removed in -3001. These dependencies are replaced by \fBpypsexec\fP and \fBsmbprotocol\fP -respectively. These are pure python alternatives that are compatible with all -supported python versions. -.UNINDENT -.UNINDENT -.sp -Salt Cloud makes use of \fIimpacket\fP and \fIwinexe\fP to set up the Windows Salt -Minion installer. -.sp -\fIimpacket\fP is usually available as either the \fIimpacket\fP or the -\fIpython\-impacket\fP package, depending on the distribution. More information on -\fIimpacket\fP can be found at the project home: -.INDENT 0.0 -.IP \(bu 2 -\fI\%impacket project home\fP -.UNINDENT -.sp -\fIwinexe\fP is less commonly available in distribution\-specific repositories. -However, it is currently being built for various distributions in 3rd party -channels: -.INDENT 0.0 -.IP \(bu 2 -\fI\%RPMs at pbone.net\fP -.UNINDENT -.INDENT 0.0 -.IP \(bu 2 -\fI\%openSUSE Build Service\fP -.UNINDENT -.INDENT 0.0 -.IP \(bu 2 -\fI\%pypsexec project home\fP -.UNINDENT -.INDENT 0.0 -.IP \(bu 2 -\fI\%smbprotocol project home\fP -.UNINDENT -.sp -Optionally WinRM can be used instead of \fIwinexe\fP if the python module \fIpywinrm\fP -is available and WinRM is supported on the target Windows version. Information -on pywinrm can be found at the project home: -.INDENT 0.0 -.IP \(bu 2 -\fI\%pywinrm project home\fP -.UNINDENT -.sp -Additionally, a copy of the Salt Minion Windows installer must be present on -the system on which Salt Cloud is running. This installer may be downloaded -from saltstack.com: -.INDENT 0.0 -.IP \(bu 2 -\fI\%SaltStack Download Area\fP -.UNINDENT +A copy of the Salt Minion Windows installer must be present on the system on +which Salt Cloud is running. See +\fI\%Windows \- Salt install guide\fP for information about downloading +and using the Salt Minion Windows installer. .SS Self Signed Certificates with WinRM .sp Salt\-Cloud can use versions of \fBpywinrm<=0.1.1\fP or \fBpywinrm>=0.2.1\fP\&. @@ -67045,2197 +67505,6 @@ my\-aliyun\-config: Aliyun ECS REST API documentation is available from \fI\%Aliyun ECS API\fP\&. .UNINDENT .UNINDENT -.SS Getting Started With Azure -.sp -New in version 2014.1.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 due to -the deprecation of the \(dqClassic\(dq API for Azure. Please migrate to -\fI\%Azure Resource Manager by March 1, 2023\fP -.UNINDENT -.UNINDENT -.sp -Azure is a cloud service by Microsoft providing virtual machines, SQL services, -media services, and more. This document describes how to use Salt Cloud to -create a virtual machine on Azure, with Salt installed. -.sp -More information about Azure is located at \fI\%http://www.windowsazure.com/\fP\&. -.SS Dependencies -.INDENT 0.0 -.IP \(bu 2 -\fI\%Microsoft Azure SDK for Python\fP >= 1.0.2 -.IP \(bu 2 -The python\-requests library, for Python < 2.7.9. -.IP \(bu 2 -A Microsoft Azure account -.IP \(bu 2 -OpenSSL (to generate the certificates) -.IP \(bu 2 -\fI\%Salt\fP -.UNINDENT -.SS Configuration -.sp -Set up the provider config at \fB/etc/salt/cloud.providers.d/azure.conf\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# Note: This example is for /etc/salt/cloud.providers.d/azure.conf - -my\-azure\-config: - driver: azure - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - certificate_path: /etc/salt/azure.pem - - # Set up the location of the salt master - # - minion: - master: saltmaster.example.com - - # Optional - management_host: management.core.windows.net -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The certificate used must be generated by the user. OpenSSL can be used to -create the management certificates. Two certificates are needed: a .cer file, -which is uploaded to Azure, and a .pem file, which is stored locally. -.sp -To create the .pem file, execute the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -openssl req \-x509 \-nodes \-days 365 \-newkey rsa:1024 \-keyout /etc/salt/azure.pem \-out /etc/salt/azure.pem -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -To create the .cer file, execute the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -openssl x509 \-inform pem \-in /etc/salt/azure.pem \-outform der \-out /etc/salt/azure.cer -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -After creating these files, the .cer file will need to be uploaded to -Azure via the \(dqUpload a Management Certificate\(dq action of the \(dqManagement Certificates\(dq -tab within the \(dqSettings\(dq section of the management portal. -.sp -Optionally, a \fBmanagement_host\fP may be configured, if necessary for the region. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Changed in version 2015.8.0. - -.sp -The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This -change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile -definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that -provides the underlying functionality to connect to a cloud host, while cloud profiles continue -to use \fBprovider\fP to refer to provider configurations that you define. -.UNINDENT -.UNINDENT -.SS Cloud Profiles -.sp -Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -azure\-ubuntu: - provider: my\-azure\-config - image: \(aqb39f27a8b8c64d52b05eac6a62ebad85__Ubuntu\-12_04_3\-LTS\-amd64\-server\-20131003\-en\-us\-30GB\(aq - size: Small - location: \(aqEast US\(aq - ssh_username: azureuser - ssh_password: verybadpass - slot: production - media_link: \(aqhttp://portalvhdabcdefghijklmn.blob.core.windows.net/vhds\(aq - virtual_network_name: azure\-virtual\-network - subnet_name: azure\-subnet -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -These options are described in more detail below. Once configured, the profile -can be realized with a salt command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-p azure\-ubuntu newinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This will create an salt minion instance named \fBnewinstance\fP in Azure. If -the command was executed on the salt\-master, its Salt key will automatically -be signed on the master. -.sp -Once the instance has been created with salt\-minion installed, connectivity to -it can be verified with Salt: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt newinstance test.version -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Profile Options -.sp -The following options are currently available for Azure. -.SS provider -.sp -The name of the provider as configured in -\fI/etc/salt/cloud.providers.d/azure.conf\fP\&. -.SS image -.sp -The name of the image to use to create a VM. Available images can be viewed -using the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-images my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS size -.sp -The name of the size to use to create a VM. Available sizes can be viewed using -the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-sizes my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS location -.sp -The name of the location to create a VM in. Available locations can be viewed -using the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-locations my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS affinity_group -.sp -The name of the affinity group to create a VM in. Either a \fBlocation\fP or an -\fBaffinity_group\fP may be specified, but not both. See Affinity Groups below. -.SS ssh_username -.sp -The user to use to log into the newly\-created VM to install Salt. -.SS ssh_password -.sp -The password to use to log into the newly\-created VM to install Salt. -.SS slot -.sp -The environment to which the hosted service is deployed. Valid values are -\fIstaging\fP or \fIproduction\fP\&. When set to \fIproduction\fP, the resulting URL of the -new VM will be \fI.cloudapp.net\fP\&. When set to \fIstaging\fP, the resulting -URL will contain a generated hash instead. -.SS media_link -.sp -This is the URL of the container that will store the disk that this VM uses. -Currently, this container must already exist. If a VM has previously been -created in the associated account, a container should already exist. In the web -interface, go into the Storage area and click one of the available storage -selections. Click the Containers link, and then copy the URL from the container -that will be used. It generally looks like: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds -.ft P -.fi -.UNINDENT -.UNINDENT -.SS service_name -.sp -The name of the service in which to create the VM. If this is not specified, -then a service will be created with the same name as the VM. -.SS virtual_network_name -.sp -Optional. The name of the virtual network for the VM to join. If this is not -specified, then no virtual network will be joined. -.SS subnet_name -.sp -Optional. The name of the subnet in the virtual network for the VM to join. -Requires that a \fBvirtual_network_name\fP is specified. -.SS Show Instance -.sp -This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on -a single instance only. In an environment with several machines, this will save -a user from having to sort through all instance data, just to examine a single -instance. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_instance myinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Destroying VMs -.sp -There are certain options which can be specified in the global cloud -configuration file (usually \fB/etc/salt/cloud\fP) which affect Salt Cloud\(aqs -behavior when a VM is destroyed. -.SS cleanup_disks -.sp -New in version 2015.8.0. - -.sp -Default is \fBFalse\fP\&. When set to \fBTrue\fP, Salt Cloud will wait for the VM to -be destroyed, then attempt to destroy the main disk that is associated with the -VM. -.SS cleanup_vhds -.sp -New in version 2015.8.0. - -.sp -Default is \fBFalse\fP\&. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. When -also set to \fBTrue\fP, Salt Cloud will ask Azure to delete the VHD associated -with the disk that is also destroyed. -.SS cleanup_services -.sp -New in version 2015.8.0. - -.sp -Default is \fBFalse\fP\&. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. When -also set to \fBTrue\fP, Salt Cloud will wait for the disk to be destroyed, then -attempt to remove the service that is associated with the VM. Because the disk -belongs to the service, the disk must be destroyed before the service can be. -.SS Managing Hosted Services -.sp -New in version 2015.8.0. - -.sp -An account can have one or more hosted services. A hosted service is required -in order to create a VM. However, as mentioned above, if a hosted service is not -specified when a VM is created, then one will automatically be created with the -name of the name. The following functions are also available. -.SS create_service -.sp -Create a hosted service. The following options are available. -.SS name -.sp -Required. The name of the hosted service to create. -.SS label -.sp -Required. A label to apply to the hosted service. -.SS description -.sp -Optional. A longer description of the hosted service. -.SS location -.sp -Required, if \fBaffinity_group\fP is not set. The location in which to create the -hosted service. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, -but not both. -.SS affinity_group -.sp -Required, if \fBlocation\fP is not set. The affinity group in which to create the -hosted service. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, -but not both. -.SS extended_properties -.sp -Optional. Dictionary containing name/value pairs of hosted service properties. -You can have a maximum of 50 extended property name/value pairs. The maximum -length of the Name element is 64 characters, only alphanumeric characters and -underscores are valid in the Name, and the name must start with a letter. -The value has a maximum length of 255 characters. -.SS CLI Example -.sp -The following example illustrates creating a hosted service. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_service my\-azure name=my\-service label=my\-service location=\(aqWest US\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_service -.sp -Return details about a specific hosted service. Can also be called with -\fBget_service\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage my\-azure name=my\-service -.ft P -.fi -.UNINDENT -.UNINDENT -.SS list_services -.sp -List all hosted services associates with the subscription. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_services my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_service -.sp -Delete a specific hosted service. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_service my\-azure name=my\-service -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Storage Accounts -.sp -New in version 2015.8.0. - -.sp -Salt Cloud can manage storage accounts associated with the account. The -following functions are available. Deprecated marked as deprecated are marked -as such as per the SDK documentation, but are still included for completeness -with the SDK. -.SS create_storage -.sp -Create a storage account. The following options are supported. -.SS name -.sp -Required. The name of the storage account to create. -.SS label -.sp -Required. A label to apply to the storage account. -.SS description -.sp -Optional. A longer description of the storage account. -.SS location -.sp -Required, if \fBaffinity_group\fP is not set. The location in which to create the -storage account. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, -but not both. -.SS affinity_group -.sp -Required, if \fBlocation\fP is not set. The affinity group in which to create the -storage account. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, -but not both. -.SS extended_properties -.sp -Optional. Dictionary containing name/value pairs of storage account properties. -You can have a maximum of 50 extended property name/value pairs. The maximum -length of the Name element is 64 characters, only alphanumeric characters and -underscores are valid in the Name, and the name must start with a letter. The -value has a maximum length of 255 characters. -.SS geo_replication_enabled -.sp -Deprecated. Replaced by the account_type parameter. -.SS account_type -.sp -Specifies whether the account supports locally\-redundant storage, geo\-redundant -storage, zone\-redundant storage, or read access geo\-redundant storage. Possible -values are: -.INDENT 0.0 -.IP \(bu 2 -Standard_LRS -.IP \(bu 2 -Standard_ZRS -.IP \(bu 2 -Standard_GRS -.IP \(bu 2 -Standard_RAGRS -.UNINDENT -.SS CLI Example -.sp -The following example illustrates creating a storage account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_storage my\-azure name=my\-storage label=my\-storage location=\(aqWest US\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS list_storage -.sp -List all storage accounts associates with the subscription. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_storage my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_storage -.sp -Return details about a specific storage account. Can also be called with -\fBget_storage\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage my\-azure name=my\-storage -.ft P -.fi -.UNINDENT -.UNINDENT -.SS update_storage -.sp -Update details concerning a storage account. Any of the options available in -\fBcreate_storage\fP can be used, but the name cannot be changed. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_storage my\-azure name=my\-storage label=my\-storage -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_storage -.sp -Delete a specific storage account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_storage my\-azure name=my\-storage -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_storage_keys -.sp -Returns the primary and secondary access keys for the specified storage account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_keys my\-azure name=my\-storage -.ft P -.fi -.UNINDENT -.UNINDENT -.SS regenerate_storage_keys -.sp -Regenerate storage account keys. Requires a key_type (\(dqprimary\(dq or \(dqsecondary\(dq) -to be specified. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f regenerate_storage_keys my\-azure name=my\-storage key_type=primary -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Disks -.sp -New in version 2015.8.0. - -.sp -When a VM is created, a disk will also be created for it. The following -functions are available for managing disks. Deprecated marked as deprecated are -marked as such as per the SDK documentation, but are still included for -completeness with the SDK. -.SS show_disk -.sp -Return details about a specific disk. Can also be called with \fBget_disk\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_disk my\-azure name=my\-disk -.ft P -.fi -.UNINDENT -.UNINDENT -.SS list_disks -.sp -List all disks associates with the account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_disks my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS update_disk -.sp -Update details for a disk. The following options are available. -.SS name -.sp -Required. The name of the disk to update. -.SS has_operating_system -.sp -Deprecated. -.SS label -.sp -Required. The label for the disk. -.SS media_link -.sp -Deprecated. The location of the disk in the account, including the storage -container that it is in. This should not need to be changed. -.SS new_name -.sp -Deprecated. If renaming the disk, the new name. -.SS os -.sp -Deprecated. -.SS CLI Example -.sp -The following example illustrates updating a disk. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_disk my\-azure name=my\-disk label=my\-disk -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_disk -.sp -Delete a specific disk. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_disk my\-azure name=my\-disk -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Service Certificates -.sp -New in version 2015.8.0. - -.sp -Stored at the cloud service level, these certificates are used by your deployed -services. For more information on service certificates, see the following link: -.INDENT 0.0 -.IP \(bu 2 -\fI\%Manage Certificates\fP -.UNINDENT -.sp -The following functions are available. -.SS list_service_certificates -.sp -List service certificates associated with the account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_service_certificates my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_service_certificate -.sp -Show the data for a specific service certificate associated with the account. -The \fBname\fP, \fBthumbprint\fP, and \fBthumbalgorithm\fP can be obtained from -\fBlist_service_certificates\fP\&. Can also be called with -\fBget_service_certificate\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.SS add_service_certificate -.sp -Add a service certificate to the account. This requires that a certificate -already exists, which is then added to the account. For more information on -creating the certificate itself, see: -.INDENT 0.0 -.IP \(bu 2 -\fI\%Create a Service Certificate for Azure\fP -.UNINDENT -.sp -The following options are available. -.SS name -.sp -Required. The name of the hosted service that the certificate will belong to. -.SS data -.sp -Required. The base\-64 encoded form of the pfx file. -.SS certificate_format -.sp -Required. The service certificate format. The only supported value is pfx. -.SS password -.sp -The certificate password. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_service_certificate my\-azure name=my\-cert \e - data=\(aq...CERT_DATA...\(aq certificate_format=pfx password=verybadpass -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_service_certificate -.sp -Delete a service certificate from the account. The \fBname\fP, \fBthumbprint\fP, -and \fBthumbalgorithm\fP can be obtained from \fBlist_service_certificates\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_service_certificate my\-azure \e - name=my_service_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Management Certificates -.sp -New in version 2015.8.0. - -.sp -A Azure management certificate is an X.509 v3 certificate used to authenticate -an agent, such as Visual Studio Tools for Windows Azure or a client application -that uses the Service Management API, acting on behalf of the subscription owner -to manage subscription resources. Azure management certificates are uploaded to -Azure and stored at the subscription level. The management certificate store can -hold up to 100 certificates per subscription. These certificates are used to -authenticate your Windows Azure deployment. -.sp -For more information on management certificates, see the following link. -.INDENT 0.0 -.IP \(bu 2 -\fI\%Manage Certificates\fP -.UNINDENT -.sp -The following functions are available. -.SS list_management_certificates -.sp -List management certificates associated with the account. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_management_certificates my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_management_certificate -.sp -Show the data for a specific management certificate associated with the account. -The \fBname\fP, \fBthumbprint\fP, and \fBthumbalgorithm\fP can be obtained from -\fBlist_management_certificates\fP\&. Can also be called with -\fBget_management_certificate\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_management_certificate my\-azure name=my_management_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.SS add_management_certificate -.sp -Management certificates must have a key length of at least 2048 bits and should -reside in the Personal certificate store. When the certificate is installed on -the client, it should contain the private key of the certificate. To upload to -the certificate to the Microsoft Azure Management Portal, you must export it as -a .cer format file that does not contain the private key. For more information -on creating management certificates, see the following link: -.INDENT 0.0 -.IP \(bu 2 -\fI\%Create and Upload a Management Certificate for Azure\fP -.UNINDENT -.sp -The following options are available. -.SS public_key -.sp -A base64 representation of the management certificate public key. -.SS thumbprint -.sp -The thumb print that uniquely identifies the management certificate. -.SS data -.sp -The certificate\(aqs raw data in base\-64 encoded .cer format. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_management_certificate my\-azure public_key=\(aq...PUBKEY...\(aq \e - thumbprint=0123456789ABCDEF data=\(aq...CERT_DATA...\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_management_certificate -.sp -Delete a management certificate from the account. The \fBthumbprint\fP can be -obtained from \fBlist_management_certificates\fP\&. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_management_certificate my\-azure thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Virtual Network Management -.sp -New in version 2015.8.0. - -.sp -The following are functions for managing virtual networks. -.SS list_virtual_networks -.sp -List input endpoints associated with the deployment. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_virtual_networks my\-azure service=myservice deployment=mydeployment -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Input Endpoints -.sp -New in version 2015.8.0. - -.sp -Input endpoints are used to manage port access for roles. Because endpoints -cannot be managed by the Azure Python SDK, Salt Cloud uses the API directly. -With versions of Python before 2.7.9, the \fBrequests\-python\fP package needs to -be installed in order for this to work. Additionally, the following needs to be -set in the master\(aqs configuration file: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -backend: requests -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The following functions are available. -.SS list_input_endpoints -.sp -List input endpoints associated with the deployment -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_input_endpoints my\-azure service=myservice deployment=mydeployment -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_input_endpoint -.sp -Show an input endpoint associated with the deployment -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.SS add_input_endpoint -.sp -Add an input endpoint to the deployment. Please note that there may be a delay -before the changes show up. The following options are available. -.SS service -.sp -Required. The name of the hosted service which the VM belongs to. -.SS deployment -.sp -Required. The name of the deployment that the VM belongs to. If the VM was -created with Salt Cloud, the deployment name probably matches the VM name. -.SS role -.sp -Required. The name of the role that the VM belongs to. If the VM was created -with Salt Cloud, the role name probably matches the VM name. -.SS name -.sp -Required. The name of the input endpoint. This typically matches the port that -the endpoint is set to. For instance, port 22 would be called SSH. -.SS port -.sp -Required. The public (Internet\-facing) port that is used for the endpoint. -.SS local_port -.sp -Optional. The private port on the VM itself that will be matched with the port. -This is typically the same as the \fBport\fP\&. If this value is not specified, it -will be copied from \fBport\fP\&. -.SS protocol -.sp -Required. Either \fBtcp\fP or \fBudp\fP\&. -.SS enable_direct_server_return -.sp -Optional. If an internal load balancer exists in the account, it can be used -with a direct server return. The default value is \fBFalse\fP\&. Please see the -following article for an explanation of this option. -.INDENT 0.0 -.IP \(bu 2 -\fI\%Load Balancing for Azure Infrastructure Services\fP -.UNINDENT -.SS timeout_for_tcp_idle_connection -.sp -Optional. The default value is \fB4\fP\&. Please see the following article for an -explanation of this option. -.INDENT 0.0 -.IP \(bu 2 -\fI\%Configurable Idle Timeout for Azure Load Balancer\fP -.UNINDENT -.SS CLI Example -.sp -The following example illustrates adding an input endpoint. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP local_port=80 \e - port=80 protocol=tcp enable_direct_server_return=False \e - timeout_for_tcp_idle_connection=4 -.ft P -.fi -.UNINDENT -.UNINDENT -.SS update_input_endpoint -.sp -Updates the details for a specific input endpoint. All options from -\fBadd_input_endpoint\fP are supported. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP local_port=80 \e - port=80 protocol=tcp enable_direct_server_return=False \e - timeout_for_tcp_idle_connection=4 -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_input_endpoint -.sp -Delete an input endpoint from the deployment. Please note that there may be a -delay before the changes show up. The following items are required. -.SS CLI Example -.sp -The following example illustrates deleting an input endpoint. -.SS service -.sp -The name of the hosted service which the VM belongs to. -.SS deployment -.sp -The name of the deployment that the VM belongs to. If the VM was created with -Salt Cloud, the deployment name probably matches the VM name. -.SS role -.sp -The name of the role that the VM belongs to. If the VM was created with Salt -Cloud, the role name probably matches the VM name. -.SS name -.sp -The name of the input endpoint. This typically matches the port that the -endpoint is set to. For instance, port 22 would be called SSH. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Affinity Groups -.sp -New in version 2015.8.0. - -.sp -Affinity groups allow you to group your Azure services to optimize performance. -All services and VMs within an affinity group will be located in the same -region. For more information on Affinity groups, see the following link: -.INDENT 0.0 -.IP \(bu 2 -\fI\%Create an Affinity Group in the Management Portal\fP -.UNINDENT -.sp -The following functions are available. -.SS list_affinity_groups -.sp -List input endpoints associated with the account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_affinity_groups my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS show_affinity_group -.sp -Show an affinity group associated with the account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_affinity_group my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.SS create_affinity_group -.sp -Create a new affinity group. The following options are supported. -.SS name -.sp -Required. The name of the new affinity group. -.SS location -.sp -Required. The region in which the affinity group lives. -.SS label -.sp -Required. A label describing the new affinity group. -.SS description -.sp -Optional. A longer description of the affinity group. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_affinity_group my\-azure name=my_affinity_group \e - label=my\-affinity\-group location=\(aqWest US\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS update_affinity_group -.sp -Update an affinity group\(aqs properties -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_affinity_group my\-azure name=my_group label=my_group -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delete_affinity_group -.sp -Delete a specific affinity group associated with the account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_affinity_group my\-azure name=my_affinity_group -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Managing Blob Storage -.sp -New in version 2015.8.0. - -.sp -Azure storage containers and their contents can be managed with Salt Cloud. This -is not as elegant as using one of the other available clients in Windows, but it -benefits Linux and Unix users, as there are fewer options available on those -platforms. -.SS Blob Storage Configuration -.sp -Blob storage must be configured differently than the standard Azure -configuration. Both a \fBstorage_account\fP and a \fBstorage_key\fP must be -specified either through the Azure provider configuration (in addition to the -other Azure configuration) or via the command line. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -storage_account: mystorage -storage_key: ffhj334fDSGFEGDFGFDewr34fwfsFSDFwe== -.ft P -.fi -.UNINDENT -.UNINDENT -.SS storage_account -.sp -This is one of the storage accounts that is available via the \fBlist_storage\fP -function. -.SS storage_key -.sp -Both a primary and a secondary \fBstorage_key\fP can be obtained by running the -\fBshow_storage_keys\fP function. Either key may be used. -.SS Blob Functions -.sp -The following functions are made available through Salt Cloud for managing -blog storage. -.SS make_blob_url -.sp -Creates the URL to access a blob -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f make_blob_url my\-azure container=mycontainer blob=myblob -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -Name of the container. -.SS blob -.sp -Name of the blob. -.SS account -.sp -Name of the storage account. If not specified, derives the host base -from the provider configuration. -.SS protocol -.sp -Protocol to use: \(aqhttp\(aq or \(aqhttps\(aq. If not specified, derives the host -base from the provider configuration. -.SS host_base -.sp -Live host base URL. If not specified, derives the host base from the -provider configuration. -.SS list_storage_containers -.sp -List containers associated with the storage account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_storage_containers my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS create_storage_container -.sp -Create a storage container -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of container to create. -.SS meta_name_values -.sp -Optional. A dict with name_value pairs to associate with the -container as metadata. Example:{\(aqCategory\(aq:\(aqtest\(aq} -.SS blob_public_access -.sp -Optional. Possible values include: container, blob -.SS fail_on_exist -.sp -Specify whether to throw an exception when the container exists. -.SS show_storage_container -.sp -Show a container associated with the storage account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of container to show. -.SS show_storage_container_metadata -.sp -Show a storage container\(aqs metadata -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of container to show. -.SS lease_id -.sp -If specified, show_storage_container_metadata only succeeds if the -container\(aqs lease is active and matches this ID. -.SS set_storage_container_metadata -.sp -Set a storage container\(aqs metadata -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_storage_container my\-azure name=mycontainer \e - x_ms_meta_name_values=\(aq{\(dqmy_name\(dq: \(dqmy_value\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of existing container. -meta_name_values -\fB\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\fP -A dict containing name, value for metadata. -Example: {\(aqcategory\(aq:\(aqtest\(aq} -lease_id -\fB\(ga\(ga\(ga\(ga\fP -If specified, set_storage_container_metadata only succeeds if the -container\(aqs lease is active and matches this ID. -.SS show_storage_container_acl -.sp -Show a storage container\(aqs acl -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_acl my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of existing container. -.SS lease_id -.sp -If specified, show_storage_container_acl only succeeds if the -container\(aqs lease is active and matches this ID. -.SS set_storage_container_acl -.sp -Set a storage container\(aqs acl -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of existing container. -.SS signed_identifiers -.sp -SignedIdentifiers instance -.SS blob_public_access -.sp -Optional. Possible values include: container, blob -.SS lease_id -.sp -If specified, set_storage_container_acl only succeeds if the -container\(aqs lease is active and matches this ID. -.SS delete_storage_container -.sp -Delete a container associated with the storage account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of container to create. -.SS fail_not_exist -.sp -Specify whether to throw an exception when the container exists. -.SS lease_id -.sp -If specified, delete_storage_container only succeeds if the -container\(aqs lease is active and matches this ID. -.SS lease_storage_container -.sp -Lease a container associated with the storage account -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f lease_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.SS name -.sp -Name of container to create. -.SS lease_action -.sp -Required. Possible values: acquire|renew|release|break|change -.SS lease_id -.sp -Required if the container has an active lease. -.SS lease_duration -.sp -Specifies the duration of the lease, in seconds, or negative one -(\-1) for a lease that never expires. A non\-infinite lease can be -between 15 and 60 seconds. A lease duration cannot be changed -using renew or change. For backwards compatibility, the default is -60, and the value is only used on an acquire operation. -.SS lease_break_period -.sp -Optional. For a break operation, this is the proposed duration of -seconds that the lease should continue before it is broken, between -0 and 60 seconds. This break period is only used if it is shorter -than the time remaining on the lease. If longer, the time remaining -on the lease is used. A new lease will not be available before the -break period has expired, but the lease may be held for longer than -the break period. If this header does not appear with a break -operation, a fixed\-duration lease breaks after the remaining lease -period elapses, and an infinite lease breaks immediately. -.SS proposed_lease_id -.sp -Optional for acquire, required for change. Proposed lease ID, in a -GUID string format. -.SS list_blobs -.sp -List blobs associated with the container -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_blobs my\-azure container=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -The name of the storage container -.SS prefix -.sp -Optional. Filters the results to return only blobs whose names -begin with the specified prefix. -.SS marker -.sp -Optional. A string value that identifies the portion of the list -to be returned with the next list operation. The operation returns -a marker value within the response body if the list returned was -not complete. The marker value may then be used in a subsequent -call to request the next set of list items. The marker value is -opaque to the client. -.SS maxresults -.sp -Optional. Specifies the maximum number of blobs to return, -including all BlobPrefix elements. If the request does not specify -maxresults or specifies a value greater than 5,000, the server will -return up to 5,000 items. Setting maxresults to a value less than -or equal to zero results in error response code 400 (Bad Request). -.SS include -.sp -Optional. Specifies one or more datasets to include in the -response. To specify more than one of these options on the URI, -you must separate each option with a comma. Valid values are: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -snapshots: - Specifies that snapshots should be included in the - enumeration. Snapshots are listed from oldest to newest in - the response. -metadata: - Specifies that blob metadata be returned in the response. -uncommittedblobs: - Specifies that blobs for which blocks have been uploaded, - but which have not been committed using Put Block List - (REST API), be included in the response. -copy: - Version 2012\-02\-12 and newer. Specifies that metadata - related to any current or previous Copy Blob operation - should be included in the response. -.ft P -.fi -.UNINDENT -.UNINDENT -.SS delimiter -.sp -Optional. When the request includes this parameter, the operation -returns a BlobPrefix element in the response body that acts as a -placeholder for all blobs whose names begin with the same -substring up to the appearance of the delimiter character. The -delimiter may be a single character or a string. -.SS show_blob_service_properties -.sp -Show a blob\(aqs service properties -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_service_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS set_blob_service_properties -.sp -Sets the properties of a storage account\(aqs Blob service, including -Windows Azure Storage Analytics. You can also use this operation to -set the default request version for all incoming requests that do not -have a version specified. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_blob_service_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS properties -.sp -a StorageServiceProperties object. -.SS timeout -.sp -Optional. The timeout parameter is expressed in seconds. -.SS show_blob_properties -.sp -Returns all user\-defined metadata, standard HTTP properties, and -system properties for the blob. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_properties my\-azure container=mycontainer blob=myblob -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -Name of existing container. -.SS blob -.sp -Name of existing blob. -.SS lease_id -.sp -Required if the blob has an active lease. -.SS set_blob_properties -.sp -Set a blob\(aqs properties -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_blob_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -Name of existing container. -.SS blob -.sp -Name of existing blob. -.SS blob_cache_control -.sp -Optional. Modifies the cache control string for the blob. -.SS blob_content_type -.sp -Optional. Sets the blob\(aqs content type. -.SS blob_content_md5 -.sp -Optional. Sets the blob\(aqs MD5 hash. -.SS blob_content_encoding -.sp -Optional. Sets the blob\(aqs content encoding. -.SS blob_content_language -.sp -Optional. Sets the blob\(aqs content language. -.SS lease_id -.sp -Required if the blob has an active lease. -.SS blob_content_disposition -.sp -Optional. Sets the blob\(aqs Content\-Disposition header. -The Content\-Disposition response header field conveys additional -information about how to process the response payload, and also can -be used to attach additional metadata. For example, if set to -attachment, it indicates that the user\-agent should not display the -response, but instead show a Save As dialog with a filename other -than the blob name specified. -.SS put_blob -.sp -Upload a blob -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f put_blob my\-azure container=base name=top.sls blob_path=/srv/salt/top.sls -salt\-cloud \-f put_blob my\-azure container=base name=content.txt blob_content=\(aqSome content\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -Name of existing container. -.SS name -.sp -Name of existing blob. -.SS blob_path -.sp -The path on the local machine of the file to upload as a blob. Either -this or blob_content must be specified. -.SS blob_content -.sp -The actual content to be uploaded as a blob. Either this or blob_path -must me specified. -.SS cache_control -.sp -Optional. The Blob service stores this value but does not use or -modify it. -.SS content_language -.sp -Optional. Specifies the natural languages used by this resource. -.SS content_md5 -.sp -Optional. An MD5 hash of the blob content. This hash is used to -verify the integrity of the blob during transport. When this header -is specified, the storage service checks the hash that has arrived -with the one that was sent. If the two hashes do not match, the -operation will fail with error code 400 (Bad Request). -.SS blob_content_type -.sp -Optional. Set the blob\(aqs content type. -.SS blob_content_encoding -.sp -Optional. Set the blob\(aqs content encoding. -.SS blob_content_language -.sp -Optional. Set the blob\(aqs content language. -.SS blob_content_md5 -.sp -Optional. Set the blob\(aqs MD5 hash. -.SS blob_cache_control -.sp -Optional. Sets the blob\(aqs cache control. -.SS meta_name_values -.sp -A dict containing name, value for metadata. -.SS lease_id -.sp -Required if the blob has an active lease. -.SS get_blob -.sp -Download a blob -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_blob my\-azure container=base name=top.sls local_path=/srv/salt/top.sls -salt\-cloud \-f get_blob my\-azure container=base name=content.txt return_content=True -.ft P -.fi -.UNINDENT -.UNINDENT -.SS container -.sp -Name of existing container. -.SS name -.sp -Name of existing blob. -.SS local_path -.sp -The path on the local machine to download the blob to. Either this or -return_content must be specified. -.SS return_content -.sp -Whether or not to return the content directly from the blob. If -specified, must be True or False. Either this or the local_path must -be specified. -.SS snapshot -.sp -Optional. The snapshot parameter is an opaque DateTime value that, -when present, specifies the blob snapshot to retrieve. -.SS lease_id -.sp -Required if the blob has an active lease. -.SS progress_callback -.sp -callback for progress with signature function(current, total) where -current is the number of bytes transferred so far, and total is the -size of the blob. -.SS max_connections -.sp -Maximum number of parallel connections to use when the blob size -exceeds 64MB. -Set to 1 to download the blob chunks sequentially. -Set to 2 or more to download the blob chunks in parallel. This uses -more system resources but will download faster. -.SS max_retries -.sp -Number of times to retry download of blob chunk if an error occurs. -.SS retry_wait -.sp -Sleep time in secs between retries. -.SS Getting Started With Azure ARM -.sp -New in version 2016.11.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.sp -Azure is a cloud service by Microsoft providing virtual machines, SQL services, -media services, and more. Azure ARM (aka, the Azure Resource Manager) is a next -generation version of the Azure portal and API. This document describes how to -use Salt Cloud to create a virtual machine on Azure ARM, with Salt installed. -.sp -More information about Azure is located at \fI\%http://www.windowsazure.com/\fP\&. -.SS Dependencies -.INDENT 0.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0rc6 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.4 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 0.33.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 0.30.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.32.0 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.IP \(bu 2 -A Microsoft Azure account -.IP \(bu 2 -\fI\%Salt\fP -.UNINDENT -.SS Installation Tips -.sp -Because the \fBazure\fP library requires the \fBcryptography\fP library, which is -compiled on\-the\-fly by \fBpip\fP, you may need to install the development tools -for your operating system. -.sp -Before you install \fBazure\fP with \fBpip\fP, you should make sure that the -required libraries are installed. -.SS Debian -.sp -For Debian and Ubuntu, the following command will ensure that the required -dependencies are installed: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -sudo apt\-get install build\-essential libssl\-dev libffi\-dev python\-dev -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Red Hat -.sp -For Fedora and RHEL\-derivatives, the following command will ensure that the -required dependencies are installed: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -sudo yum install gcc libffi\-devel python\-devel openssl\-devel -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Configuration -.sp -Set up the provider config at \fB/etc/salt/cloud.providers.d/azurearm.conf\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# Note: This example is for /etc/salt/cloud.providers.d/azurearm.conf - -my\-azurearm\-config: - driver: azurearm - master: salt.example.com - subscription_id: 01234567\-890a\-bcde\-f012\-34567890abdc - - # https://apps.dev.microsoft.com/#/appList - username: @.onmicrosoft.com - password: verybadpass - location: westus - resource_group: my_rg - - # Optional - network_resource_group: my_net_rg - cleanup_disks: True - cleanup_vhds: True - cleanup_data_disks: True - cleanup_interfaces: True - custom_data: \(aqThis is custom data\(aq - expire_publisher_cache: 604800 # 7 days - expire_offer_cache: 518400 # 6 days - expire_sku_cache: 432000 # 5 days - expire_version_cache: 345600 # 4 days - expire_group_cache: 14400 # 4 hours - expire_interface_cache: 3600 # 1 hour - expire_network_cache: 3600 # 1 hour -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Cloud Profiles -.sp -Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -azure\-ubuntu\-pass: - provider: my\-azure\-config - image: Canonical|UbuntuServer|14.04.5\-LTS|14.04.201612050 - size: Standard_D1_v2 - location: eastus - ssh_username: azureuser - ssh_password: verybadpass - -azure\-ubuntu\-key: - provider: my\-azure\-config - image: Canonical|UbuntuServer|14.04.5\-LTS|14.04.201612050 - size: Standard_D1_v2 - location: eastus - ssh_username: azureuser - ssh_publickeyfile: /path/to/ssh_public_key.pub - -azure\-win2012: - provider: my\-azure\-config - image: MicrosoftWindowsServer|WindowsServer|2012\-R2\-Datacenter|latest - size: Standard_D1_v2 - location: westus - win_username: azureuser - win_password: verybadpass -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -These options are described in more detail below. Once configured, the profile -can be realized with a salt command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-p azure\-ubuntu newinstance -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This will create an salt minion instance named \fBnewinstance\fP in Azure. If -the command was executed on the salt\-master, its Salt key will automatically -be signed on the master. -.sp -Once the instance has been created with salt\-minion installed, connectivity to -it can be verified with Salt: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt newinstance test.version -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Profile Options -.sp -The following options are currently available for Azure ARM. -.SS provider -.sp -The name of the provider as configured in -\fI/etc/salt/cloud.providers.d/azure.conf\fP\&. -.SS image -.sp -Required. The name of the image to use to create a VM. Available images can be -viewed using the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-images my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -As you will see in \fB\-\-list\-images\fP, image names are comprised of the following -fields, separated by the pipe (\fB|\fP) character: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -publisher: For example, Canonical or MicrosoftWindowsServer -offer: For example, UbuntuServer or WindowsServer -sku: Such as 14.04.5\-LTS or 2012\-R2\-Datacenter -version: Such as 14.04.201612050 or latest -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -It is possible to specify the URL or resource ID path of a custom image that you -have access to, such as: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -https://.blob.core.windows.net/system/Microsoft.Compute/Images//template\-osDisk.01234567\-890a\-bcdef0123\-4567890abcde.vhd -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -or: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -/subscriptions/XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX/resourceGroups/myRG/providers/Microsoft.Compute/images/myImage -.ft P -.fi -.UNINDENT -.UNINDENT -.SS size -.sp -Required. The name of the size to use to create a VM. Available sizes can be -viewed using the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-sizes my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS location -.sp -Required. The name of the location to create a VM in. Available locations can -be viewed using the following command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-\-list\-locations my\-azure\-config -.ft P -.fi -.UNINDENT -.UNINDENT -.SS ssh_username -.sp -Required for Linux. The admin user to add on the instance. It is also used to log -into the newly\-created VM to install Salt. -.SS ssh_keyfile -.sp -Required if using SSH key authentication. The path on the Salt master to the SSH private -key used during the minion bootstrap process. -.SS ssh_publickeyfile -.sp -Use either \fBssh_publickeyfile\fP or \fBssh_password\fP\&. The path on the Salt master to the -SSH public key which will be pushed to the Linux VM. -.SS ssh_password -.sp -Use either \fBssh_publickeyfile\fP or \fBssh_password\fP\&. The password for the admin user on -the newly\-created Linux virtual machine. -.SS win_username -.sp -Required for Windows. The user to use to log into the newly\-created Windows VM -to install Salt. -.SS win_password -.sp -Required for Windows. The password to use to log into the newly\-created Windows -VM to install Salt. -.SS win_installer -.sp -Required for Windows. The path to the Salt installer to be uploaded. -.SS resource_group -.sp -Required. The resource group that all VM resources (VM, network interfaces, -etc) will be created in. -.SS network_resource_group -.sp -Optional. If specified, then the VM will be connected to the virtual network -in this resource group, rather than the parent resource group of the instance. -The VM interfaces and IPs will remain in the configured \fBresource_group\fP with -the VM. -.SS network -.sp -Required. The virtual network that the VM will be spun up in. -.SS subnet -.sp -Optional. The subnet inside the virtual network that the VM will be spun up in. -Default is \fBdefault\fP\&. -.SS allocate_public_ip -.sp -Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, a public IP will -be created and assigned to the VM. -.SS load_balancer -.sp -Optional. The load\-balancer for the VM\(aqs network interface to join. If -specified the backend_pool option need to be set. -.SS backend_pool -.sp -Optional. Required if the load_balancer option is set. The load\-balancer\(aqs -Backend Pool the VM\(aqs network interface will join. -.SS iface_name -.sp -Optional. The name to apply to the VM\(aqs network interface. If not supplied, the -value will be set to \fB\-iface0\fP\&. -.SS dns_servers -.sp -Optional. A \fBlist\fP of the DNS servers to configure for the network interface -(will be set on the VM by the DHCP of the VNET). -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-azurearm\-profile: - provider: azurearm\-provider - network: mynetwork - dns_servers: - \- 10.1.1.4 - \- 10.1.1.5 -.ft P -.fi -.UNINDENT -.UNINDENT -.SS availability_set -.sp -Optional. If set, the VM will be added to the specified availability set. -.SS volumes -.sp -Optional. A list of dictionaries describing data disks to attach to the -instance can be specified using this setting. The data disk dictionaries are -passed entirely to the \fI\%Azure DataDisk object\fP, -so ad\-hoc options can be handled as long as they are valid properties of the -object. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -volumes: -\- disk_size_gb: 50 - caching: ReadWrite -\- disk_size_gb: 100 - caching: ReadWrite - managed_disk: - storage_account_type: Standard_LRS -.ft P -.fi -.UNINDENT -.UNINDENT -.SS cleanup_disks -.sp -Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, disks will be cleaned up -when the VM that they belong to is deleted. -.SS cleanup_vhds -.sp -Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, VHDs will be cleaned up -when the VM and disk that they belong to are deleted. Requires \fBcleanup_disks\fP -to be set to \fBTrue\fP\&. -.SS cleanup_data_disks -.sp -Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, data disks (non\-root -volumes) will be cleaned up whtn the VM that they are attached to is deleted. -Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. -.SS cleanup_interfaces -.sp -Optional. Default is \fBFalse\fP\&. Normally when a VM is deleted, its associated -interfaces and IPs are retained. This is useful if you expect the deleted VM -to be recreated with the same name and network settings. If you would like -interfaces and IPs to be deleted when their associated VM is deleted, set this -to \fBTrue\fP\&. -.SS userdata -.sp -Optional. Any custom cloud data that needs to be specified. How this data is -used depends on the operating system and image that is used. For instance, -Linux images that use \fBcloud\-init\fP will import this data for use with that -program. Some Windows images will create a file with a copy of this data, and -others will ignore it. If a Windows image creates a file, then the location -will depend upon the version of Windows. This will be ignored if the -\fBuserdata_file\fP is specified. -.SS userdata_file -.sp -Optional. The path to a file to be read and submitted to Azure as user data. -How this is used depends on the operating system that is being deployed. If -used, any \fBuserdata\fP setting will be ignored. -.SS userdata_sendkeys -.sp -Optional. Set to \fBTrue\fP in order to generate salt minion keys and provide -them as variables to the userdata script when running it through the template -renderer. The keys can be referenced as \fB{{opts[\(aqpriv_key\(aq]}}\fP and -\fB{{opts[\(aqpub_key\(aq]}}\fP\&. -.SS userdata_template -.sp -Optional. Enter the renderer, such as \fBjinja\fP, to be used for the userdata -script template. -.SS wait_for_ip_timeout -.sp -Optional. Default is \fB600\fP\&. When waiting for a VM to be created, Salt Cloud -will attempt to connect to the VM\(aqs IP address until it starts responding. This -setting specifies the maximum time to wait for a response. -.SS wait_for_ip_interval -.sp -Optional. Default is \fB10\fP\&. How long to wait between attempts to connect to -the VM\(aqs IP. -.SS wait_for_ip_interval_multiplier -.sp -Optional. Default is \fB1\fP\&. Increase the interval by this multiplier after -each request; helps with throttling. -.SS expire_publisher_cache -.sp -Optional. Default is \fB604800\fP\&. When fetching image data using -\fB\-\-list\-images\fP, a number of web calls need to be made to the Azure ARM API. -This is normally very fast when performed using a VM that exists inside Azure -itself, but can be very slow when made from an external connection. -.sp -By default, the publisher data will be cached, and only updated every \fB604800\fP -seconds (7 days). If you need the publisher cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the publisher -cache. -.SS expire_offer_cache -.sp -Optional. Default is \fB518400\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the offer data will be cached, and only updated every \fB518400\fP -seconds (6 days). If you need the offer cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the publiser -cache. -.SS expire_sku_cache -.sp -Optional. Default is \fB432000\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the sku data will be cached, and only updated every \fB432000\fP -seconds (5 days). If you need the sku cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the sku -cache. -.SS expire_version_cache -.sp -Optional. Default is \fB345600\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the version data will be cached, and only updated every \fB345600\fP -seconds (4 days). If you need the version cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the version -cache. -.SS expire_group_cache -.sp -Optional. Default is \fB14400\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the resource group data will be cached, and only updated every -\fB14400\fP seconds (4 hours). If you need the resource group cache to be updated -at a different frequency, change this setting. Setting it to \fB0\fP will turn -off the resource group cache. -.SS expire_interface_cache -.sp -Optional. Default is \fB3600\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the interface data will be cached, and only updated every \fB3600\fP -seconds (1 hour). If you need the interface cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the interface -cache. -.SS expire_network_cache -.sp -Optional. Default is \fB3600\fP\&. See \fBexpire_publisher_cache\fP for details on -why this exists. -.sp -By default, the network data will be cached, and only updated every \fB3600\fP -seconds (1 hour). If you need the network cache to be updated at a different -frequency, change this setting. Setting it to \fB0\fP will turn off the network -cache. -.SS Other Options -.sp -Other options relevant to Azure ARM. -.SS storage_account -.sp -Required for actions involving an Azure storage account. -.SS storage_key -.sp -Required for actions involving an Azure storage account. -.SS Show Instance -.sp -This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on -a single instance only. In an environment with several machines, this will save -a user from having to sort through all instance data, just to examine a single -instance. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a show_instance myinstance -.ft P -.fi -.UNINDENT -.UNINDENT .SS Getting Started with CloudStack .sp CloudStack is one the most popular cloud projects. It\(aqs an open source project @@ -69495,7 +67764,7 @@ digitalocean\-ubuntu: image: 14.04 x64 size: 512MB location: New York 1 - private_networking: True + vpc_name: Optional backups_enabled: True ipv6: True create_dns_record: True @@ -70252,7 +68521,7 @@ base_ec2_vpc: image: ami\-a73264ce size: m1.xlarge ssh_username: ec2\-user - script: /etc/salt/cloud.deploy.d/user_data.sh + script: /etc/salt/cloud.deploy.d/my_bootstrap.sh network_interfaces: \- DeviceIndex: 0 PrivateIpAddresses: @@ -73118,9 +71387,6 @@ This driver requires the Python \fBrequests\fP library to be installed. .B \fBpassword\fP \fB(Required)\fP The default password to set on new VMs. Must be 8 characters with at least one lowercase, uppercase, and numeric. .TP -.B \fBapi_version\fP -The version of the Linode API to interact with. Defaults to \fBv3\fP\&. -.TP .B \fBpoll_interval\fP The rate of time in milliseconds to poll the Linode API for changes. Defaults to \fB500\fP\&. .TP @@ -73138,24 +71404,8 @@ Set up the provider cloud configuration file at \fB/etc/salt/cloud.providers\fP .ft C my\-linode\-provider: driver: linode - api_version: v4 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... - password: F00barbaz -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -For use with APIv3 (deprecated): -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-linode\-provider\-v3: - driver: linode - apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... - password: F00barbaz + password: F00barbazverylongp@ssword .ft P .fi .UNINDENT @@ -73166,20 +71416,19 @@ my\-linode\-provider\-v3: .TP .B \fBimage\fP \fB(Required)\fP The image to deploy the boot disk from. This should be an image ID -(e.g. \fBlinode/ubuntu16.04\fP); official images start with \fBlinode/\fP\&. For APIv3, -this would be an image label (i.e. Ubuntu 16.04). See \fI\%listing images\fP -for more options. +(e.g. \fBlinode/ubuntu22.04\fP); official images start with \fBlinode/\fP\&. .TP .B \fBlocation\fP \fB(Required)\fP The location of the VM. This should be a Linode region -(e.g. \fBus\-east\fP). For APIv3, this would be a datacenter location -(e.g. \fBNewark, NJ, USA\fP). See \fI\%listing locations\fP for -more options. +(e.g. \fBus\-east\fP). See \fI\%the list of locations\fP and +\fI\%the guide to choose a location\fP +for more options. .TP .B \fBsize\fP \fB(Required)\fP The size of the VM. This should be a Linode instance type ID -(e.g. \fBg6\-standard\-2\fP). For APIv3, this would be a plan ID (e.g. \fBLinode 2GB\fP). -See \fI\%listing sizes\fP for more options. +(e.g. \fBg6\-standard\-2\fP). See \fI\%the list of sizes\fP and +\fI\%the guide to choose a size\fP +for more options. .TP .B \fBpassword\fP (overrides provider) \fB(*Required)\fP The default password for the VM. Must be provided at the profile @@ -73189,21 +71438,20 @@ or provider level. New in version 2016.3.0. .sp -Whether or not to assign a private key to the VM. Defaults to \fBFalse\fP\&. +\fB(optional)\fP Whether or not to assign a private IP to the VM. Defaults to \fBFalse\fP\&. +.TP +.B \fBbackups_enabled\fP +\fB(optional)\fP Whether or not to enable the backup for this VM. Backup can be +configured in your Linode account Defaults to \fBFalse\fP\&. .TP .B \fBcloneform\fP -The name of the Linode to clone from. -.TP -.B \fBdisk_size\fP -\fB(Deprecated)\fP The amount of disk space to allocate for the OS disk. This has no -effect with APIv4; the size of the boot disk will be the remainder of disk space -after the swap partition is allocated. +\fB(optional)\fP The name of the Linode to clone from. .TP .B \fBssh_interface\fP New in version 2016.3.0. .sp -The interface with which to connect over SSH. Valid options are \fBprivate_ips\fP or +\fB(optional)\fP The interface with which to connect over SSH. Valid options are \fBprivate_ips\fP or \fBpublic_ips\fP\&. Defaults to \fBpublic_ips\fP\&. .sp If specifying \fBprivate_ips\fP, the Linodes must be hosted within the same data center @@ -73216,14 +71464,14 @@ the Network Helper on your Linode account, please see \fI\%Linode\(aqs Network H documentation. .TP .B \fBssh_pubkey\fP -The public key to authorize for SSH with the VM. +\fB(optional)\fP The public key to authorize for SSH with the VM. .TP .B \fBswap\fP -The amount of disk space to allocate for the swap partition. Defaults to \fB256\fP\&. +\fB(optional)\fP The amount of disk space to allocate for the swap partition. Defaults to \fB256\fP\&. .UNINDENT .SS Example Configuration .sp -Set up a profile configuration in \fB/etc/salt/cloud.profiles.d/\fP: +Set up a profile configuration at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/*.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp @@ -73232,7 +71480,7 @@ Set up a profile configuration in \fB/etc/salt/cloud.profiles.d/\fP: my\-linode\-profile: provider: my\-linode\-provider size: g6\-standard\-1 - image: linode/alpine3.12 + image: linode/ubuntu22.04 location: us\-east .ft P .fi @@ -73275,10 +71523,10 @@ A more advanced configuration utlizing all of the configuration options might lo .ft C my\-linode\-profile\-advanced: provider: my\-linode\-provider - size: g6\-standard\-3 - image: linode/alpine3.10 - location: eu\-west - password: bogus123X + size: g6\-standard\-1 + image: linode/ubuntu22.04 + location: us\-central + password: iamaverylongp@ssword assign_private_ip: true ssh_interface: private_ips ssh_pubkey: ssh\-rsa AAAAB3NzaC1yc2EAAAADAQAB... @@ -73287,26 +71535,9 @@ my\-linode\-profile\-advanced: .fi .UNINDENT .UNINDENT -.sp -A legacy configuration for use with APIv3 might look like: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-linode\-profile\-v3: - provider: my\-linode\-provider\-v3 - size: Nanode 1GB - image: Alpine 3.12 - location: Fremont, CA, USA -.ft P -.fi -.UNINDENT -.UNINDENT .SS Migrating to APIv4 .sp -Linode APIv3 has been deprecated and will be shutdown in the coming months. You can opt\-in to using -APIv4 by setting the \fBapi_version\fP provider configuration option to \fBv4\fP\&. +Linode APIv3 has been removed, and APIv4 is the only available version. .sp When switching to APIv4, you will also need to generate a new token. See \fI\%here\fP @@ -73317,18 +71548,18 @@ for more information. \fBsize\fP, and \fBimage\fP have moved from accepting label based references to IDs. See the \fI\%profile configuration\fP section for more details. .sp -\fBThe \(ga\(gadisk_size\(ga\(ga profile configuration parameter has been deprecated.\fP The parameter will not be taken into +\fBThe \(ga\(gadisk_size\(ga\(ga profile configuration parameter has been removed.\fP The parameter will not be taken into account when creating new VMs while targeting APIv4. See the \fBdisk_size\fP description under the \fI\%profile configuration\fP section for more details. .sp \fBThe \(ga\(gaboot\(ga\(ga function no longer requires a \(ga\(gaconfig_id\(ga\(ga.\fP A config can be inferred by the API instead when booting. .sp -\fBThe \(ga\(gaclone\(ga\(ga function has renamed parameters to match convention.\fP The old version of these parameters will not -be supported when targeting APIv4. -* \fBdatacenter_id\fP has been deprecated in favor of \fBlocation\fP\&. -* \fBplan_id\fP has been deprecated in favor of \fBsize\fP\&. +\fBThe \(ga\(gaclone\(ga\(ga function has renamed parameters to match convention.\fP The old version of these parameters are no longer +supported. +* \fBdatacenter_id\fP has been removed and replaced by \fBlocation\fP\&. +* \fBplan_id\fP has been removed and replaced by \fBsize\fP\&. .sp -\fBThe \(ga\(gaget_plan_id\(ga\(ga function has been deprecated and will not be supported by APIv4.\fP IDs are now the only way +\fBThe \(ga\(gaget_plan_id\(ga\(ga function has been removed and is not supported by APIv4.\fP IDs are now the only way of referring to a \(dqplan\(dq (or type/size). .SS Query Utilities .SS Listing Sizes @@ -73424,7 +71655,7 @@ my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- - linode/alpine3.10: + linode/ubuntu22.04: \-\-\-\-\-\-\-\-\-\- created: 2019\-06\-20T17:17:11 @@ -73439,7 +71670,7 @@ my\-linode\-config: expiry: None id: - linode/alpine3.10 + linode/ubuntu22.04 is_public: True label: @@ -74933,6 +73164,14 @@ resources such as servers. The default wait_for_timeout is 15 minutes. For more information concerning cloud profiles, see \fI\%here\fP\&. .SS Getting Started With Proxmox .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This cloud provider will be removed from Salt in version 3009.0 in favor of +the \fI\%saltext.proxmox Salt Extension\fP +.UNINDENT +.UNINDENT +.sp Proxmox Virtual Environment is a complete server virtualization management solution, based on OpenVZ(in Proxmox up to 3.4)/LXC(from Proxmox 4.0 and up) and full virtualization with KVM. Further information can be found at: @@ -79398,10 +77637,7 @@ upon execution. Most often, it uses \fBget_configured_provider()\fP to determine if the necessary configuration has been set up. It may also check for necessary imports, to decide whether to load the module. In most cases, it will return a \fBTrue\fP or \fBFalse\fP value. If the name of the driver used does not match the -filename, then that name should be returned instead of \fBTrue\fP\&. An example of -this may be seen in the Azure module: -.sp -\fI\%https://github.com/saltstack/salt/tree/master/salt/cloud/clouds/msazure.py\fP +filename, then that name should be returned instead of \fBTrue\fP\&. .SS The get_configured_provider() Function .sp This function uses \fBconfig.is_provider_configured()\fP to determine whether @@ -79632,8 +77868,7 @@ salt\-cloud \-\-list\-sizes my\-cloud\-provider .sp This function builds the deploy script to be used on the remote machine. It is likely to be moved into the \fBsalt.utils.cloud\fP library in the near future, as -it is very generic and can usually be copied wholesale from another module. An -excellent example is in the Azure driver. +it is very generic and can usually be copied wholesale from another module. .SS The destroy() Function .sp This function irreversibly destroys a virtual machine on the cloud provider. @@ -85326,6 +83561,12 @@ are built with the \fI\%relenv\fP tool. .sp The Salt Project uses docker containers to build our deb and rpm packages. If you are building your own packages you can use the same containers we build with in the Github piplines. These containers are documented \fI\%here\fP\&. +.SS Package Grain +.sp +In the 3007.0 release a new package grain was added. This detects how Salt was installed using the \fI_pkg.txt\fP +in the root of the Salt repo. By default this is set to \fBpip\fP, but it is set to \fBonedir\fP when \fBtools pkg build salt\-onedir\fP +is run in our pipelines when building our onedir packages. If you are building your own custom packages, please ensure you set +\fB_pkg.txt\fP contents to be the type of package you are creating. The options are \fBpip\fP, \fBonedir\fP or \fBsystem\fP\&. .SS How to build onedir only .INDENT 0.0 .IP 1. 3 @@ -91663,6 +89904,8 @@ mysql.user: None mysql.password: None mysql.database: salt_cache mysql.table_name: cache +# This may be enabled to create a fresh connection on every call +mysql.fresh_connection: false .ft P .fi .UNINDENT @@ -91715,7 +89958,7 @@ bank. Get a cursor and run a query. Reconnect up to \fBretries\fP times if needed. Returns: cursor, affected rows counter -Raises: SaltCacheError, AttributeError, OperationalError +Raises: SaltCacheError, AttributeError, OperationalError, InterfaceError .UNINDENT .INDENT 0.0 .TP @@ -92003,12 +90246,6 @@ AliYun ECS Cloud Module T} _ T{ -\fI\%azurearm\fP -T} T{ -Azure ARM Cloud Module -T} -_ -T{ \fI\%clc\fP T} T{ CenturyLink Cloud Module @@ -92081,12 +90318,6 @@ Install Salt on an LXC Container T} _ T{ -\fI\%msazure\fP -T} T{ -Azure Cloud Module -T} -_ -T{ \fI\%oneandone\fP T} T{ 1&1 Cloud Server Module @@ -92125,7 +90356,6 @@ _ T{ \fI\%proxmox\fP T} T{ -Proxmox Cloud Module T} _ T{ @@ -92458,366 +90688,6 @@ salt\-cloud \-a stop myinstance force=True .UNINDENT .UNINDENT .UNINDENT -.SS salt.cloud.clouds.azurearm -.SS Azure ARM Cloud Module -.sp -New in version 2016.11.0. - -.sp -Changed in version 2019.2.0. - -.sp -The Azure ARM cloud module is used to control access to Microsoft Azure Resource Manager -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0rc6 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.4 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 0.33.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 0.30.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.30.0rc6 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.32.0 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B configuration -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.TP -.B if using Managed Service Identity authentication: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 7.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.IP \(bu 2 -HTTP base URL for a custom endpoint, such as Azure Stack. The \fB/metadata/endpoints\fP path will be added to the URL. -.UNINDENT -.TP -\fBuserdata\fP and \fBuserdata_file\fP: -Azure Resource Manager uses a separate VirtualMachineExtension object to pass userdata scripts to the virtual -machine. Arbitrary shell commands can be passed via the \fBuserdata\fP parameter, or via a file local to the Salt -Cloud system using the \fBuserdata_file\fP parameter. Note that the local file is not treated as a script by the -extension, so \(dqone\-liners\(dq probably work best. If greater functionality is desired, a web\-hosted script file can -be specified via \fBuserdata_file: https://raw.githubusercontent.com/account/repo/master/azure\-script.py\fP, which -will be executed on the system after VM creation. For Windows systems, script files ending in \fB\&.ps1\fP will be -executed with \fBpowershell.exe\fP\&. The \fBuserdata\fP parameter takes precedence over the \fBuserdata_file\fP parameter -when creating the custom script extension. -.TP -\fBwin_installer\fP: -This parameter, which holds the local path to the Salt Minion installer package, is used to determine if the -virtual machine type will be \(dqWindows\(dq. Only set this parameter on profiles which install Windows operating systems. -.UNINDENT -.UNINDENT -.sp -Example \fB/etc/salt/cloud.providers\fP or -\fB/etc/salt/cloud.providers.d/azure.conf\fP configuration: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-azure\-config with username and password: - driver: azurearm - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - username: larry - password: 123pass - -Or my\-azure\-config with service principal: - driver: azurearm - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - secret: XXXXXXXXXXXXXXXXXXXXXXXX - cloud_environment: AZURE_US_GOV_CLOUD - - The Service Principal can be created with the new Azure CLI (https://github.com/Azure/azure\-cli) with: - az ad sp create\-for\-rbac \-n \(dqhttp://\(dq \-\-role \-\-scopes - For example, this creates a service principal with \(aqowner\(aq role for the whole subscription: - az ad sp create\-for\-rbac \-n \(dqhttp://mysaltapp\(dq \-\-role owner \-\-scopes /subscriptions/3287abc8\-f98a\-c678\-3bde\-326766fd3617 - - *Note: review the details of Service Principals. Owner role is more than you normally need, and you can restrict - scope to a resource group or individual resources. -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.avail_images(call=None) -Return a dict of all available images on the provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.avail_locations(call=None) -Return a dict of all available regions. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.avail_sizes(call=None) -Return a list of sizes available from the provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.create(vm_) -Create a single VM from a data dict. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.create_network_interface(call=None, kwargs=None) -Create a network interface. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.create_or_update_vmextension(call=None, kwargs=None) -New in version 2019.2.0. - -.sp -Create or update a VM extension object \(dqinside\(dq of a VM object. -.INDENT 7.0 -.TP -.B required kwargs: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -extension_name: myvmextension -virtual_machine_name: myvm -settings: {\(dqcommandToExecute\(dq: \(dqhostname\(dq} -.ft P -.fi -.UNINDENT -.UNINDENT -.TP -.B optional kwargs: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -resource_group: < inferred from cloud configs > -location: < inferred from cloud configs > -publisher: < default: Microsoft.Azure.Extensions > -virtual_machine_extension_type: < default: CustomScript > -type_handler_version: < default: 2.0 > -auto_upgrade_minor_version: < default: True > -protected_settings: < default: None > -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.delete_blob(call=None, kwargs=None) -Delete a blob from a container. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.delete_interface(call=None, kwargs=None) -Delete a network interface. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.delete_managed_disk(call=None, kwargs=None) -Delete a managed disk from a resource group. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.destroy(name, call=None, kwargs=None) -Destroy a VM. -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-d myminion -salt\-cloud \-a destroy myminion service_name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_api_versions(call=None, kwargs=None) -Get a resource type api versions -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_configured_provider() -Return the first configured provider instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_conn(client_type) -Return a connection object for a client type. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_dependencies() -Warn if dependencies aren\(aqt met. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_location(call=None, kwargs=None) -Return the location that is configured for this provider -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.get_resource_by_id(resource_id, api_version, extract_value=None) -Get an AzureARM resource by id -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_blobs(call=None, kwargs=None) -List blobs. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_nodes(call=None) -List VMs on this Azure account -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_nodes_full(call=None) -List all VMs on the subscription with full information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_resource_groups(call=None) -List resource groups associated with the subscription -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_storage_accounts(call=None) -List storage accounts within the subscription. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_subnets(call=None, kwargs=None) -List subnets in a virtual network. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.list_virtual_networks(call=None, kwargs=None) -List virtual networks. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.request_instance(vm_, kwargs=None) -Request a VM from Azure. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.show_instance(name, call=None) -Show the details from AzureARM concerning an instance -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.start(name, call=None) -New in version 2019.2.0. - -.sp -Start a VM -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a start myminion -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.azurearm.stop(name, call=None) -New in version 2019.2.0. - -.sp -Stop (deallocate) a VM -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-a stop myminion -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.cloud.clouds.clc .SS CenturyLink Cloud Module .sp @@ -96517,8 +94387,6 @@ Return a list of the VMs that are on the provider, with select fields .SS The Linode Cloud Module .sp The Linode cloud module is used to interact with the Linode Cloud. -.sp -You can target a specific version of the Linode API with the \fBapi_version\fP parameter. The default is \fBv3\fP\&. .SS Provider .sp The following provider parameters are supported: @@ -96528,8 +94396,6 @@ The following provider parameters are supported: .IP \(bu 2 \fBpassword\fP: (required) The default password to set on new VMs. Must be 8 characters with at least one lowercase, uppercase, and numeric. .IP \(bu 2 -\fBapi_version\fP: (optional) The version of the Linode API to interact with. Defaults to \fBv3\fP\&. -.IP \(bu 2 \fBpoll_interval\fP: (optional) The rate of time in milliseconds to poll the Linode API for changes. Defaults to \fB500\fP\&. .IP \(bu 2 \fBratelimit_sleep\fP: (optional) The time in seconds to wait before retrying after a ratelimit has been enforced. Defaults to \fB0\fP\&. @@ -96538,8 +94404,8 @@ The following provider parameters are supported: \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -APIv3 usage is deprecated and will be removed in a future release in favor of APIv4. To move to APIv4 now, -set the \fBapi_version\fP parameter in your provider configuration to \fBv4\fP\&. See the full migration guide +APIv3 usage has been removed in favor of APIv4. To move to APIv4 now, +See the full migration guide here \fI\%https://docs.saltproject.io/en/latest/topics/cloud/linode.html#migrating\-to\-apiv4\fP\&. .UNINDENT .UNINDENT @@ -96552,24 +94418,8 @@ Set up the provider configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/ .ft C my\-linode\-provider: driver: linode - api_version: v4 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... - password: F00barbaz -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -For use with APIv3 (deprecated): -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-linode\-provider\-v3: - driver: linode - apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... - password: F00barbaz + password: F00barbazverylongp@ssword .ft P .fi .UNINDENT @@ -96579,15 +94429,17 @@ my\-linode\-provider\-v3: The following profile parameters are supported: .INDENT 0.0 .IP \(bu 2 -\fBsize\fP: (required) The size of the VM. This should be a Linode instance type ID (i.e. \fBg6\-standard\-2\fP). For APIv3, this would be a plan ID (i.e. \fBLinode 2GB\fP). Run \fBsalt\-cloud \-f avail_sizes my\-linode\-provider\fP for options. +\fBsize\fP: (required) The size of the VM. This should be a Linode instance type ID (i.e. \fBg6\-standard\-2\fP). Run \fBsalt\-cloud \-f avail_sizes my\-linode\-provider\fP for options. .IP \(bu 2 -\fBlocation\fP: (required) The location of the VM. This should be a Linode region (e.g. \fBus\-east\fP). For APIv3, this would be a datacenter location (i.e. \fBNewark, NJ, USA\fP). Run \fBsalt\-cloud \-f avail_locations my\-linode\-provider\fP for options. +\fBlocation\fP: (required) The location of the VM. This should be a Linode region (e.g. \fBus\-east\fP). Run \fBsalt\-cloud \-f avail_locations my\-linode\-provider\fP for options. .IP \(bu 2 -\fBimage\fP: (required) The image to deploy the boot disk from. This should be an image ID (e.g. \fBlinode/ubuntu16.04\fP); official images start with \fBlinode/\fP\&. For APIv3, this would be an image label (i.e. Ubuntu 16.04). Run \fBsalt\-cloud \-f avail_images my\-linode\-provider\fP for more options. +\fBimage\fP: (required) The image to deploy the boot disk from. This should be an image ID (e.g. \fBlinode/ubuntu22.04\fP); official images start with \fBlinode/\fP\&. Run \fBsalt\-cloud \-f avail_images my\-linode\-provider\fP for more options. .IP \(bu 2 \fBpassword\fP: (*required) The default password for the VM. Must be provided at the profile or provider level. .IP \(bu 2 -\fBassign_private_ip\fP: (optional) Whether or not to assign a private key to the VM. Defaults to \fBFalse\fP\&. +\fBassign_private_ip\fP: (optional) Whether or not to assign a private IP to the VM. Defaults to \fBFalse\fP\&. +.IP \(bu 2 +\fBbackups_enabled\fP: (optional) Whether or not to enable the backup for this VM. Backup can be configured in your Linode account Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBssh_interface\fP: (optional) The interface with which to connect over SSH. Valid options are \fBprivate_ips\fP or \fBpublic_ips\fP\&. Defaults to \fBpublic_ips\fP\&. .IP \(bu 2 @@ -96596,8 +94448,6 @@ The following profile parameters are supported: \fBswap\fP: (optional) The amount of disk space to allocate for the swap partition. Defaults to \fB256\fP\&. .IP \(bu 2 \fBclonefrom\fP: (optional) The name of the Linode to clone from. -.IP \(bu 2 -\fBdisk_size\fP: (deprecated, optional) The amount of disk space to allocate for the OS disk. This has no effect with APIv4; the size of the boot disk will be the remainder of disk space after the swap parition is allocated. .UNINDENT .sp Set up a profile configuration in \fB/etc/salt/cloud.profiles.d/\fP: @@ -96610,36 +94460,27 @@ my\-linode\-profile: # a minimal configuration provider: my\-linode\-provider size: g6\-standard\-1 - image: linode/alpine3.12 + image: linode/ubuntu22.04 location: us\-east my\-linode\-profile\-advanced: # an advanced configuration provider: my\-linode\-provider size: g6\-standard\-3 - image: linode/alpine3.10 + image: linode/ubuntu22.04 location: eu\-west password: bogus123X assign_private_ip: true ssh_interface: private_ips ssh_pubkey: ssh\-rsa AAAAB3NzaC1yc2EAAAADAQAB... swap_size: 512 - -my\-linode\-profile\-v3: - # a legacy configuration - provider: my\-linode\-provider\-v3 - size: Nanode 1GB - image: Alpine 3.12 - location: Fremont, CA, USA .ft P .fi .UNINDENT .UNINDENT .SS Migrating to APIv4 .sp -In order to target APIv4, ensure your provider configuration has \fBapi_version\fP set to \fBv4\fP\&. -.sp -You will also need to generate a new token for your account. See \fI\%https://www.linode.com/docs/platform/api/getting\-started\-with\-the\-linode\-api/#create\-an\-api\-token\fP +You will need to generate a new token for your account. See \fI\%https://www.linode.com/docs/products/tools/api/get\-started/#create\-an\-api\-token\fP .sp There are a few changes to note: \- There has been a general move from label references to ID references. The profile configuration parameters \fBlocation\fP, \fBsize\fP, and \fBimage\fP have moved from being label based references to IDs. See the profile section for more information. In addition to these inputs being changed, \fBavail_sizes\fP, \fBavail_locations\fP, and \fBavail_images\fP now output options sorted by ID instead of label. @@ -96647,10 +94488,7 @@ There are a few changes to note: .INDENT 0.0 .TP .B maintainer -Charles Kenney <\fI\%ckenney@linode.com\fP> -.TP -.B maintainer -Phillip Campbell <\fI\%pcampbell@linode.com\fP> +Linode Developer Tools and Experience Team <\fI\%dev\-dx@linode.com\fP> .TP .B depends requests @@ -96709,11 +94547,6 @@ get_config_id implementation .UNINDENT .INDENT 7.0 .TP -.B get_plan_id(kwargs=None) -get_plan_id implementation -.UNINDENT -.INDENT 7.0 -.TP .B abstract list_nodes() list_nodes implementation .UNINDENT @@ -96759,100 +94592,6 @@ stop implementation .UNINDENT .INDENT 0.0 .TP -.B class salt.cloud.clouds.linode.LinodeAPIv3 -.INDENT 7.0 -.TP -.B avail_images() -avail_images implementation -.UNINDENT -.INDENT 7.0 -.TP -.B avail_locations() -avail_locations implementation -.UNINDENT -.INDENT 7.0 -.TP -.B avail_sizes() -avail_sizes implementation -.UNINDENT -.INDENT 7.0 -.TP -.B boot(name=None, kwargs=None) -boot implementation -.UNINDENT -.INDENT 7.0 -.TP -.B clone(kwargs=None) -clone implementation -.UNINDENT -.INDENT 7.0 -.TP -.B create(vm_) -create implementation -.UNINDENT -.INDENT 7.0 -.TP -.B create_config(kwargs=None) -create_config implementation -.UNINDENT -.INDENT 7.0 -.TP -.B destroy(name) -destroy implementation -.UNINDENT -.INDENT 7.0 -.TP -.B get_config_id(kwargs=None) -get_config_id implementation -.UNINDENT -.INDENT 7.0 -.TP -.B get_plan_id(kwargs=None) -get_plan_id implementation -.UNINDENT -.INDENT 7.0 -.TP -.B list_nodes() -list_nodes implementation -.UNINDENT -.INDENT 7.0 -.TP -.B list_nodes_full() -list_nodes_full implementation -.UNINDENT -.INDENT 7.0 -.TP -.B list_nodes_min() -list_nodes_min implementation -.UNINDENT -.INDENT 7.0 -.TP -.B reboot(name) -reboot implementation -.UNINDENT -.INDENT 7.0 -.TP -.B show_instance(name) -show_instance implementation -.UNINDENT -.INDENT 7.0 -.TP -.B show_pricing(kwargs=None) -show_pricing implementation -.UNINDENT -.INDENT 7.0 -.TP -.B start(name) -start implementation -.UNINDENT -.INDENT 7.0 -.TP -.B stop(name) -stop implementation -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP .B class salt.cloud.clouds.linode.LinodeAPIv4 .INDENT 7.0 .TP @@ -96896,6 +94635,10 @@ destroy implementation .UNINDENT .INDENT 7.0 .TP +.B classmethod get_api_instance() +.UNINDENT +.INDENT 7.0 +.TP .B get_config_id(kwargs=None) get_config_id implementation .UNINDENT @@ -96921,6 +94664,10 @@ reboot implementation .UNINDENT .INDENT 7.0 .TP +.B set_backup_schedule(label, linode_id, day, window, auto_enable=False) +.UNINDENT +.INDENT 7.0 +.TP .B show_instance(name) show_instance implementation .UNINDENT @@ -97057,14 +94804,6 @@ The location of the new Linode. Required. .TP .B size The size of the new Linode (must be greater than or equal to the clone source). Required. -.TP -.B datacenter_id -The ID of the Datacenter where the Linode will be placed. Required for APIv3 usage. -Deprecated. Use \fBlocation\fP instead. -.TP -.B plan_id -The ID of the plan (size) of the Linode. Required. Required for APIv3 usage. -Deprecated. Use \fBsize\fP instead. .UNINDENT .sp CLI Example: @@ -97073,7 +94812,7 @@ CLI Example: .sp .nf .ft C -salt\-cloud \-f clone my\-linode\-config linode_id=1234567 datacenter_id=2 plan_id=5 +salt\-cloud \-f clone my\-linode\-config linode_id=1234567 location=us\-central size=g6\-standard\-1 .ft P .fi .UNINDENT @@ -97203,29 +94942,6 @@ salt\-cloud \-f get_linode my\-linode\-config linode_id=1234567 .UNINDENT .INDENT 0.0 .TP -.B salt.cloud.clouds.linode.get_plan_id(kwargs=None, call=None) -Returns the Linode Plan ID. -.INDENT 7.0 -.TP -.B label -The label, or name, of the plan to get the ID from. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_plan_id linode label=\(dqNanode 1GB\(dq -salt\-cloud \-f get_plan_id linode label=\(dqLinode 2GB\(dq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP .B salt.cloud.clouds.linode.list_nodes(call=None) Returns a list of linodes, keeping only a brief listing. .sp @@ -97335,6 +95051,81 @@ salt\-cloud \-a reboot vm_name .UNINDENT .INDENT 0.0 .TP +.B salt.cloud.clouds.linode.set_backup_schedule(name=None, kwargs=None, call=None) +Set the backup schedule for a Linode. +.INDENT 7.0 +.TP +.B name +The name (label) of the Linode. Can be used instead of +\fBlinode_id\fP\&. +.TP +.B linode_id +The ID of the Linode instance to set the backup schedule for. +If provided, will be used as an alternative to \fBname\fP and +reduces the number of API calls to Linode by one. Will be +preferred over \fBname\fP\&. +.TP +.B auto_enable +If \fBTrue\fP, automatically enable the backup feature for the Linode +if it wasn\(aqt already enabled. Optional parameter, default to \fBFalse\fP\&. +.TP +.B day +Possible values: +\fBSunday\fP, \fBMonday\fP, \fBTuesday\fP, \fBWednesday\fP, +\fBThursday\fP, \fBFriday\fP, \fBSaturday\fP +.sp +The day of the week that your Linode\(aqs weekly Backup is taken. +If not set manually, a day will be chosen for you. Backups are +taken every day, but backups taken on this day are preferred +when selecting backups to retain for a longer period. +.sp +If not set manually, then when backups are initially enabled, +this may come back as \fBScheduling\fP until the day is automatically +selected. +.TP +.B window +Possible values: +\fBW0\fP, \fBW2\fP, \fBW4\fP, \fBW6\fP, \fBW8\fP, \fBW10\fP, +\fBW12\fP, \fBW14\fP, \fBW16\fP, \fBW18\fP, \fBW20\fP, \fBW22\fP +.sp +The window in which your backups will be taken, in UTC. A backups +window is a two\-hour span of time in which the backup may occur. +.sp +For example, \fBW10\fP indicates that your backups should be taken +between 10:00 and 12:00. If you do not choose a backup window, one +will be selected for you automatically. +.sp +If not set manually, when backups are initially enabled this may come +back as \fBScheduling\fP until the window is automatically selected. +.UNINDENT +.sp +Can be called as an action (which requires a name): +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-a set_backup_schedule my\-linode\-instance day=Monday window=W20 auto_enable=True +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...or as a function (which requires either a name or linode_id): +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-cloud \-f set_backup_schedule my\-linode\-provider name=my\-linode\-instance day=Monday window=W20 auto_enable=True +salt\-cloud \-f set_backup_schedule my\-linode\-provider linode_id=1225876 day=Monday window=W20 auto_enable=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.cloud.clouds.linode.show_instance(name, call=None) Displays details about a particular Linode VM. Either a name or a linode_id must be provided. @@ -97487,1918 +95278,6 @@ Return a list of the VMs that are on the provider, with select fields .B salt.cloud.clouds.lxc.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT -.SS salt.cloud.clouds.msazure -.SS Azure Cloud Module -.sp -The Azure cloud module is used to control access to Microsoft Azure -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 due to -the deprecation of the \(dqClassic\(dq API for Azure. Please migrate to -\fI\%Azure Resource Manager by March 1, 2023\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%Microsoft Azure SDK for Python\fP >= 1.0.2 -.IP \(bu 2 -python\-requests, for Python < 2.7.9 -.UNINDENT -.TP -.B configuration -Required provider parameters: -.INDENT 7.0 -.IP \(bu 2 -\fBapikey\fP -.IP \(bu 2 -\fBcertificate_path\fP -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBbackend\fP -.UNINDENT -.sp -A Management Certificate (.pem and .crt files) must be created and the .pem -file placed on the same machine that salt\-cloud is run from. Information on -creating the pem file to use, and uploading the associated cer file can be -found at: -.sp -\fI\%http://www.windowsazure.com/en\-us/develop/python/how\-to\-guides/service\-management/\fP -.sp -For users with Python < 2.7.9, \fBbackend\fP must currently be set to \fBrequests\fP\&. -.UNINDENT -.sp -Example \fB/etc/salt/cloud.providers\fP or -\fB/etc/salt/cloud.providers.d/azure.conf\fP configuration: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -my\-azure\-config: - driver: azure - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - certificate_path: /etc/salt/azure.pem - management_host: management.core.windows.net -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.add_input_endpoint(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Add an input endpoint to the deployment. Please note that -there may be a delay before the changes show up. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP local_port=80 \e - port=80 protocol=tcp enable_direct_server_return=False \e - timeout_for_tcp_idle_connection=4 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.add_management_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Add a new management certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_management_certificate my\-azure public_key=\(aq...PUBKEY...\(aq \e - thumbprint=0123456789ABCDEF data=\(aq...CERT_DATA...\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.add_service_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Add a new service certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f add_service_certificate my\-azure name=my_service_certificate \e - data=\(aq...CERT_DATA...\(aq certificate_format=sha1 password=verybadpass -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.avail_images(conn=None, call=None) -List available images for Azure -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.avail_locations(conn=None, call=None) -List available locations for Azure -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.avail_sizes(call=None) -Return a list of sizes from Azure -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.cleanup_unattached_disks(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Cleans up all disks associated with the account, which are not attached. -\fB* CAUTION *\fP This is a destructive function with no undo button, and no -\(dqAre you sure?\(dq confirmation! -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f cleanup_unattached_disks my\-azure name=my_disk -salt\-cloud \-f cleanup_unattached_disks my\-azure name=my_disk delete_vhd=True -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create(vm_) -Create a single VM from a data dict -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create_affinity_group(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Create a new affinity group -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_affinity_group my\-azure name=my_affinity_group -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True) -Create and attach volumes to created node -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create_service(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Create a new hosted service -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_service my\-azure name=my_service label=my_service location=\(aqWest US\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Create a new storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_storage my\-azure name=my_storage label=my_storage location=\(aqWest US\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.create_storage_container(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Create a storage container -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f create_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to create. -.TP -.B meta_name_values: -Optional. A dict with name_value pairs to associate with the -container as metadata. Example:{\(aqCategory\(aq:\(aqtest\(aq} -.TP -.B blob_public_access: -Optional. Possible values include: container, blob -.TP -.B fail_on_exist: -Specify whether to throw an exception when the container exists. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_affinity_group(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific affinity group associated with the account -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_affinity_group my\-azure name=my_affinity_group -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_disk(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific disk associated with the account -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_disk my\-azure name=my_disk -salt\-cloud \-f delete_disk my\-azure name=my_disk delete_vhd=True -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_input_endpoint(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete an input endpoint from the deployment. Please note that -there may be a delay before the changes show up. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_management_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific certificate associated with the management -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_management_certificate my\-azure name=my_management_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_service(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific service associated with the account -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_service my\-azure name=my_service -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_service_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific certificate associated with the service -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_service_certificate my\-azure name=my_service_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a specific storage account -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_storage my\-azure name=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.delete_storage_container(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Delete a container associated with the storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f delete_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to create. -.TP -.B fail_not_exist: -Specify whether to throw an exception when the container exists. -.TP -.B lease_id: -If specified, delete_storage_container only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.destroy(name, conn=None, call=None, kwargs=None) -Destroy a VM -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-d myminion -salt\-cloud \-a destroy myminion service_name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_affinity_group(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show an affinity group associated with the account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_affinity_group my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_blob(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Download a blob -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_blob my\-azure container=base name=top.sls local_path=/srv/salt/top.sls -salt\-cloud \-f get_blob my\-azure container=base name=content.txt return_content=True -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of existing container. -.TP -.B name: -Name of existing blob. -.TP -.B local_path: -The path on the local machine to download the blob to. Either this or -return_content must be specified. -.TP -.B return_content: -Whether or not to return the content directly from the blob. If -specified, must be True or False. Either this or the local_path must -be specified. -.TP -.B snapshot: -Optional. The snapshot parameter is an opaque DateTime value that, -when present, specifies the blob snapshot to retrieve. -.TP -.B lease_id: -Required if the blob has an active lease. -.TP -.B progress_callback: -callback for progress with signature function(current, total) where -current is the number of bytes transferred so far, and total is the -size of the blob. -.TP -.B max_connections: -Maximum number of parallel connections to use when the blob size -exceeds 64MB. -Set to 1 to download the blob chunks sequentially. -Set to 2 or more to download the blob chunks in parallel. This uses -more system resources but will download faster. -.TP -.B max_retries: -Number of times to retry download of blob chunk if an error occurs. -.TP -.B retry_wait: -Sleep time in secs between retries. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_blob_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Returns all user\-defined metadata, standard HTTP properties, and -system properties for the blob. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_properties my\-azure container=mycontainer blob=myblob -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of existing container. -.TP -.B blob: -Name of existing blob. -.TP -.B lease_id: -Required if the blob has an active lease. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_blob_service_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a blob\(aqs service properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_service_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_configured_provider() -Return the first configured instance. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_conn() -Return a conn object for the passed VM data -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_dependencies() -Warn if dependencies aren\(aqt met. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_deployment(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_deployment my\-azure name=my_deployment -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_disk(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a disk -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_disk my\-azure name=my_disk -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_input_endpoint(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show an input endpoint associated with the deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_management_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a management_certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_operation_status(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Get Operation Status, based on a request ID -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_operation_status my\-azure id=0123456789abcdef0123456789abcdef -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_service_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a service certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List storage service properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage my\-azure name=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage_conn(storage_account=None, storage_key=None, conn_kwargs=None) -New in version 2015.8.0. - -.sp -Return a storage_conn object for the storage account -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage_container(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a container associated with the storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to show. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage_container_acl(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a storage container\(aqs acl -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_acl my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of existing container. -.TP -.B lease_id: -If specified, show_storage_container_acl only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage_container_metadata(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a storage container\(aqs metadata -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to show. -.TP -.B lease_id: -If specified, show_storage_container_metadata only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.get_storage_keys(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show storage account keys -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_keys my\-azure name=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.lease_storage_container(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Lease a container associated with the storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f lease_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to create. -.TP -.B lease_action: -Required. Possible values: acquire|renew|release|break|change -.TP -.B lease_id: -Required if the container has an active lease. -.TP -.B lease_duration: -Specifies the duration of the lease, in seconds, or negative one -(\-1) for a lease that never expires. A non\-infinite lease can be -between 15 and 60 seconds. A lease duration cannot be changed -using renew or change. For backwards compatibility, the default is -60, and the value is only used on an acquire operation. -.TP -.B lease_break_period: -Optional. For a break operation, this is the proposed duration of -seconds that the lease should continue before it is broken, between -0 and 60 seconds. This break period is only used if it is shorter -than the time remaining on the lease. If longer, the time remaining -on the lease is used. A new lease will not be available before the -break period has expired, but the lease may be held for longer than -the break period. If this header does not appear with a break -operation, a fixed\-duration lease breaks after the remaining lease -period elapses, and an infinite lease breaks immediately. -.TP -.B proposed_lease_id: -Optional for acquire, required for change. Proposed lease ID, in a -GUID string format. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_affinity_groups(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List input endpoints associated with the deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_affinity_groups my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_blobs(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -List blobs associated with the container -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_blobs my\-azure container=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -The name of the storage container -.TP -.B prefix: -Optional. Filters the results to return only blobs whose names -begin with the specified prefix. -.TP -.B marker: -Optional. A string value that identifies the portion of the list -to be returned with the next list operation. The operation returns -a marker value within the response body if the list returned was -not complete. The marker value may then be used in a subsequent -call to request the next set of list items. The marker value is -opaque to the client. -.TP -.B maxresults: -Optional. Specifies the maximum number of blobs to return, -including all BlobPrefix elements. If the request does not specify -maxresults or specifies a value greater than 5,000, the server will -return up to 5,000 items. Setting maxresults to a value less than -or equal to zero results in error response code 400 (Bad Request). -.TP -.B include: -Optional. Specifies one or more datasets to include in the -response. To specify more than one of these options on the URI, -you must separate each option with a comma. Valid values are: -.INDENT 7.0 -.TP -.B snapshots: -Specifies that snapshots should be included in the -enumeration. Snapshots are listed from oldest to newest in -the response. -.TP -.B metadata: -Specifies that blob metadata be returned in the response. -.TP -.B uncommittedblobs: -Specifies that blobs for which blocks have been uploaded, -but which have not been committed using Put Block List -(REST API), be included in the response. -.TP -.B copy: -Version 2012\-02\-12 and newer. Specifies that metadata -related to any current or previous Copy Blob operation -should be included in the response. -.UNINDENT -.TP -.B delimiter: -Optional. When the request includes this parameter, the operation -returns a BlobPrefix element in the response body that acts as a -placeholder for all blobs whose names begin with the same -substring up to the appearance of the delimiter character. The -delimiter may be a single character or a string. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_disks(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List disks associated with the account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_disks my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_hosted_services(conn=None, call=None) -List VMs on this Azure account, with full information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_input_endpoints(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List input endpoints associated with the deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_input_endpoints my\-azure service=myservice deployment=mydeployment -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_management_certificates(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List management certificates associated with the subscription -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_management_certificates my\-azure name=my_management -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_nodes(conn=None, call=None) -List VMs on this Azure account -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_nodes_full(conn=None, call=None) -List VMs on this Azure account, with full information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_nodes_select(conn=None, call=None) -Return a list of the VMs that are on the provider, with select fields -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_service_certificates(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List certificates associated with the service -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_service_certificates my\-azure name=my_service -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_services(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List hosted services associated with the account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_services my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List storage accounts associated with the account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_storage my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_storage_containers(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -List containers associated with the storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_storage_containers my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_storage_services(conn=None, call=None) -List VMs on this Azure account, with full information -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.list_virtual_networks(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List input endpoints associated with the deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f list_virtual_networks my\-azure service=myservice deployment=mydeployment -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.make_blob_url(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Creates the URL to access a blob -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f make_blob_url my\-azure container=mycontainer blob=myblob -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of the container. -.TP -.B blob: -Name of the blob. -.TP -.B account: -Name of the storage account. If not specified, derives the host base -from the provider configuration. -.TP -.B protocol: -Protocol to use: \(aqhttp\(aq or \(aqhttps\(aq. If not specified, derives the host -base from the provider configuration. -.TP -.B host_base: -Live host base URL. If not specified, derives the host base from the -provider configuration. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.put_blob(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Upload a blob -.sp -CLI Examples: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f put_blob my\-azure container=base name=top.sls blob_path=/srv/salt/top.sls -salt\-cloud \-f put_blob my\-azure container=base name=content.txt blob_content=\(aqSome content\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of existing container. -.TP -.B name: -Name of existing blob. -.TP -.B blob_path: -The path on the local machine of the file to upload as a blob. Either -this or blob_content must be specified. -.TP -.B blob_content: -The actual content to be uploaded as a blob. Either this or blob_path -must me specified. -.TP -.B cache_control: -Optional. The Blob service stores this value but does not use or -modify it. -.TP -.B content_language: -Optional. Specifies the natural languages used by this resource. -.TP -.B content_md5: -Optional. An MD5 hash of the blob content. This hash is used to -verify the integrity of the blob during transport. When this header -is specified, the storage service checks the hash that has arrived -with the one that was sent. If the two hashes do not match, the -operation will fail with error code 400 (Bad Request). -.TP -.B blob_content_type: -Optional. Set the blob\(aqs content type. -.TP -.B blob_content_encoding: -Optional. Set the blob\(aqs content encoding. -.TP -.B blob_content_language: -Optional. Set the blob\(aqs content language. -.TP -.B blob_content_md5: -Optional. Set the blob\(aqs MD5 hash. -.TP -.B blob_cache_control: -Optional. Sets the blob\(aqs cache control. -.TP -.B meta_name_values: -A dict containing name, value for metadata. -.TP -.B lease_id: -Required if the blob has an active lease. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.query(path, method=\(aqGET\(aq, data=None, params=None, header_dict=None, decode=True) -Perform a query directly against the Azure REST API -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.regenerate_storage_keys(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Regenerate storage account keys. Requires a key_type (\(dqprimary\(dq or -\(dqsecondary\(dq) to be specified. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f regenerate_storage_keys my\-azure name=my_storage key_type=primary -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.script(vm_) -Return the script deployment object -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.set_blob_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Set a blob\(aqs properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_blob_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of existing container. -.TP -.B blob: -Name of existing blob. -.TP -.B blob_cache_control: -Optional. Modifies the cache control string for the blob. -.TP -.B blob_content_type: -Optional. Sets the blob\(aqs content type. -.TP -.B blob_content_md5: -Optional. Sets the blob\(aqs MD5 hash. -.TP -.B blob_content_encoding: -Optional. Sets the blob\(aqs content encoding. -.TP -.B blob_content_language: -Optional. Sets the blob\(aqs content language. -.TP -.B lease_id: -Required if the blob has an active lease. -.TP -.B blob_content_disposition: -Optional. Sets the blob\(aqs Content\-Disposition header. -The Content\-Disposition response header field conveys additional -information about how to process the response payload, and also can -be used to attach additional metadata. For example, if set to -attachment, it indicates that the user\-agent should not display the -response, but instead show a Save As dialog with a filename other -than the blob name specified. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.set_blob_service_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Sets the properties of a storage account\(aqs Blob service, including -Windows Azure Storage Analytics. You can also use this operation to -set the default request version for all incoming requests that do not -have a version specified. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_blob_service_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B properties: -a StorageServiceProperties object. -.TP -.B timeout: -Optional. The timeout parameter is expressed in seconds. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.set_storage_container_acl(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Set a storage container\(aqs acl -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_storage_container my\-azure name=mycontainer -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of existing container. -.TP -.B signed_identifiers: -SignedIdentifers instance -.TP -.B blob_public_access: -Optional. Possible values include: container, blob -.TP -.B lease_id: -If specified, set_storage_container_acl only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.set_storage_container_metadata(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Set a storage container\(aqs metadata -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f set_storage_container my\-azure name=mycontainer \e - x_ms_meta_name_values=\(aq{\(dqmy_name\(dq: \(dqmy_value\(dq}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of existing container. -.TP -.B meta_name_values: -A dict containing name, value for metadata. -Example: {\(aqcategory\(aq:\(aqtest\(aq} -.TP -.B lease_id: -If specified, set_storage_container_metadata only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_affinity_group(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show an affinity group associated with the account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_affinity_group my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_blob_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Returns all user\-defined metadata, standard HTTP properties, and -system properties for the blob. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_properties my\-azure container=mycontainer blob=myblob -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B container: -Name of existing container. -.TP -.B blob: -Name of existing blob. -.TP -.B lease_id: -Required if the blob has an active lease. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_blob_service_properties(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a blob\(aqs service properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_blob_service_properties my\-azure -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_deployment(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_deployment my\-azure name=my_deployment -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_disk(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a disk -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_disk my\-azure name=my_disk -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_input_endpoint(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show an input endpoint associated with the deployment -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e - deployment=mydeployment name=SSH -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_instance(name, call=None) -Show the details from the provider concerning an instance -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_management_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a management_certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_service(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List hosted service properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_service my\-azure name=my_service -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_service_certificate(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Return information about a service certificate -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e - thumbalgorithm=sha1 thumbprint=0123456789ABCDEF -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -List storage service properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage my\-azure name=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_storage_container(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a container associated with the storage account -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to show. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_storage_container_acl(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a storage container\(aqs acl -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_acl my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of existing container. -.TP -.B lease_id: -If specified, show_storage_container_acl only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_storage_container_metadata(kwargs=None, storage_conn=None, call=None) -New in version 2015.8.0. - -.sp -Show a storage container\(aqs metadata -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B name: -Name of container to show. -.TP -.B lease_id: -If specified, show_storage_container_metadata only succeeds if the -container\(aqs lease is active and matches this ID. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.show_storage_keys(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Show storage account keys -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f show_storage_keys my\-azure name=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.update_affinity_group(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Update an affinity group\(aqs properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_affinity_group my\-azure name=my_group label=my_group -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.update_disk(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Update a disk\(aqs properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_disk my\-azure name=my_disk label=my_disk -salt\-cloud \-f update_disk my\-azure name=my_disk new_name=another_disk -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.update_input_endpoint(kwargs=None, conn=None, call=None, activity=\(aqupdate\(aq) -New in version 2015.8.0. - -.sp -Update an input endpoint associated with the deployment. Please note that -there may be a delay before the changes show up. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_input_endpoint my\-azure service=myservice \e - deployment=mydeployment role=myrole name=HTTP local_port=80 \e - port=80 protocol=tcp enable_direct_server_return=False \e - timeout_for_tcp_idle_connection=4 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.cloud.clouds.msazure.update_storage(kwargs=None, conn=None, call=None) -New in version 2015.8.0. - -.sp -Update a storage account\(aqs properties -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-cloud \-f update_storage my\-azure name=my_storage label=my_storage -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.cloud.clouds.oneandone .SS 1&1 Cloud Server Module .sp @@ -103421,6 +99300,14 @@ salt\-cloud \-a stop vm_name Checks profitbricks version .UNINDENT .SS salt.cloud.clouds.proxmox +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%proxmox Salt Extension\fP\&. +.UNINDENT +.UNINDENT .SS Proxmox Cloud Module .sp New in version 2014.7.0. @@ -103450,6 +99337,14 @@ my\-proxmox\-config: .fi .UNINDENT .UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This cloud provider will be removed from Salt in version 3009.0 in favor of +the \fI\%saltext.proxmox Salt Extension\fP +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B maintainer @@ -107719,293 +103614,6 @@ salt\-cloud \-a vif_list xenvm01 .UNINDENT .UNINDENT .UNINDENT -.SS Configuring Salt -.sp -Salt configuration is very simple. The default configuration for the -\fI\%master\fP will work for most installations and the only requirement for -setting up a \fI\%minion\fP is to set the location of the master in the minion -configuration file. -.sp -The configuration files will be installed to \fB/etc/salt\fP and are named -after the respective components, \fB/etc/salt/master\fP, and -\fB/etc/salt/minion\fP\&. -.SS Master Configuration -.sp -By default the Salt master listens on ports 4505 and 4506 on all -interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the -\(dqinterface\(dq directive in the master configuration file, typically -\fB/etc/salt/master\fP, as follows: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -\- #interface: 0.0.0.0 -+ interface: 10.0.0.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -After updating the configuration file, restart the Salt master. -See the \fI\%master configuration reference\fP -for more details about other configurable options. -.SS Minion Configuration -.sp -Although there are many Salt Minion configuration options, configuring -a Salt Minion is very simple. By default a Salt Minion will -try to connect to the DNS name \(dqsalt\(dq; if the Minion is able to -resolve that name correctly, no configuration is needed. -.sp -If the DNS name \(dqsalt\(dq does not resolve to point to the correct -location of the Master, redefine the \(dqmaster\(dq directive in the minion -configuration file, typically \fB/etc/salt/minion\fP, as follows: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -\- #master: salt -+ master: 10.0.0.1 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -After updating the configuration file, restart the Salt minion. -See the \fI\%minion configuration reference\fP -for more details about other configurable options. -.SS Proxy Minion Configuration -.sp -A proxy minion emulates the behaviour of a regular minion -and inherits their options. -.sp -Similarly, the configuration file is \fB/etc/salt/proxy\fP and the proxy -tries to connect to the DNS name \(dqsalt\(dq. -.sp -In addition to the regular minion options, -there are several proxy\-specific \- see the -\fI\%proxy minion configuration reference\fP\&. -.SS Running Salt -.INDENT 0.0 -.IP 1. 3 -Start the master in the foreground (to daemonize the process, pass the -\fI\%\-d flag\fP): -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-master -.ft P -.fi -.UNINDENT -.UNINDENT -.IP 2. 3 -Start the minion in the foreground (to daemonize the process, pass the -\fI\%\-d flag\fP): -.INDENT 3.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-minion -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.IP "Having trouble?" -.sp -The simplest way to troubleshoot Salt is to run the master and minion in -the foreground with \fI\%log level\fP set to \fBdebug\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-master \-\-log\-level=debug -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -For information on salt\(aqs logging system please see the \fI\%logging -document\fP\&. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.IP "Run as an unprivileged (non\-root) user" -.sp -To run Salt as another user, set the \fI\%user\fP parameter in the -master config file. -.sp -Additionally, ownership, and permissions need to be set such that the -desired user can read from and write to the following directories (and -their subdirectories, where applicable): -.INDENT 0.0 -.IP \(bu 2 -/etc/salt -.IP \(bu 2 -/var/cache/salt -.IP \(bu 2 -/var/log/salt -.IP \(bu 2 -/var/run/salt -.UNINDENT -.sp -More information about running salt as a non\-privileged user can be found -\fI\%here\fP\&. -.UNINDENT -.UNINDENT -.sp -There is also a full \fI\%troubleshooting guide\fP -available. -.SS Key Identity -.sp -Salt provides commands to validate the identity of your Salt master -and Salt minions before the initial key exchange. Validating key identity helps -avoid inadvertently connecting to the wrong Salt master, and helps prevent -a potential MiTM attack when establishing the initial connection. -.SS Master Key Fingerprint -.sp -Print the master key fingerprint by running the following command on the Salt master: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-key \-F master -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Copy the \fBmaster.pub\fP fingerprint from the \fILocal Keys\fP section, and then set this value -as the \fI\%master_finger\fP in the minion configuration file. Save the configuration -file and then restart the Salt minion. -.SS Minion Key Fingerprint -.sp -Run the following command on each Salt minion to view the minion key fingerprint: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call \-\-local key.finger -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Compare this value to the value that is displayed when you run the -\fBsalt\-key \-\-finger \fP command on the Salt master. -.SS Key Management -.sp -Salt uses AES encryption for all communication between the Master and -the Minion. This ensures that the commands sent to the Minions cannot -be tampered with, and that communication between Master and Minion is -authenticated through trusted, accepted keys. -.sp -Before commands can be sent to a Minion, its key must be accepted on -the Master. Run the \fBsalt\-key\fP command to list the keys known to -the Salt Master: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root@master ~]# salt\-key \-L -Unaccepted Keys: -alpha -bravo -charlie -delta -Accepted Keys: -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This example shows that the Salt Master is aware of four Minions, but none of -the keys has been accepted. To accept the keys and allow the Minions to be -controlled by the Master, again use the \fBsalt\-key\fP command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root@master ~]# salt\-key \-A -[root@master ~]# salt\-key \-L -Unaccepted Keys: -Accepted Keys: -alpha -bravo -charlie -delta -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The -example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys -individually use the lowercase of the same option, \fB\-a keyname\fP\&. -.sp -\fBSEE ALSO:\fP -.INDENT 0.0 -.INDENT 3.5 -\fI\%salt\-key manpage\fP -.UNINDENT -.UNINDENT -.SS Sending Commands -.sp -Communication between the Master and a Minion may be verified by running -the \fBtest.version\fP command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root@master ~]# salt alpha test.version -alpha: - 2018.3.4 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Communication between the Master and all Minions may be tested in a -similar way: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[root@master ~]# salt \(aq*\(aq test.version -alpha: - 2018.3.4 -bravo: - 2018.3.4 -charlie: - 2018.3.4 -delta: - 2018.3.4 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Each of the Minions should send a \fB2018.3.4\fP response as shown above, -or any other salt version installed. -.SS What\(aqs Next? -.sp -Understanding \fI\%targeting\fP is important. From there, depending -on the way you wish to use Salt, you should also proceed to learn about -\fI\%Remote Execution\fP and \fI\%Configuration Management\fP\&. .SS engine modules .TS center; @@ -108014,7 +103622,6 @@ _ T{ \fI\%docker_events\fP T} T{ -Send events from Docker events :Depends: Docker API >= 1.22 T} _ T{ @@ -108128,6 +103735,14 @@ _ .TE .SS salt.engines.docker_events .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Send events from Docker events :Depends: Docker API >= 1.22 .INDENT 0.0 @@ -111080,30 +106695,6 @@ Support for the Amazon Simple Queue Service. T} _ T{ -\fI\%azurearm_compute\fP -T} T{ -Azure (ARM) Compute Execution Module -T} -_ -T{ -\fI\%azurearm_dns\fP -T} T{ -Azure (ARM) DNS Execution Module -T} -_ -T{ -\fI\%azurearm_network\fP -T} T{ -Azure (ARM) Network Execution Module -T} -_ -T{ -\fI\%azurearm_resource\fP -T} T{ -Azure (ARM) Resource Execution Module -T} -_ -T{ \fI\%bamboohr\fP T} T{ Support for BambooHR @@ -111386,11 +106977,6 @@ Cassandra Database Module T} _ T{ -\fI\%cassandra_mod\fP -T} T{ -T} -_ -T{ \fI\%celery\fP T} T{ Support for scheduling celery tasks. @@ -111561,7 +107147,6 @@ _ T{ \fI\%deb_apache\fP T} T{ -Support for Apache T} _ T{ @@ -111645,13 +107230,11 @@ _ T{ \fI\%dockercompose\fP T} T{ -Module to import docker\-compose via saltstack T} _ T{ \fI\%dockermod\fP T} T{ -Management of Docker Containers T} _ T{ @@ -111903,7 +107486,7 @@ _ T{ \fI\%gpg\fP T} T{ -Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. +Manage GPG keychains, add keys, create keys, retrieve keys from keyservers. T} _ T{ @@ -112170,7 +107753,6 @@ _ T{ \fI\%k8s\fP T} T{ -Salt module to manage Kubernetes cluster T} _ T{ @@ -112236,13 +107818,11 @@ _ T{ \fI\%kubeadm\fP T} T{ -Module for kubeadm :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new :depends: None :platform: Linux T} _ T{ \fI\%kubernetesmod\fP T} T{ -Module for handling kubernetes calls. T} _ T{ @@ -113118,7 +108698,6 @@ _ T{ \fI\%pushover_notify\fP T} T{ -Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) T} _ T{ @@ -113580,7 +109159,6 @@ _ T{ \fI\%suse_apache\fP T} T{ -Support for Apache T} _ T{ @@ -113790,7 +109368,6 @@ _ T{ \fI\%vault\fP T} T{ -Functions to interact with Hashicorp Vault. T} _ T{ @@ -113848,6 +109425,12 @@ Support for htpasswd command. T} _ T{ +\fI\%win_appx\fP +T} T{ +Manage provisioned apps +T} +_ +T{ \fI\%win_auditpol\fP T} T{ A salt module for modifying the audit policies on the machine @@ -114138,7 +109721,6 @@ _ T{ \fI\%zabbix\fP T} T{ -Support for Zabbix T} _ T{ @@ -114257,7 +109839,7 @@ Make sure the appropriate certbot plugin for the wanted DNS provider is installed before using this module. .INDENT 0.0 .TP -.B salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None) +.B salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None, manual_auth_hook=None, manual_cleanup_hook=None) Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt. .INDENT 7.0 .TP @@ -114315,6 +109897,10 @@ the specified DNS plugin .IP \(bu 2 \fBdns_plugin_propagate_seconds\fP \-\- Number of seconds to wait for DNS propogations before asking ACME servers to verify the DNS record. (default 10) +.IP \(bu 2 +\fBmanual_auth_hook\fP \-\- Path to the manual authentication hook script. +.IP \(bu 2 +\fBmanual_cleanup_hook\fP \-\- Path to the manual cleanup or post\-authentication hook script. .UNINDENT .TP .B Return type @@ -116867,6 +112453,9 @@ salt \(aq*\(aq pkg.autoremove purge=True This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 +Changed in version 3007.0. + +.sp Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned. @@ -117378,6 +112967,9 @@ Returns a dict containing the new package names and versions: .INDENT 0.0 .TP .B salt.modules.aptpkg.latest_version(*names, **kwargs) +Changed in version 3007.0. + +.sp Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned. @@ -119966,6 +115558,13 @@ Artifactory username. Optional parameter. Artifactory password. Optional parameter. .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.artifactory.set_basic_auth(url, username, password) +Sets the username and password for a specific url. Helper method. +.sp +CLI Example: +.UNINDENT .SS salt.modules.at .sp Wrapper module for at(1) @@ -120722,3957 +116321,6 @@ salt \(aq*\(aq aws_sqs.receive_message num=10 .sp New in version 2014.7.0. -.UNINDENT -.SS salt.modules.azurearm_compute -.sp -Azure (ARM) Compute Execution Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as keyword arguments -to every function in order to work properly. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.UNINDENT -.INDENT 0.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. -.INDENT 7.0 -.TP -.B Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.availability_set_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update an availability set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The availability set to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -availability set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.availability_set_create_or_update testset testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.availability_set_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete an availability set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The availability set to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -availability set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.availability_set_delete testset testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.availability_set_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get a dictionary representing an availability set\(aqs properties. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The availability set to get. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -availability set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.availability_set_get testset testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.availability_sets_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all availability sets within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list availability -sets within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.availability_sets_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.availability_sets_list_available_sizes(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all available virtual machine sizes that can be used to -to create a new virtual machine in an existing availability set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The availability set name to list available -virtual machine sizes within. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name to list available -availability set sizes within. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.availability_sets_list_available_sizes testset testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_capture(name, destination_name, resource_group, prefix=\(aqcapture\-\(aq, overwrite=False, **kwargs) -New in version 2019.2.0. - -.sp -Captures the VM by copying virtual hard disks of the VM and outputs -a template that can be used to create similar VMs. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine. -.IP \(bu 2 -\fBdestination_name\fP \-\- The destination container name. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.IP \(bu 2 -\fBprefix\fP \-\- (Default: \(aqcapture\-\(aq) The captured virtual hard disk\(aqs name prefix. -.IP \(bu 2 -\fBoverwrite\fP \-\- (Default: False) Overwrite the destination disk in case of conflict. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_capture testvm testcontainer testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_convert_to_managed_disks(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Converts virtual machine disks from blob\-based to managed disks. Virtual -machine must be stop\-deallocated before invoking this operation. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to convert. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_convert_to_managed_disks testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_deallocate(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Power off a virtual machine and deallocate compute resources. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to deallocate. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_deallocate testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_generalize(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Set the state of a virtual machine to \(aqgeneralized\(aq. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_generalize testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Retrieves information about the model view or the instance view of a -virtual machine. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_get testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_power_off(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Power off (stop) a virtual machine. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to stop. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_power_off testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_redeploy(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Redeploy a virtual machine. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to redeploy. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_redeploy testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_restart(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Restart a virtual machine. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to restart. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_restart testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machine_start(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Power on (start) a virtual machine. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine to start. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machine_start testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machines_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all virtual machines within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list virtual -machines within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machines_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machines_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all virtual machines within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machines_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_compute.virtual_machines_list_available_sizes(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Lists all available virtual machine sizes to which the specified virtual -machine can be resized. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual machine. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual machine. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_compute.virtual_machines_list_available_sizes testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.modules.azurearm_dns -.sp -Azure (ARM) DNS Execution Module -.sp -New in version 3000. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-dns\fP >= 2.0.0rc1 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as keyword arguments -to every function in order to work properly. -.UNINDENT -.sp -Required provider parameters: -.INDENT 0.0 -.INDENT 3.5 -if using username and password: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.UNINDENT -.UNINDENT -.sp -if using a service principal: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 0.0 -.INDENT 3.5 -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. -.sp -Possible values: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.record_set_create_or_update(name, zone_name, resource_group, record_type, **kwargs) -New in version 3000. - -.sp -Creates or updates a record set within a DNS zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the record set, relative to the name of the zone. -.IP \(bu 2 -\fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBrecord_type\fP \-\- The type of DNS record in this record set. Record sets of type SOA can be -updated but not created (they are created when the DNS zone is created). -Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.record_set_create_or_update myhost myzone testgroup A - arecords=\(aq[{ipv4_address: 10.0.0.1}]\(aq ttl=300 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.record_set_delete(name, zone_name, resource_group, record_type, **kwargs) -New in version 3000. - -.sp -Deletes a record set from a DNS zone. This operation cannot be undone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the record set, relative to the name of the zone. -.IP \(bu 2 -\fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBrecord_type\fP \-\- The type of DNS record in this record set. Record sets of type SOA cannot be -deleted (they are deleted when the DNS zone is deleted). -Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.record_set_delete myhost myzone testgroup A -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.record_set_get(name, zone_name, resource_group, record_type, **kwargs) -New in version 3000. - -.sp -Get a dictionary representing a record set\(aqs properties. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the record set, relative to the name of the zone. -.IP \(bu 2 -\fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBrecord_type\fP \-\- The type of DNS record in this record set. -Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.record_set_get \(aq@\(aq myzone testgroup SOA -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.record_sets_list_by_dns_zone(zone_name, resource_group, top=None, recordsetnamesuffix=None, **kwargs) -New in version 3000. - -.sp -Lists all record sets in a DNS zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBtop\fP \-\- The maximum number of record sets to return. If not specified, -returns up to 100 record sets. -.IP \(bu 2 -\fBrecordsetnamesuffix\fP \-\- The suffix label of the record set name that has -to be used to filter the record set enumerations. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.record_sets_list_by_dns_zone myzone testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.record_sets_list_by_type(zone_name, resource_group, record_type, top=None, recordsetnamesuffix=None, **kwargs) -New in version 3000. - -.sp -Lists the record sets of a specified type in a DNS zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBrecord_type\fP \-\- The type of record sets to enumerate. -Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq -.IP \(bu 2 -\fBtop\fP \-\- The maximum number of record sets to return. If not specified, -returns up to 100 record sets. -.IP \(bu 2 -\fBrecordsetnamesuffix\fP \-\- The suffix label of the record set name that has -to be used to filter the record set enumerations. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.record_sets_list_by_type myzone testgroup SOA -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.zone_create_or_update(name, resource_group, **kwargs) -New in version 3000. - -.sp -Creates or updates a DNS zone. Does not modify DNS records within the zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the DNS zone to create (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.zone_create_or_update myzone testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.zone_delete(name, resource_group, **kwargs) -New in version 3000. - -.sp -Delete a DNS zone within a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the DNS zone to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.zone_delete myzone testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.zone_get(name, resource_group, **kwargs) -New in version 3000. - -.sp -Get a dictionary representing a DNS zone\(aqs properties, but not the -record sets within the zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The DNS zone to get. -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.zone_get myzone testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.zones_list(top=None, **kwargs) -New in version 3000. - -.sp -Lists the DNS zones in all resource groups in a subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBtop\fP \-\- The maximum number of DNS zones to return. If not specified, -eturns up to 100 zones. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.zones_list -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_dns.zones_list_by_resource_group(resource_group, top=None, **kwargs) -New in version 3000. - -.sp -Lists the DNS zones in a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBresource_group\fP \-\- The name of the resource group. -.IP \(bu 2 -\fBtop\fP \-\- The maximum number of DNS zones to return. If not specified, -returns up to 100 zones. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_dns.zones_list_by_resource_group testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.modules.azurearm_network -.sp -Azure (ARM) Network Execution Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as keyword arguments -to every function in order to work properly. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.UNINDENT -.INDENT 0.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. -.INDENT 7.0 -.TP -.B Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.check_dns_name_availability(name, region, **kwargs) -New in version 2019.2.0. - -.sp -Check whether a domain name in the current zone is available for use. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The DNS name to query. -.IP \(bu 2 -\fBregion\fP \-\- The region to query for the DNS name in question. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.check_dns_name_availability testdnsname westus -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.check_ip_address_availability(ip_address, virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Check that a private ip address is available within the specified -virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBip_address\fP \-\- The ip_address to query. -.IP \(bu 2 -\fBvirtual_network\fP \-\- The virtual network to query for the IP address -in question. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.check_ip_address_availability 10.0.0.4 testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.default_security_rule_get(name, security_group, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a default security rule within a security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the security rule to query. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group containing the -security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.default_security_rule_get DenyAllOutBound testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.default_security_rules_list(security_group, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List default security rules within a security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.default_security_rules_list testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.get_virtual_machine_scale_set_network_interface(name, scale_set, vm_index, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get information about a specific network interface within a scale set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to query. -.IP \(bu 2 -\fBscale_set\fP \-\- The name of the scale set containing the interface. -.IP \(bu 2 -\fBvm_index\fP \-\- The virtual machine index. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -scale set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.get_virtual_machine_scale_set_network_interface test\-iface0 testset testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.list_virtual_machine_scale_set_network_interfaces(scale_set, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get information about all network interfaces within a scale set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBscale_set\fP \-\- The name of the scale set to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -scale set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces testset testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces(scale_set, vm_index, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get information about all network interfaces in a specific virtual machine within a scale set. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBscale_set\fP \-\- The name of the scale set to query. -.IP \(bu 2 -\fBvm_index\fP \-\- The virtual machine index. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -scale set. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces testset testvm testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.load_balancer_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a load balancer within a specified resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the load balancer to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -load balancer. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.load_balancer_create_or_update testlb testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.load_balancer_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a load balancer. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the load balancer to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -load balancer. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.load_balancer_delete testlb testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.load_balancer_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific load balancer. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the load balancer to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -load balancer. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.load_balancer_get testlb testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.load_balancers_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all load balancers within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list load balancers -within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.load_balancers_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.load_balancers_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all load balancers within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.load_balancers_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interface_create_or_update(name, ip_configurations, subnet, virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a network interface within a specified resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to create. -.IP \(bu 2 -\fBip_configurations\fP \-\- A list of dictionaries representing valid -NetworkInterfaceIPConfiguration objects. The \(aqname\(aq key is required at -minimum. At least one IP Configuration must be present. -.IP \(bu 2 -\fBsubnet\fP \-\- The name of the subnet assigned to the network interface. -.IP \(bu 2 -\fBvirtual_network\fP \-\- The name of the virtual network assigned to the subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interface_create_or_update test\-iface0 [{\(aqname\(aq: \(aqtestipconfig1\(aq}] testsubnet testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interface_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a network interface. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network interface. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interface_delete test\-iface0 testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interface_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific network interface. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network interface. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interface_get test\-iface0 testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interface_get_effective_route_table(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get all route tables for a specific network interface. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network interface. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interface_get_effective_route_table test\-iface0 testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interface_list_effective_network_security_groups(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get all network security groups applied to a specific network interface. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network interface to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network interface. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interface_list_effective_network_security_groups test\-iface0 testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interfaces_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all network interfaces within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list network -interfaces within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interfaces_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_interfaces_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all network interfaces within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_interfaces_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_security_group_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a network security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network security group to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_security_group_create_or_update testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_security_group_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a network security group within a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network security group to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_security_group_delete testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_security_group_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a network security group within a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the network security group to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_security_group_get testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_security_groups_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all network security groups within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list network security groups within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_security_groups_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.network_security_groups_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all network security groups within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.network_security_groups_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.public_ip_address_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a public IP address within a specified resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the public IP address to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -public IP address. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.public_ip_address_create_or_update test\-ip\-0 testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.public_ip_address_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a public IP address. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the public IP address to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -public IP address. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.public_ip_address_delete test\-pub\-ip testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.public_ip_address_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific public IP address. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the public IP address to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -public IP address. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.public_ip_address_get test\-pub\-ip testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.public_ip_addresses_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all public IP addresses within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list public IP -addresses within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.public_ip_addresses_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.public_ip_addresses_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all public IP addresses within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.public_ip_addresses_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_create_or_update(name, address_prefix, next_hop_type, route_table, resource_group, next_hop_ip_address=None, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a route within a specified route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route to create. -.IP \(bu 2 -\fBaddress_prefix\fP \-\- The destination CIDR to which the route applies. -.IP \(bu 2 -\fBnext_hop_type\fP \-\- The type of Azure hop the packet should be sent to. Possible values are: -\(aqVirtualNetworkGateway\(aq, \(aqVnetLocal\(aq, \(aqInternet\(aq, \(aqVirtualAppliance\(aq, and \(aqNone\(aq. -.IP \(bu 2 -\fBnext_hop_ip_address\fP \-\- Optional IP address to which packets should be forwarded. Next hop -values are only allowed in routes where the next_hop_type is \(aqVirtualAppliance\(aq. -.IP \(bu 2 -\fBroute_table\fP \-\- The name of the route table containing the route. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_create_or_update test\-rt \(aq10.0.0.0/8\(aq test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_delete(name, route_table, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a route from a route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The route to delete. -.IP \(bu 2 -\fBroute_table\fP \-\- The route table containing the route. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_delete test\-rt test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a route filter within a specified resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route filter to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_create_or_update test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a route filter. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route filter to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_delete test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific route filter. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route table to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_get test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_rule_create_or_update(name, access, communities, route_filter, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a rule within a specified route filter. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the rule to create. -.IP \(bu 2 -\fBaccess\fP \-\- The access type of the rule. Valid values are \(aqAllow\(aq and \(aqDeny\(aq. -.IP \(bu 2 -\fBcommunities\fP \-\- A list of BGP communities to filter on. -.IP \(bu 2 -\fBroute_filter\fP \-\- The name of the route filter containing the rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_rule_create_or_update test\-rule allow \(dq[\(aq12076:51006\(aq]\(dq test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_rule_delete(name, route_filter, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a route filter rule. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The route filter rule to delete. -.IP \(bu 2 -\fBroute_filter\fP \-\- The route filter containing the rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_rule_delete test\-rule test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_rule_get(name, route_filter, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific route filter rule. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The route filter rule to query. -.IP \(bu 2 -\fBroute_filter\fP \-\- The route filter containing the rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_rule_get test\-rule test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filter_rules_list(route_filter, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all routes within a route filter. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBroute_filter\fP \-\- The route filter to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route filter. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filter_rules_list test\-filter testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filters_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all route filters within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list route -filters within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filters_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_filters_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all route filters within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_filters_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_get(name, route_table, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific route. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The route to query. -.IP \(bu 2 -\fBroute_table\fP \-\- The route table containing the route. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_get test\-rt test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_table_create_or_update(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a route table within a specified resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route table to create. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_table_create_or_update test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_table_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route table to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_table_delete test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_table_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the route table to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_table_get test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_tables_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all route tables within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list route -tables within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_tables_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.route_tables_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all route tables within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.route_tables_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.routes_list(route_table, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all routes within a route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBroute_table\fP \-\- The route table to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -route table. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.routes_list test\-rt\-table testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.security_rule_create_or_update(name, access, direction, priority, protocol, security_group, resource_group, source_address_prefix=None, destination_address_prefix=None, source_port_range=None, destination_port_range=None, source_address_prefixes=None, destination_address_prefixes=None, source_port_ranges=None, destination_port_ranges=None, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a security rule within a specified network security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the security rule to create. -.IP \(bu 2 -\fBaccess\fP \-\- \(aqallow\(aq or \(aqdeny\(aq -.IP \(bu 2 -\fBdirection\fP \-\- \(aqinbound\(aq or \(aqoutbound\(aq -.IP \(bu 2 -\fBpriority\fP \-\- Integer between 100 and 4096 used for ordering rule application. -.IP \(bu 2 -\fBprotocol\fP \-\- \(aqtcp\(aq, \(aqudp\(aq, or \(aq*\(aq -.IP \(bu 2 -\fBdestination_address_prefix\fP \-\- The CIDR or destination IP range. Asterix \(aq*\(aq can also be used to match all destination IPs. -Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. -If this is an ingress rule, specifies where network traffic originates from. -.IP \(bu 2 -\fBdestination_port_range\fP \-\- The destination port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq -can also be used to match all ports. -.IP \(bu 2 -\fBsource_address_prefix\fP \-\- The CIDR or source IP range. Asterix \(aq*\(aq can also be used to match all source IPs. -Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. -If this is an ingress rule, specifies where network traffic originates from. -.IP \(bu 2 -\fBsource_port_range\fP \-\- The source port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq -can also be used to match all ports. -.IP \(bu 2 -\fBdestination_address_prefixes\fP \-\- A list of destination_address_prefix values. This parameter overrides destination_address_prefix -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBdestination_port_ranges\fP \-\- A list of destination_port_range values. This parameter overrides destination_port_range -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBsource_address_prefixes\fP \-\- A list of source_address_prefix values. This parameter overrides source_address_prefix -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBsource_port_ranges\fP \-\- A list of source_port_range values. This parameter overrides source_port_range -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group containing the -security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.security_rule_create_or_update testrule1 allow outbound 101 tcp testnsg testgroup source_address_prefix=\(aq*\(aq destination_address_prefix=internet source_port_range=\(aq*\(aq destination_port_range=\(aq1\-1024\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.security_rule_delete(security_rule, security_group, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a security rule within a specified security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the security rule to delete. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group containing the -security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.security_rule_delete testrule1 testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.security_rule_get(security_rule, security_group, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get a security rule within a specified network security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the security rule to query. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group containing the -security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.security_rule_get testrule1 testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.security_rules_list(security_group, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List security rules within a network security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -network security group. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.security_rules_list testnsg testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.subnet_create_or_update(name, address_prefix, virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a subnet. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name assigned to the subnet being created or updated. -.IP \(bu 2 -\fBaddress_prefix\fP \-\- A valid CIDR block within the virtual network. -.IP \(bu 2 -\fBvirtual_network\fP \-\- The virtual network name containing the -subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.subnet_create_or_update testsubnet \(aq10.0.0.0/24\(aq testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.subnet_delete(name, virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a subnet. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the subnet to delete. -.IP \(bu 2 -\fBvirtual_network\fP \-\- The virtual network name containing the -subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.subnet_delete testsubnet testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.subnet_get(name, virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific subnet. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the subnet to query. -.IP \(bu 2 -\fBvirtual_network\fP \-\- The virtual network name containing the -subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.subnet_get testsubnet testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.subnets_list(virtual_network, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all subnets within a virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBvirtual_network\fP \-\- The virtual network name to list subnets within. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.subnets_list testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.usages_list(location, **kwargs) -New in version 2019.2.0. - -.sp -List subscription network usage for a location. -.INDENT 7.0 -.TP -.B Parameters -\fBlocation\fP \-\- The Azure location to query for network usage. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.usages_list westus -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.virtual_network_create_or_update(name, address_prefixes, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name assigned to the virtual network being -created or updated. -.IP \(bu 2 -\fBaddress_prefixes\fP \-\- A list of CIDR blocks which can be used -by subnets within the virtual network. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.virtual_network_create_or_update testnet [\(aq10.0.0.0/16\(aq] testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.virtual_network_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual network to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.virtual_network_delete testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.virtual_network_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the virtual network to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -virtual network. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.virtual_network_get testnet testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.virtual_networks_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all virtual networks within a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list virtual networks -within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.virtual_networks_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_network.virtual_networks_list_all(**kwargs) -New in version 2019.2.0. - -.sp -List all virtual networks within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_network.virtual_networks_list_all -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.modules.azurearm_resource -.sp -Azure (ARM) Resource Execution Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as keyword arguments -to every function in order to work properly. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.UNINDENT -.INDENT 0.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. -.INDENT 7.0 -.TP -.B Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_cancel(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Cancel a deployment if in \(aqAccepted\(aq or \(aqRunning\(aq state. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to cancel. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_cancel testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_check_existence(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Check the existence of a deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_check_existence testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_create_or_update(name, resource_group, deploy_mode=\(aqincremental\(aq, debug_setting=\(aqnone\(aq, deploy_params=None, parameters_link=None, deploy_template=None, template_link=None, **kwargs) -New in version 2019.2.0. - -.sp -Deploys resources to a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to create or update. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.IP \(bu 2 -\fBdeploy_mode\fP \-\- The mode that is used to deploy resources. This value can be either -\(aqincremental\(aq or \(aqcomplete\(aq. In Incremental mode, resources are deployed without deleting -existing resources that are not included in the template. In Complete mode, resources -are deployed and existing resources in the resource group that are not included in -the template are deleted. Be careful when using Complete mode as you may -unintentionally delete resources. -.IP \(bu 2 -\fBdebug_setting\fP \-\- The debug setting of the deployment. The permitted values are \(aqnone\(aq, -\(aqrequestContent\(aq, \(aqresponseContent\(aq, or \(aqrequestContent,responseContent\(aq. By logging -information about the request or response, you could potentially expose sensitive data -that is retrieved through the deployment operations. -.IP \(bu 2 -\fBdeploy_params\fP \-\- JSON string containing name and value pairs that define the deployment -parameters for the template. You use this element when you want to provide the parameter -values directly in the request rather than link to an existing parameter file. Use either -the parameters_link property or the deploy_params property, but not both. -.IP \(bu 2 -\fBparameters_link\fP \-\- The URI of a parameters file. You use this element to link to an existing -parameters file. Use either the parameters_link property or the deploy_params property, but not both. -.IP \(bu 2 -\fBdeploy_template\fP \-\- JSON string of template content. You use this element when you want to pass -the template syntax directly in the request rather than link to an existing template. Use either -the template_link property or the deploy_template property, but not both. -.IP \(bu 2 -\fBtemplate_link\fP \-\- The URI of the template. Use either the template_link property or the -deploy_template property, but not both. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_create_or_update testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_delete(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Delete a deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to delete. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_delete testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_export_template(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Exports the template used for the specified deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_export_template testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_get(name, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_get testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_operation_get(operation, deployment, resource_group, **kwargs) -New in version 2019.2.0. - -.sp -Get a deployment operation within a deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBoperation\fP \-\- The operation ID of the operation within the deployment. -.IP \(bu 2 -\fBdeployment\fP \-\- The name of the deployment containing the operation. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_operation_get XXXXX testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_operations_list(name, resource_group, result_limit=10, **kwargs) -New in version 2019.2.0. - -.sp -List all deployment operations within a deployment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to query. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.IP \(bu 2 -\fBresult_limit\fP \-\- (Default: 10) The limit on the list of deployment -operations. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_operations_list testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployment_validate(name, resource_group, deploy_mode=None, debug_setting=None, deploy_params=None, parameters_link=None, deploy_template=None, template_link=None, **kwargs) -New in version 2019.2.0. - -.sp -Validates whether the specified template is syntactically correct -and will be accepted by Azure Resource Manager. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the deployment to validate. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group name assigned to the -deployment. -.IP \(bu 2 -\fBdeploy_mode\fP \-\- The mode that is used to deploy resources. This value can be either -\(aqincremental\(aq or \(aqcomplete\(aq. In Incremental mode, resources are deployed without deleting -existing resources that are not included in the template. In Complete mode, resources -are deployed and existing resources in the resource group that are not included in -the template are deleted. Be careful when using Complete mode as you may -unintentionally delete resources. -.IP \(bu 2 -\fBdebug_setting\fP \-\- The debug setting of the deployment. The permitted values are \(aqnone\(aq, -\(aqrequestContent\(aq, \(aqresponseContent\(aq, or \(aqrequestContent,responseContent\(aq. By logging -information about the request or response, you could potentially expose sensitive data -that is retrieved through the deployment operations. -.IP \(bu 2 -\fBdeploy_params\fP \-\- JSON string containing name and value pairs that define the deployment -parameters for the template. You use this element when you want to provide the parameter -values directly in the request rather than link to an existing parameter file. Use either -the parameters_link property or the deploy_params property, but not both. -.IP \(bu 2 -\fBparameters_link\fP \-\- The URI of a parameters file. You use this element to link to an existing -parameters file. Use either the parameters_link property or the deploy_params property, but not both. -.IP \(bu 2 -\fBdeploy_template\fP \-\- JSON string of template content. You use this element when you want to pass -the template syntax directly in the request rather than link to an existing template. Use either -the template_link property or the deploy_template property, but not both. -.IP \(bu 2 -\fBtemplate_link\fP \-\- The URI of the template. Use either the template_link property or the -deploy_template property, but not both. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployment_validate testdeploy testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.deployments_list(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all deployments within a resource group. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.deployments_list testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_assignment_create(name, scope, definition_name, **kwargs) -New in version 2019.2.0. - -.sp -Create a policy assignment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the policy assignment to create. -.IP \(bu 2 -\fBscope\fP \-\- The scope of the policy assignment. -.IP \(bu 2 -\fBdefinition_name\fP \-\- The name of the policy definition to assign. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_assignment_create testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 testpolicy -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_assignment_delete(name, scope, **kwargs) -New in version 2019.2.0. - -.sp -Delete a policy assignment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the policy assignment to delete. -.IP \(bu 2 -\fBscope\fP \-\- The scope of the policy assignment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_assignment_delete testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_assignment_get(name, scope, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific policy assignment. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the policy assignment to query. -.IP \(bu 2 -\fBscope\fP \-\- The scope of the policy assignment. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_assignment_get testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_assignments_list(**kwargs) -New in version 2019.2.0. - -.sp -List all policy assignments for a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_assignments_list -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_assignments_list_for_resource_group(resource_group, **kwargs) -New in version 2019.2.0. - -.sp -List all policy assignments for a resource group. -.INDENT 7.0 -.TP -.B Parameters -\fBresource_group\fP \-\- The resource group name to list policy assignments within. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_assignments_list_for_resource_group testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_definition_create_or_update(name, policy_rule, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a policy definition. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the policy definition to create or update. -.IP \(bu 2 -\fBpolicy_rule\fP \-\- A dictionary defining the -\fI\%policy rule\fP\&. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_definition_create_or_update testpolicy \(aq{...rule definition..}\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_definition_delete(name, **kwargs) -New in version 2019.2.0. - -.sp -Delete a policy definition. -.INDENT 7.0 -.TP -.B Parameters -\fBname\fP \-\- The name of the policy definition to delete. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_definition_delete testpolicy -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_definition_get(name, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a specific policy definition. -.INDENT 7.0 -.TP -.B Parameters -\fBname\fP \-\- The name of the policy definition to query. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_definition_get testpolicy -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.policy_definitions_list(hide_builtin=False, **kwargs) -New in version 2019.2.0. - -.sp -List all policy definitions for a subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBhide_builtin\fP \-\- Boolean which will filter out BuiltIn policy definitions from the result. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.policy_definitions_list -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.resource_group_check_existence(name, **kwargs) -New in version 2019.2.0. - -.sp -Check for the existence of a named resource group in the current subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBname\fP \-\- The resource group name to check. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.resource_group_check_existence testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.resource_group_create_or_update(name, location, **kwargs) -New in version 2019.2.0. - -.sp -Create or update a resource group in a given location. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the resource group to create or update. -.IP \(bu 2 -\fBlocation\fP \-\- The location of the resource group. This value -is not able to be updated once the resource group is created. -.UNINDENT -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.resource_group_create_or_update testgroup westus -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.resource_group_delete(name, **kwargs) -New in version 2019.2.0. - -.sp -Delete a resource group from the subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBname\fP \-\- The resource group name to delete. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.resource_group_delete testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.resource_group_get(name, **kwargs) -New in version 2019.2.0. - -.sp -Get a dictionary representing a resource group\(aqs properties. -.INDENT 7.0 -.TP -.B Parameters -\fBname\fP \-\- The resource group name to get. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.resource_group_get testgroup -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.resource_groups_list(**kwargs) -New in version 2019.2.0. - -.sp -List all resource groups within a subscription. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.resource_groups_list -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.subscription_get(subscription_id=None, **kwargs) -New in version 2019.2.0. - -.sp -Get details about a subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBsubscription_id\fP \-\- The ID of the subscription to query. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.subscription_get XXXXXXXX -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.subscriptions_list(**kwargs) -New in version 2019.2.0. - -.sp -List all subscriptions for a tenant. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.subscriptions_list -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.subscriptions_list_locations(subscription_id=None, **kwargs) -New in version 2019.2.0. - -.sp -List all locations for a subscription. -.INDENT 7.0 -.TP -.B Parameters -\fBsubscription_id\fP \-\- The ID of the subscription to query. -.UNINDENT -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.subscriptions_list_locations XXXXXXXX -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.azurearm_resource.tenants_list(**kwargs) -New in version 2019.2.0. - -.sp -List all tenants for your account. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call azurearm_resource.tenants_list -.ft P -.fi -.UNINDENT -.UNINDENT .UNINDENT .SS salt.modules.bamboohr .sp @@ -147448,197 +139096,6 @@ salt \(aqminion1\(aq cassandra_cql.version contact_points=minion1 .UNINDENT .UNINDENT .UNINDENT -.SS salt.modules.cassandra_mod -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fIcassandra\fP module is deprecated in favor of the \fIcassandra_cql\fP -module. -.UNINDENT -.UNINDENT -.sp -Cassandra NoSQL Database Module -.INDENT 0.0 -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -pycassa Cassandra Python adapter -.UNINDENT -.TP -.B configuration -The location of the \(aqnodetool\(aq command, host, and thrift port needs to be -specified via pillar: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -cassandra.nodetool: /usr/local/bin/nodetool -cassandra.host: localhost -cassandra.thrift_port: 9160 -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.column_families(keyspace=None) -Return existing column families for all keyspaces -or just the provided one. -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.column_families -salt \(aq*\(aq cassandra.column_families -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.column_family_definition(keyspace, column_family) -Return a dictionary of column family definitions for the given -keyspace/column_family -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.column_family_definition -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.compactionstats() -Return compactionstats info -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.compactionstats -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.info() -Return cassandra node info -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.info -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.keyspaces() -Return existing keyspaces -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.keyspaces -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.netstats() -Return netstats info -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.netstats -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.ring() -Return cassandra ring info -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.ring -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.tpstats() -Return tpstats info -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.tpstats -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.cassandra_mod.version() -Return the cassandra version -.sp -CLI Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt \(aq*\(aq cassandra.version -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.modules.celery .sp Support for scheduling celery tasks. The worker is independent of salt and thus can run in a different @@ -157921,6 +149378,87 @@ depending on the shell being used to run the command. .UNINDENT .INDENT 0.0 .TP +.B salt.modules.cp.cache_file_ssh(path, saltenv=None, source_hash=None, verify_ssl=True, use_etag=False) +This function is an alias of \fBcache_file\fP\&. +.INDENT 7.0 +.INDENT 3.5 +Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set + +.sp +Used to cache a single file on the Minion +.sp +Returns the location of the new cached file on the Minion +.INDENT 0.0 +.TP +.B source_hash +If \fBname\fP is an http(s) or ftp URL and the file exists in the +minion\(aqs file cache, this option can be passed to keep the minion from +re\-downloading the file if the cached copy matches the specified hash. +.sp +New in version 2018.3.0. + +.TP +.B verify_ssl +If \fBFalse\fP, remote https file sources (\fBhttps://\fP) and source_hash +will not attempt to validate the servers certificate. Default is True. +.sp +New in version 3002. + +.TP +.B use_etag +If \fBTrue\fP, remote http/https file sources will attempt to use the +ETag header to determine if the remote file needs to be downloaded. +This provides a lightweight mechanism for promptly refreshing files +changed on a web server without requiring a full hash comparison via +the \fBsource_hash\fP parameter. +.sp +New in version 3005. + +.UNINDENT +.sp +CLI Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq cp.cache_file salt://path/to/file +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +There are two ways of defining the fileserver environment (a.k.a. +\fBsaltenv\fP) from which to cache the file. One is to use the \fBsaltenv\fP +parameter, and the other is to use a querystring syntax in the \fBsalt://\fP +URL. The below two examples are equivalent: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq cp.cache_file salt://foo/bar.conf saltenv=config +salt \(aq*\(aq cp.cache_file salt://foo/bar.conf?saltenv=config +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If the path being cached is a \fBsalt://\fP URI, and the path does not exist, +then \fBFalse\fP will be returned. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It may be necessary to quote the URL when using the querystring method, +depending on the shell being used to run the command. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.cp.cache_files(paths, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set @@ -158262,6 +149800,33 @@ salt \(aq*\(aq cp.hash_file salt://path/to/file .UNINDENT .INDENT 0.0 .TP +.B salt.modules.cp.hash_file_ssh(path, saltenv=None) +This function is an alias of \fBhash_file\fP\&. +.INDENT 7.0 +.INDENT 3.5 +Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set + +.sp +Return the hash of a file, to get the hash of a file on the +salt master file server prepend the path with salt:// +otherwise, prepend the file with / for a local file. +.sp +CLI Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq cp.hash_file salt://path/to/file +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.cp.is_cached(path, saltenv=None) Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set @@ -158367,7 +149932,7 @@ salt \(aq*\(aq cp.list_minion Changed in version 3005: \fBsaltenv\fP will use value from config if not explicitly set .sp -List all of the available state modules in an environment +List all of the available state files in an environment .sp CLI Example: .INDENT 7.0 @@ -160186,6 +151751,14 @@ salt ns1 ddns.update example.com host1 60 A 10.0.0.1 .UNINDENT .SS salt.modules.deb_apache .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Support for Apache .sp Please note: The functions in here are Debian\-specific. Placing them in this @@ -161962,6 +153535,14 @@ salt \(aq*\(aq disk.blkid token=\(aqTYPE=ext4\(aq .TP .B salt.modules.disk.dump(device, args=None) Return all contents of dumpe2fs for a specified device +.INDENT 7.0 +.TP +.B device +The device path to dump. +.TP +.B args +A list of attributes to return. Returns all by default. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -162081,13 +153662,19 @@ salt \(aq*\(aq disk.get_fstype_from_path /root .UNINDENT .INDENT 0.0 .TP -.B salt.modules.disk.hdparms(disks, args=None) -Retrieve all info\(aqs for all disks -parse \(aqem into a nice dict -(which, considering hdparms output, is quite a hassle) +.B salt.modules.disk.hdparms(disks, args=\(aqaAbBcCdgHiJkMmNnQrRuW\(aq) +Retrieve disk parameters. .sp New in version 2016.3.0. +.INDENT 7.0 +.TP +.B disks +Single disk or list of disks to query. +.TP +.B args +Sequence of \fBhdparm\fP flags to fetch. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -162140,6 +153727,11 @@ salt \(aq*\(aq disk.hpa /dev/sda 10543256 .TP .B salt.modules.disk.inodeusage(args=None) Return inode usage information for volumes mounted on this minion +.INDENT 7.0 +.TP +.B args +Sequence of flags to pass to the \fBdf\fP command. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -162180,6 +153772,11 @@ salt \(aq*\(aq disk.iostat 1 5 disks=sda .TP .B salt.modules.disk.percent(args=None) Return partition information for volumes mounted on this minion +.INDENT 7.0 +.TP +.B args +Specify a single partition for which to return data. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -162264,6 +153861,11 @@ options. .TP .B salt.modules.disk.usage(args=None) Return usage information for volumes mounted on this minion +.INDENT 7.0 +.TP +.B args +Sequence of flags to pass to the \fBdf\fP command. +.UNINDENT .sp Changed in version 2019.2.0: Default for SunOS changed to 1 kilobyte blocks @@ -162821,6 +154423,14 @@ salt ns1 dnsutil.serial example.com .UNINDENT .SS salt.modules.dockercompose .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Module to import docker\-compose via saltstack .sp New in version 2016.3.0. @@ -163467,6 +155077,14 @@ salt myminion dockercompose.up /path/where/docker\-compose/stored \(aq[janus]\(a .UNINDENT .SS salt.modules.dockermod .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Docker Containers .sp New in version 2015.8.0. @@ -173724,8 +165342,16 @@ salt \(aq*\(aq extfs.dump /dev/sda1 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.extfs.mkfs(device, fs_type, **kwargs) +.B salt.modules.extfs.mkfs(device, fs_type, full_return=False, **kwargs) Create a file system on the specified device +.INDENT 7.0 +.TP +.B full_return +False +If \fBTrue\fP, the full \fBcmd.run_all\fP dictionary will be returned +instead of just stdout/stderr text. Useful for setting the result of +the \fBmodule.run\fP state. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -173792,6 +165418,12 @@ option twice (it is already set once); this is truly dangerous \fBusage_type\fP: how the filesystem is going to be used .IP \(bu 2 \fBuuid\fP: set the UUID for the file system +.IP \(bu 2 +\fBcluster_size\fP: specify the size of cluster in bytes for file systems using the bigalloc feature +.IP \(bu 2 +\fBroot_directory\fP: copy the contents of the given directory into the root directory of the file system +.IP \(bu 2 +\fBerrors_behavior\fP: change the behavior of the kernel code when errors are detected .UNINDENT .sp See the \fBmke2fs(8)\fP manpage for a more complete description of these @@ -173799,8 +165431,16 @@ options. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.extfs.tune(device, **kwargs) +.B salt.modules.extfs.tune(device, full_return=False, **kwargs) Set attributes for the specified device (using tune2fs) +.INDENT 7.0 +.TP +.B full_return +False +If \fBTrue\fP, the full \fBcmd.run_all\fP dictionary will be returned +instead of just stdout/stderr text. Useful for setting the result of +the \fBmodule.run\fP state. +.UNINDENT .sp CLI Example: .INDENT 7.0 @@ -173837,7 +165477,7 @@ Valid options are: .IP \(bu 2 \fBlabel\fP: label to apply to the file system .IP \(bu 2 -\fBreserved\fP: percentage of blocks reserved for super\-user +\fBreserved_percentage\fP: percentage of blocks reserved for super\-user .IP \(bu 2 \fBlast_dir\fP: last mounted directory .IP \(bu 2 @@ -175204,7 +166844,7 @@ salt \(aq*\(aq file.get_hash /etc/shadow .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.get_managed(name, template, source, source_hash, source_hash_name, user, group, mode, attrs, saltenv, context, defaults, skip_verify=False, verify_ssl=True, use_etag=False, **kwargs) +.B salt.modules.file.get_managed(name, template, source, source_hash, source_hash_name, user, group, mode, attrs, saltenv, context, defaults, skip_verify=False, verify_ssl=True, use_etag=False, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Return the managed file data for file.managed .INDENT 7.0 .TP @@ -175272,6 +166912,43 @@ the \fBsource_hash\fP parameter. .sp New in version 3005. +.TP +.B source_hash_sig +When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, +\fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a +valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying \fBsource_hash_sig\fP, require at least one valid signature +from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying \fBsource_hash_sig\fP, require a valid signature from each +of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying \fBsource_hash_sig\fP, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying \fBsource_hash_sig\fP, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -175333,7 +167010,7 @@ salt \(aq*\(aq file.get_selinux_context /etc/hosts .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.get_source_sum(file_name=\(aq\(aq, source=\(aq\(aq, source_hash=None, source_hash_name=None, saltenv=\(aqbase\(aq, verify_ssl=True) +.B salt.modules.file.get_source_sum(file_name=\(aq\(aq, source=\(aq\(aq, source_hash=None, source_hash_name=None, saltenv=\(aqbase\(aq, verify_ssl=True, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None) New in version 2016.11.0. .sp @@ -175373,6 +167050,42 @@ will not attempt to validate the servers certificate. Default is True. .sp New in version 3002. +.TP +.B source_hash_sig +When \fBsource\fP is a remote file source and \fBsource_hash\fP is a file, +ensure a valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying \fBsource_hash_sig\fP, require at least one valid signature +from one of a list of key fingerprints. This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying \fBsource_hash_sig\fP, require a valid signature from each +of the key fingerprints in this list. This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying \fBsource_hash_sig\fP, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying \fBsource_hash_sig\fP, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -176321,7 +168034,7 @@ salt \(aq*\(aq file.makedirs_perms /opt/code .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, attrs, saltenv, backup, makedirs=False, template=None, show_changes=True, contents=None, dir_mode=None, follow_symlinks=True, skip_verify=False, keep_mode=False, encoding=None, encoding_errors=\(aqstrict\(aq, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, use_etag=False, **kwargs) +.B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, attrs, saltenv, backup, makedirs=False, template=None, show_changes=True, contents=None, dir_mode=None, follow_symlinks=True, skip_verify=False, keep_mode=False, encoding=None, encoding_errors=\(aqstrict\(aq, seuser=None, serole=None, setype=None, serange=None, verify_ssl=True, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary). .INDENT 7.0 @@ -176463,6 +168176,80 @@ the \fBsource_hash\fP parameter. .sp New in version 3005. +.TP +.B signature +Ensure a valid GPG signature exists on the selected \fBsource\fP file. +Set this to true for inline signatures, or to a file URI retrievable +by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature is only enforced directly after caching the file, +before it is moved to its final destination. Existing target files +(with the correct checksum) will neither be checked nor deleted. +.sp +It will be enforced regardless of source type and will be +required on the final output, therefore this does not lend itself +well when templates are rendered. +The file will not be modified, meaning inline signatures are not +removed. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B source_hash_sig +When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, +\fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a +valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature on the \fBsource_hash\fP file is enforced regardless of +changes since its contents are used to check if an existing file +is in the correct state \- but only for remote sources! +As for \fBsignature\fP, existing target files will not be modified, +only the cached source_hash and source_hash_sig files will be removed. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying signatures either on the managed file or its source hash file, +require at least one valid signature from one of a list of key fingerprints. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying signatures either on the managed file or its source hash file, +require a valid signature from each of the key fingerprints in this list. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying signatures, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying signatures, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -177615,7 +169402,7 @@ salt \(aq*\(aq file.statvfs /path/to/file .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.symlink(src, path, force=False, atomic=False) +.B salt.modules.file.symlink(src, path, force=False, atomic=False, follow_symlinks=True) Create a symbolic link (symlink, soft link) to a file .INDENT 7.0 .TP @@ -177631,6 +169418,10 @@ Create a symbolic link (symlink, soft link) to a file .IP \(bu 2 \fBatomic\fP (\fI\%bool\fP) \-\- Use atomic file operations to create the symlink \&.. versionadded:: 3006.0 +.IP \(bu 2 +\fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If set to \fBFalse\fP, use \fBos.path.lexists()\fP for existence checks +instead of \fBos.path.exists()\fP\&. +\&.. versionadded:: 3007.0 .UNINDENT .TP .B Returns @@ -188418,8 +180209,8 @@ salt \(aq*\(aq google_chat.send_message \(dqhttps://chat.googleapis.com/v1/space .UNINDENT .SS salt.modules.gpg .sp -Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. -Sign, encrypt and sign plus encrypt text and files. +Manage GPG keychains, add keys, create keys, retrieve keys from keyservers. +Sign, encrypt, sign plus encrypt and verify text and files. .sp New in version 2015.5.0. @@ -188435,7 +180226,36 @@ libraries are not supported. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.create_key(key_type=\(aqRSA\(aq, key_length=1024, name_real=\(aqAutogenerated Key\(aq, name_comment=\(aqGenerated by SaltStack\(aq, name_email=None, subkey_type=None, subkey_length=None, expire_date=None, use_passphrase=False, user=None, gnupghome=None) +.B class salt.modules.gpg.FixedVerify(gpg) +This is a workaround for \fI\%https://github.com/vsajip/python\-gnupg/issues/214\fP\&. +It ensures invalid or otherwise unverified signatures are not +merged into sig_info in any way. +.sp +\fI\%https://github.com/vsajip/python\-gnupg/commit/ee94a7ecc1a86484c9f02337e2bbdd05fd32b383\fP +.INDENT 7.0 +.TP +.B handle_status(key, value) +Handle status messages from the \fIgpg\fP child process. These are lines of the format +.INDENT 7.0 +.INDENT 3.5 +[GNUPG:] +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBkey\fP (\fI\%str\fP) \-\- Identifies what the status message is. +.IP \(bu 2 +\fBvalue\fP (\fI\%str\fP) \-\- Identifies additional data, which differs depending on the key. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.gpg.create_key(key_type=\(aqRSA\(aq, key_length=1024, name_real=\(aqAutogenerated Key\(aq, name_comment=\(aqGenerated by SaltStack\(aq, name_email=None, subkey_type=None, subkey_length=None, expire_date=None, use_passphrase=False, user=None, gnupghome=None, keyring=None) Create a key in the GPG keychain .sp \fBNOTE:\fP @@ -188444,7 +180264,7 @@ Create a key in the GPG keychain GPG key generation requires \fIa lot\fP of entropy and randomness. Difficult to do over a remote connection, consider having another process available which is generating randomness for -the machine. Also especially difficult on virtual machines, +the machine. Also especially difficult on virtual machines, consider the \fI\%rng\-tools\fP package. .sp @@ -188482,16 +180302,23 @@ You can specify an ISO date, A number of days/weeks/months/years, an epoch value, or 0 for a non\-expiring key. .TP .B use_passphrase -Whether to use a passphrase with the signing key. Passphrase is received -from Pillar. +Whether to use a passphrase with the signing key. The passphrase is +retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188508,34 +180335,41 @@ salt \-t 15 \(aq*\(aq gpg.create_key .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, bare=False) -Decrypt a message or file +.B salt.modules.gpg.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, bare=False, keyring=None) +Decrypt a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B text The encrypted text to decrypt. .TP .B filename -The encrypted filename to decrypt. +The path of the encrypted file to decrypt. .TP .B output -The filename where the decrypted data will be written, default is standard out. +Instead of printing to standard out, write the output to this path. .TP .B use_passphrase -Whether to use a passphrase with the signing key. Passphrase is received -from Pillar. +Whether to use a passphrase with the signing key. The passphrase is retrieved +from Pillar value \fBgpg_passphrase\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. .TP .B bare If \fBTrue\fP, return the (armored) decrypted block as a string without the standard comment/res dict. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188554,8 +180388,8 @@ salt \(aq*\(aq gpg.decrypt filename=\(aq/path/to/important.file.gpg\(aq use_pass .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None, use_passphrase=True) -Get a key from the GPG keychain +.B salt.modules.gpg.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None, use_passphrase=True, keyring=None) +Delete a key from the GPG keychain. .INDENT 7.0 .TP .B keyid @@ -188570,18 +180404,26 @@ Secret keys must be deleted before deleting any corresponding public keys. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. .TP .B use_passphrase -Whether to use a passphrase with the signing key. Passphrase is received -from Pillar. +Whether to use a passphrase with the signing key. The passphrase is retrieved +from the Pillar key \fBgpg_passphrase\fP\&. Note that this defaults to True here, +contrary to the rest of the module functions that provide this parameter. .sp New in version 3003. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188604,13 +180446,13 @@ salt \(aq*\(aq gpg.delete_key keyid=3FAD9F1E user=username delete_secret=True .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.encrypt(user=None, recipients=None, text=None, filename=None, output=None, sign=None, use_passphrase=False, always_trust=False, gnupghome=None, bare=False) -Encrypt a message or file +.B salt.modules.gpg.encrypt(user=None, recipients=None, text=None, filename=None, output=None, sign=None, use_passphrase=False, always_trust=False, gnupghome=None, bare=False, keyring=None) +Encrypt a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B recipients @@ -188621,10 +180463,10 @@ key can be used. The text to encrypt. .TP .B filename -The filename to encrypt. +The path of the file to encrypt. .TP .B output -The filename where the signed file will be written, default is standard out. +Instead of printing to standard out, write the output to this path. .TP .B sign Whether to sign, in addition to encrypt, the data. \fBTrue\fP to use @@ -188632,7 +180474,7 @@ default key or fingerprint to specify a different key to sign with. .TP .B use_passphrase Whether to use a passphrase with the signing key. -Passphrase is received from Pillar. +The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B always_trust Skip key validation and assume that used keys are fully trusted. @@ -188641,11 +180483,18 @@ New in version 3006.0. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. .TP .B bare If \fBTrue\fP, return the (armored) encrypted block as a string without the standard comment/res dict. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188667,7 +180516,7 @@ salt \(aq*\(aq gpg.encrypt filename=\(aq/path/to/important.file\(aq sign=True us .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.export_key(keyids=None, secret=False, user=None, gnupghome=None, use_passphrase=False, output=None, bare=False) +.B salt.modules.gpg.export_key(keyids=None, secret=False, user=None, gnupghome=None, use_passphrase=False, output=None, bare=False, keyring=None) Export a key from the GPG keychain .INDENT 7.0 .TP @@ -188681,21 +180530,21 @@ Export the secret key identified by the \fBkeyids\fP information passed. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. .TP .B use_passphrase Whether to use a passphrase to export the secret key. -Passphrase is received from Pillar. +The passphrase is retrieved from the Pillar key \fBgpg_passphrase\fP\&. .sp New in version 3003. .TP .B output -The filename where the exported key data will be written to, default is standard out. +Instead of printing to standard out, write the output to this path. .sp New in version 3006.0. @@ -188706,6 +180555,13 @@ standard comment/res dict. .sp New in version 3006.0. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188726,7 +180582,7 @@ salt \(aq*\(aq gpg.export_key keyids=\(dq[\(aq3FAD9F1E\(aq,\(aq3FBD8F1E\(aq]\(dq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.get_key(keyid=None, fingerprint=None, user=None, gnupghome=None) +.B salt.modules.gpg.get_key(keyid=None, fingerprint=None, user=None, gnupghome=None, keyring=None) Get a key from the GPG keychain .INDENT 7.0 .TP @@ -188738,11 +180594,18 @@ The fingerprint of the key to be retrieved. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188763,8 +180626,8 @@ salt \(aq*\(aq gpg.get_key keyid=3FAD9F1E user=username .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.get_secret_key(keyid=None, fingerprint=None, user=None, gnupghome=None) -Get a key from the GPG keychain +.B salt.modules.gpg.get_secret_key(keyid=None, fingerprint=None, user=None, gnupghome=None, keyring=None) +Get a secret key from the GPG keychain .INDENT 7.0 .TP .B keyid @@ -188775,11 +180638,18 @@ The fingerprint of the key to be retrieved. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188800,23 +180670,30 @@ salt \(aq*\(aq gpg.get_secret_key keyid=3FAD9F1E user=username .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.import_key(text=None, filename=None, user=None, gnupghome=None) -Import a key from text or file +.B salt.modules.gpg.import_key(text=None, filename=None, user=None, gnupghome=None, keyring=None) +Import a key from text or a file .INDENT 7.0 .TP .B text -The text containing to import. +The text containing the key to import. .TP .B filename -The filename containing the key to import. +The path of the file containing the key to import. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188834,17 +180711,24 @@ salt \(aq*\(aq gpg.import_key filename=\(aq/path/to/public\-key\-file\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.list_keys(user=None, gnupghome=None) +.B salt.modules.gpg.list_keys(user=None, gnupghome=None, keyring=None) List keys in GPG keychain .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188861,17 +180745,24 @@ salt \(aq*\(aq gpg.list_keys .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.list_secret_keys(user=None, gnupghome=None) +.B salt.modules.gpg.list_secret_keys(user=None, gnupghome=None, keyring=None) List secret keys in GPG keychain .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188888,24 +180779,31 @@ salt \(aq*\(aq gpg.list_secret_keys .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.receive_keys(keyserver=None, keys=None, user=None, gnupghome=None) -Receive key(s) from keyserver and add them to keychain +.B salt.modules.gpg.receive_keys(keyserver=None, keys=None, user=None, gnupghome=None, keyring=None) +Receive key(s) from keyserver and add them to the keychain .INDENT 7.0 .TP .B keyserver Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org .TP .B keys -The keyID(s) to retrieve from the keyserver. Can be specified as a comma +The keyID(s) to retrieve from the keyserver. Can be specified as a comma separated string or a list. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188926,8 +180824,8 @@ salt \(aq*\(aq gpg.receive_keys keys=3FAD9F1E user=username .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.search_keys(text, keyserver=None, user=None) -Search keys from keyserver +.B salt.modules.gpg.search_keys(text, keyserver=None, user=None, gnupghome=None) +Search for keys on a keyserver .INDENT 7.0 .TP .B text @@ -188938,8 +180836,14 @@ Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. +.TP +.B gnupghome +Specify the location where the GPG keyring and related files are stored. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -188960,34 +180864,41 @@ salt \(aq*\(aq gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com u .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.sign(user=None, keyid=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None) -Sign message or file +.B salt.modules.gpg.sign(user=None, keyid=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, keyring=None) +Sign a message or a file .INDENT 7.0 .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B keyid -The keyid of the key to set the trust level for, defaults to +The keyid of the key to use for signing, defaults to the first key in the secret keyring. .TP .B text The text to sign. .TP .B filename -The filename to sign. +The path of the file to sign. .TP .B output -The filename where the signed file will be written, default is standard out. +Instead of printing to standard out, write the output to this path. .TP .B use_passphrase -Whether to use a passphrase with the signing key. Passphrase is received -from Pillar. +Whether to use a passphrase with the signing key. The passphrase is +retrieved from the Pillar key \fBgpg_passphrase\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -189008,8 +180919,8 @@ salt \(aq*\(aq gpg.sign filename=\(aq/path/to/important.file\(aq use_passphrase= .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.trust_key(keyid=None, fingerprint=None, trust_level=None, user=None) -Set the trust level for a key in GPG keychain +.B salt.modules.gpg.trust_key(keyid=None, fingerprint=None, trust_level=None, user=None, gnupghome=None, keyring=None) +Set the trust level for a key in the GPG keychain .INDENT 7.0 .TP .B keyid @@ -189025,8 +180936,21 @@ expired, unknown, not_trusted, marginally, fully, ultimately .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. +.TP +.B gnupghome +Specify the location where the GPG keyring and related files are stored. +.sp +New in version 3007.0. + +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -189045,26 +180969,26 @@ salt \(aq*\(aq gpg.trust_key keys=3FAD9F1E trust_level=\(aqultimately\(aq user=\ .UNINDENT .INDENT 0.0 .TP -.B salt.modules.gpg.verify(text=None, user=None, filename=None, gnupghome=None, signature=None, trustmodel=None) -Verify a message or file +.B salt.modules.gpg.verify(text=None, user=None, filename=None, gnupghome=None, signature=None, trustmodel=None, signed_by_any=None, signed_by_all=None, keyring=None) +Verify a message or a file .INDENT 7.0 .TP .B text The text to verify. .TP .B filename -The filename to verify. +The path of the file to verify. .TP .B user Which user\(aqs keychain to access, defaults to user Salt is running as. -Passing the user as \fBsalt\fP will set the GnuPG home directory to the +Passing the user as \fBsalt\fP will set the GnuPG home directory to \fB/etc/salt/gpgkeys\fP\&. .TP .B gnupghome -Specify the location where GPG keyring and related files are stored. +Specify the location where the GPG keyring and related files are stored. .TP .B signature -Specify the filename of a detached signature. +Specify the path of a detached signature. .sp New in version 2018.3.0. @@ -189093,6 +181017,31 @@ auto .sp New in version 2019.2.0. +.TP +.B signed_by_any +A list of key fingerprints from which any valid signature +will mark verification as passed. If none of the provided +keys signed the data, verification will fail. Optional. +Note that this does not take into account trust. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +A list of key fingerprints whose signatures are required +for verification to pass. If a single provided key did +not sign the data, verification will fail. Optional. +Note that this does not take into account trust. +.sp +New in version 3007.0. + +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -189103,7 +181052,6 @@ CLI Example: .ft C salt \(aq*\(aq gpg.verify text=\(aqHello there. How are you?\(aq salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq -salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq use_passphrase=True salt \(aq*\(aq gpg.verify filename=\(aq/path/to/important.file\(aq trustmodel=direct .ft P .fi @@ -190876,7 +182824,7 @@ minion, and it is using a different module (or gives an error similar to .UNINDENT .INDENT 0.0 .TP -.B salt.modules.groupadd.add(name, gid=None, system=False, root=None, non_unique=False) +.B salt.modules.groupadd.add(name, gid=None, system=False, root=None, non_unique=False, local=False) Changed in version 3006.0. .sp @@ -190900,6 +182848,12 @@ Allow creating groups with duplicate (non\-unique) GIDs .sp New in version 3006.0. +.TP +.B local +Specifically add the group locally rather than through remote providers (e.g. LDAP) +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -190984,7 +182938,7 @@ salt \(aq*\(aq group.chgid foo 4376 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.groupadd.delete(name, root=None) +.B salt.modules.groupadd.delete(name, root=None, local=False) Remove the named group .INDENT 7.0 .TP @@ -190993,6 +182947,13 @@ Name group to delete .TP .B root Directory to chroot into +.TP +.B local (Only on systems with lgroupdel available): +Ensure the group account is removed locally ignoring global +account management (default is False). +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -194495,7 +186456,7 @@ Passes through all the parameters described in the \fI\%utils.http.query function\fP: .INDENT 7.0 .TP -.B salt.utils.http.query(url, method=\(aqGET\(aq, params=None, data=None, data_file=None, header_dict=None, header_list=None, header_file=None, username=None, password=None, auth=None, decode=False, decode_type=\(aqauto\(aq, status=False, headers=False, text=False, cookies=None, cookie_jar=None, cookie_format=\(aqlwp\(aq, persist_session=False, session_cookie_jar=None, data_render=False, data_renderer=None, header_render=False, header_renderer=None, template_dict=None, test=False, test_url=None, node=\(aqminion\(aq, port=80, opts=None, backend=None, ca_bundle=None, verify_ssl=None, cert=None, text_out=None, headers_out=None, decode_out=None, stream=False, streaming_callback=None, header_callback=None, handle=False, agent=\(aqSalt/3006.7\(aq, hide_fields=None, raise_error=True, formdata=False, formdata_fieldname=None, formdata_filename=None, decode_body=True, **kwargs) +.B salt.utils.http.query(url, method=\(aqGET\(aq, params=None, data=None, data_file=None, header_dict=None, header_list=None, header_file=None, username=None, password=None, auth=None, decode=False, decode_type=\(aqauto\(aq, status=False, headers=False, text=False, cookies=None, cookie_jar=None, cookie_format=\(aqlwp\(aq, persist_session=False, session_cookie_jar=None, data_render=False, data_renderer=None, header_render=False, header_renderer=None, template_dict=None, test=False, test_url=None, node=\(aqminion\(aq, port=80, opts=None, backend=None, ca_bundle=None, verify_ssl=None, cert=None, text_out=None, headers_out=None, decode_out=None, stream=False, streaming_callback=None, header_callback=None, handle=False, agent=\(aqSalt/3007.0\(aq, hide_fields=None, raise_error=True, formdata=False, formdata_fieldname=None, formdata_filename=None, decode_body=True, **kwargs) Query a resource, and decode the return data .UNINDENT .INDENT 7.0 @@ -203061,6 +195022,14 @@ salt \(aqdevice_name\(aq junos.zeroize .UNINDENT .SS salt.modules.k8s .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%kubernetes Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Salt module to manage Kubernetes cluster .sp New in version 2016.3.0. @@ -206332,6 +198301,14 @@ salt \(aq*\(aq kmod.remove kvm .UNINDENT .SS salt.modules.kubeadm .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%kubernetes Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Module for kubeadm :maintainer: Alberto Planas <\fI\%aplanas@suse.com\fP> :maturity: new @@ -207277,6 +199254,14 @@ salt \(aq*\(aq kubeadm.version .UNINDENT .SS salt.modules.kubernetesmod .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%kubernetes Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Module for handling kubernetes calls. .INDENT 0.0 .TP @@ -214635,7 +206620,7 @@ CLI Example: .sp .nf .ft C -salt myminion lxc.run mycontainer \(aqifconfig \-a\(aq +salt myminion lxc.run mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT @@ -214904,7 +206889,7 @@ CLI Example: .sp .nf .ft C -salt myminion lxc.run_stdout mycontainer \(aqifconfig \-a\(aq +salt myminion lxc.run_stdout mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT @@ -218622,6 +210607,14 @@ salt \(aq*\(aq assistive.remove com.smileonmymac.textexpander .sp Homebrew for macOS .sp +It is recommended for the \fBsalt\-minion\fP to have the \fBHOMEBREW_PREFIX\fP +environment variable set. +.sp +This will ensure that Salt uses the correct path for the \fBbrew\fP binary. +.sp +Typically, this is set to \fB/usr/local\fP for Intel Macs and \fB/opt/homebrew\fP +for Apple Silicon Macs. +.sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 @@ -218705,6 +210698,23 @@ salt \(aq*\(aq pkg.hold pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .UNINDENT .INDENT 0.0 .TP +.B salt.modules.mac_brew_pkg.homebrew_prefix() +Returns the full path to the homebrew prefix. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq pkg.homebrew_prefix +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.mac_brew_pkg.info_installed(*names, **kwargs) Return the information of the named package(s) installed on the system. .sp @@ -229636,7 +221646,7 @@ salt \(aq*\(aq mount.swaps .UNINDENT .INDENT 0.0 .TP -.B salt.modules.mount.umount(name, device=None, user=None, util=\(aqmount\(aq) +.B salt.modules.mount.umount(name, device=None, user=None, util=\(aqmount\(aq, lazy=False) Attempt to unmount a device by specifying the directory it is mounted on .sp CLI Example: @@ -235309,37 +227319,6 @@ salt \(aq*\(aq napalm.netmiko_config https://bit.ly/2sgljCB .UNINDENT .INDENT 0.0 .TP -.B salt.modules.napalm_mod.netmiko_conn(**kwargs) -New in version 2019.2.0. - -.sp -Return the connection object with the network device, over Netmiko, passing -the authentication details from the existing NAPALM connection. -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -This function is not suitable for CLI usage, more rather to be used -in various Salt modules. -.UNINDENT -.UNINDENT -.sp -USAGE Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -conn = __salt__[\(aqnapalm.netmiko_conn\(aq]() -res = conn.send_command(\(aqshow interfaces\(aq) -conn.disconnect() -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.napalm_mod.netmiko_fun(fun, *args, **kwargs) New in version 2019.2.0. @@ -235640,38 +227619,6 @@ salt \(aq*\(aq napalm.pyeapi_config \(aqntp server 1.2.3.4\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.napalm_mod.pyeapi_conn(**kwargs) -New in version 2019.2.0. - -.sp -Return the connection object with the Arista switch, over \fBpyeapi\fP, -passing the authentication details from the existing NAPALM connection. -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -This function is not suitable for CLI usage, more rather to be used in -various Salt modules, to reusing the established connection, as in -opposite to opening a new connection for each task. -.UNINDENT -.UNINDENT -.sp -Usage example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -conn = __salt__[\(aqnapalm.pyeapi_conn\(aq]() -res1 = conn.run_commands(\(aqshow version\(aq) -res2 = conn.get_config(as_string=True) -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.napalm_mod.pyeapi_nxos_api_args(**prev_kwargs) New in version 2019.2.0. @@ -243866,6 +235813,46 @@ salt \(aq*\(aq network.ip_in_subnet 172.17.0.4 172.16.0.0/12 .UNINDENT .INDENT 0.0 .TP +.B salt.modules.network.ip_neighs() +Return the ip neighbour (arp) table from the minion for IPv4 addresses +.sp +New in version 3007.0. + +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_neighs +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.network.ip_neighs6() +Return the ip neighbour (arp) table from the minion for IPv6 addresses +.sp +New in version 3007.0. + +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_neighs6 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.network.ip_networks(interface=None, include_loopback=False, verbose=False) New in version 3001. @@ -244007,6 +235994,56 @@ salt \(aq*\(aq network.iphexval 10.0.0.1 .UNINDENT .INDENT 0.0 .TP +.B salt.modules.network.ipneighs() +This function is an alias of \fBip_neighs\fP\&. +.INDENT 7.0 +.INDENT 3.5 +Return the ip neighbour (arp) table from the minion for IPv4 addresses +.sp +New in version 3007.0. + +.sp +CLI Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_neighs +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.network.ipneighs6() +This function is an alias of \fBip_neighs6\fP\&. +.INDENT 7.0 +.INDENT 3.5 +Return the ip neighbour (arp) table from the minion for IPv6 addresses +.sp +New in version 3007.0. + +.sp +CLI Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_neighs6 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.network.is_loopback(ip_addr) Check if the given IP address is a loopback address .sp @@ -250456,7 +242493,7 @@ CLI Example: .sp .nf .ft C -salt myminion nspawn.run mycontainer \(aqifconfig \-a\(aq +salt myminion nspawn.run mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT @@ -250630,7 +242667,7 @@ CLI Example: .sp .nf .ft C -salt myminion nspawn.run_stdout mycontainer \(aqifconfig \-a\(aq +salt myminion nspawn.run_stdout mycontainer \(aqip addr show\(aq .ft P .fi .UNINDENT @@ -252853,6 +244890,68 @@ salt \(aq*\(aq openscap.xccdf \(dqeval \-\-profile Default /usr/share/openscap/ .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.openscap.xccdf_eval(xccdffile, ovalfiles=None, profile=None, rule=None, oval_results=None, results=None, report=None, fetch_remote_resources=None, tailoring_file=None, tailoring_id=None, remediate=None) +Run \fBoscap xccdf eval\fP commands on minions. +.sp +New in version 3007.0. + +.sp +It uses cp.push_dir to upload the generated files to the salt master +in the master\(aqs minion files cachedir +(defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) +.sp +It needs \fBfile_recv\fP set to \fBTrue\fP in the master configuration file. +.INDENT 7.0 +.TP +.B xccdffile +the path to the xccdf file to evaluate +.TP +.B ovalfiles +additional oval definition files +.TP +.B profile +the name of Profile to be evaluated +.TP +.B rule +the name of a single rule to be evaluated +.TP +.B oval_results +save OVAL results as well (True or False) +.TP +.B results +write XCCDF Results into given file +.TP +.B report +write HTML report into given file +.TP +.B fetch_remote_resources +download remote content referenced by XCCDF (True or False) +.TP +.B tailoring_file +use given XCCDF Tailoring file +.TP +.B tailoring_id +use given DS component as XCCDF Tailoring file +.TP +.B remediate +automatically execute XCCDF fix elements for failed rules. +Use of this option is always at your own risk. (True or False) +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq openscap.xccdf_eval /usr/share/openscap/scap\-yast2sec\-xccdf.xml profile=Default +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.modules.openstack_config .sp Modify, retrieve, or delete values from OpenStack configuration files. @@ -271426,6 +263525,14 @@ salt \(dq*\(dq pushbullet.push_note device=\(dqChrome\(dq title=\(dqExample titl .UNINDENT .SS salt.modules.pushover_notify .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%pushover Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) .sp New in version 2016.3.0. @@ -280345,7 +272452,7 @@ New in version 3000. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.saltcheck.run_highstate_tests(saltenv=None, only_fails=False) +.B salt.modules.saltcheck.run_highstate_tests(saltenv=None, only_fails=False, junit=False) Execute all tests for states assigned to the minion through highstate and return results .INDENT 7.0 .TP @@ -280355,6 +272462,9 @@ Execute all tests for states assigned to the minion through highstate and return \fBsaltenv\fP (\fI\%str\fP) \-\- optional saltenv. Defaults to base .IP \(bu 2 \fBonly_fails\fP (\fI\%bool\fP) \-\- boolean to only print failure results +.IP \(bu 2 +\fBjunit\fP (\fI\%bool\fP) \-\- boolean to print results in junit format +\&.. versionadded:: 3007.0 .UNINDENT .UNINDENT .sp @@ -280372,7 +272482,7 @@ salt \(aq*\(aq saltcheck.run_highstate_tests .UNINDENT .INDENT 0.0 .TP -.B salt.modules.saltcheck.run_state_tests(state, saltenv=None, check_all=False, only_fails=False) +.B salt.modules.saltcheck.run_state_tests(state, saltenv=None, check_all=False, only_fails=False, junit=False) Execute tests for a salt state and return results Nested states will also be tested .INDENT 7.0 @@ -280387,6 +272497,9 @@ Nested states will also be tested \fBcheck_all\fP (\fI\%bool\fP) \-\- boolean to run all tests in state/saltcheck\-tests directory .IP \(bu 2 \fBonly_fails\fP (\fI\%bool\fP) \-\- boolean to only print failure results +.IP \(bu 2 +\fBjunit\fP (\fI\%bool\fP) \-\- boolean to print results in junit format +\&.. versionadded:: 3007.0 .UNINDENT .UNINDENT .sp @@ -280409,7 +272522,7 @@ of parallel processes. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.saltcheck.run_state_tests_ssh(state, saltenv=None, check_all=False, only_fails=False) +.B salt.modules.saltcheck.run_state_tests_ssh(state, saltenv=None, check_all=False, only_fails=False, junit=False) This function is an alias of \fBrun_state_tests\fP\&. .INDENT 7.0 .INDENT 3.5 @@ -280428,6 +272541,10 @@ boolean to run all tests in state/saltcheck\-tests directory .TP .B param bool only_fails boolean to only print failure results +.TP +.B param bool junit +boolean to print results in junit format +\&.. versionadded:: 3007.0 .UNINDENT .sp CLI Example: @@ -281076,6 +273193,12 @@ salt \(aq*\(aq saltutil.signal_job 15 .INDENT 0.0 .TP .B salt.modules.saltutil.sync_all(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None, clean_pillar_cache=False) +Changed in version 3007.0: On masterless minions, master top modules are now synced as well. +When \fBrefresh\fP is set to \fBTrue\fP, this module\(aqs cache containing +the environments from which extension modules are synced when +\fBsaltenv\fP is not specified will be refreshed. + +.sp Changed in version 2015.8.11,2016.3.2: On masterless minions, pillar modules are now synced, and refreshed when \fBrefresh\fP is set to \fBTrue\fP\&. @@ -281088,7 +273211,9 @@ grains, returners, output modules, renderers, and utils. .B refresh True Also refresh the execution modules and recompile pillar data available -to the minion. This refresh will be performed even if no new dynamic +to the minion. If this is a masterless minion, also refresh the environments +from which extension modules are synced after syncing master tops. +This refresh will be performed even if no new dynamic modules are synced. Set to \fBFalse\fP to prevent this refresh. .UNINDENT .sp @@ -281739,8 +273864,7 @@ are found, then the \fBbase\fP environment will be synced. True If \fBTrue\fP, refresh the available execution modules on the minion. This refresh will be performed even if no new renderers are synced. -Set to \fBFalse\fP to prevent this refresh. Set to \fBFalse\fP to prevent -this refresh. +Set to \fBFalse\fP to prevent this refresh. .TP .B extmod_whitelist None @@ -281825,11 +273949,6 @@ one environment, pass a comma\-separated list. If not passed, then all environments configured in the \fI\%top files\fP will be checked for sdb modules to sync. If no top files are found, then the \fBbase\fP environment will be synced. .TP -.B refresh -False -This argument has no affect and is included for consistency with the -other sync functions. -.TP .B extmod_whitelist None comma\-separated list of modules to sync @@ -281986,6 +274105,59 @@ salt \(aq*\(aq saltutil.sync_thorium saltenv=base,dev .UNINDENT .INDENT 0.0 .TP +.B salt.modules.saltutil.sync_tops(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) +New in version 3007.0. + +.sp +Sync master tops from \fBsalt://_tops\fP to the minion. +.INDENT 7.0 +.TP +.B saltenv +The fileserver environment from which to sync. To sync from more than +one environment, pass a comma\-separated list. +.sp +If not passed, then all environments configured in the \fI\%top files\fP will be checked for master tops to sync. If no top files +are found, then the \fBbase\fP environment will be synced. +.TP +.B refresh +True +Refresh this module\(aqs cache containing the environments from which +extension modules are synced when \fBsaltenv\fP is not specified. +This refresh will be performed even if no new master tops are synced. +Set to \fBFalse\fP to prevent this refresh. +.TP +.B extmod_whitelist +None +comma\-separated list of modules to sync +.TP +.B extmod_blacklist +None +comma\-separated list of modules to blacklist based on type +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function will raise an error if executed on a traditional (i.e. +not masterless) minion +.UNINDENT +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq saltutil.sync_tops +salt \(aq*\(aq saltutil.sync_tops saltenv=dev +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.saltutil.sync_utils(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) New in version 2014.7.0. @@ -282031,6 +274203,59 @@ salt \(aq*\(aq saltutil.sync_utils saltenv=base,dev .UNINDENT .INDENT 0.0 .TP +.B salt.modules.saltutil.sync_wrapper(saltenv=None, refresh=True, extmod_whitelist=None, extmod_blacklist=None) +New in version 3007.0. + +.sp +Sync salt\-ssh wrapper modules from \fBsalt://_wrapper\fP to the minion. +.INDENT 7.0 +.TP +.B saltenv +The fileserver environment from which to sync. To sync from more than +one environment, pass a comma\-separated list. +.sp +If not passed, then all environments configured in the \fI\%top files\fP will be checked for wrappers to sync. If no top files +are found, then the \fBbase\fP environment will be synced. +.TP +.B refresh +True +If \fBTrue\fP, refresh the available wrapper modules on the minion. +This refresh will be performed even if no wrappers are synced. +Set to \fBFalse\fP to prevent this refresh. +.TP +.B extmod_whitelist +None +comma\-seperated list of modules to sync +.TP +.B extmod_blacklist +None +comma\-seperated list of modules to blacklist based on type +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This function will raise an error if executed on a traditional (i.e. +not masterless) minion. +.UNINDENT +.UNINDENT +.sp +CLI Examples: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq saltutil.sync_wrapper +salt \(aq*\(aq saltutil.sync_wrapper saltenv=dev +salt \(aq*\(aq saltutil.sync_wrapper saltenv=base,dev +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.saltutil.term_all_jobs() Sends a termination signal (SIGTERM 15) to all currently running jobs .sp @@ -283329,8 +275554,8 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq selinux.port_add_policy add tcp/8080 http_port_t -salt \(aq*\(aq selinux.port_add_policy add foobar http_port_t protocol=tcp port=8091 +salt \(aq*\(aq selinux.port_add_policy tcp/8080 http_port_t +salt \(aq*\(aq selinux.port_add_policy foobar http_port_t protocol=tcp port=8091 .ft P .fi .UNINDENT @@ -283418,6 +275643,46 @@ salt \(aq*\(aq selinux.port_get_policy foobar protocol=tcp port=80 .UNINDENT .INDENT 0.0 .TP +.B salt.modules.selinux.port_modify_policy(name, sel_type=None, protocol=None, port=None, sel_range=None) +New in version 2019.2.0. + +.sp +Modifies the SELinux policy for a given protocol and port. +.sp +Returns the result of the call to semanage. +.INDENT 7.0 +.TP +.B name +The protocol and port spec. Can be formatted as \fB(tcp|udp)/(port|port\-range)\fP\&. +.TP +.B sel_type +The SELinux Type. Required. +.TP +.B protocol +The protocol for the port, \fBtcp\fP or \fBudp\fP\&. Required if name is not formatted. +.TP +.B port +The port or port range. Required if name is not formatted. +.TP +.B sel_range +The SELinux MLS/MCS Security Range. +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq selinux.port_modify_policy tcp/8080 http_port_t +salt \(aq*\(aq selinux.port_modify_policy foobar http_port_t protocol=tcp port=8091 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.selinux.remove_semod(module) Remove SELinux module .sp @@ -294626,6 +286891,14 @@ salt \(aq*\(aq supervisord.update .UNINDENT .SS salt.modules.suse_apache .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Support for Apache .sp Please note: The functions in here are SUSE\-specific. Placing them in this @@ -297678,24 +289951,26 @@ Support for reboot, shutdown, etc on POSIX\-like systems. \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -If you have configured a wrapper such as \fBmolly\-guard\fP to -intercept \fIinteractive\fP shutdown commands, be aware that calling -\fBsystem.halt\fP, \fBsystem.poweroff\fP, \fBsystem.reboot\fP, and -\fBsystem.shutdown\fP with \fBsalt\-call\fP will hang indefinitely -while the wrapper script waits for user input. Calling them with -\fBsalt\fP will work as expected. +If a wrapper such as \fBmolly\-guard\fP to intercept \fIinteractive\fP shutdown +commands is configured, calling \fI\%system.halt\fP, +\fI\%system.poweroff\fP, +\fI\%system.reboot\fP, and +\fI\%system.shutdown\fP with \fBsalt\-call\fP will +hang indefinitely while the wrapper script waits for user input. Calling them +with \fBsalt\fP will work as expected. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.system.get_computer_desc() -Get PRETTY_HOSTNAME value stored in /etc/machine\-info +Get \fBPRETTY_HOSTNAME\fP value stored in \fB/etc/machine\-info\fP If this file doesn\(aqt exist or the variable doesn\(aqt exist -return False. +return \fBFalse\fP\&. .INDENT 7.0 .TP .B Returns -Value of PRETTY_HOSTNAME if this does not exist False. +Value of \fBPRETTY_HOSTNAME\fP in \fB/etc/machine\-info\fP\&. +If file/variable does not exist \fBFalse\fP\&. .TP .B Return type \fI\%str\fP @@ -297733,6 +290008,14 @@ salt \(aq*\(aq network.get_hostname .INDENT 0.0 .TP .B salt.modules.system.get_reboot_required_witnessed() +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This only applies to Minions running on NI Linux RT +.UNINDENT +.UNINDENT +.sp Determine if at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required. .INDENT 7.0 @@ -297763,11 +290046,11 @@ Get the system date .INDENT 7.0 .TP .B Parameters -\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an -optional sign (+/\-). Will default to None which will use the local -timezone. To set the time based off of UTC use \(dq\(aq+0000\(aq\(dq. Note: if +\fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an +optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local +timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to -allow negative offsets. +allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns Returns the system date. @@ -297795,14 +290078,14 @@ Get the system date/time. .INDENT 7.0 .TP .B Parameters -\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an -optional sign (+/\-). Will default to None which will use the local -timezone. To set the time based off of UTC use \(dq\(aq+0000\(aq\(dq. Note: if +\fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an +optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local +timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to -allow negative offsets. +allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns -Returns the system time in YYYY\-MM\-DD hh:mm:ss format. +Returns the system time in \fBYYYY\-MM\-DD hh:mm:ss\fP format. .TP .B Return type \fI\%str\fP @@ -297827,14 +290110,14 @@ Get the system time. .INDENT 7.0 .TP .B Parameters -\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an -optional sign (+/\-). Will default to None which will use the local -timezone. To set the time based off of UTC use \(dq\(aq+0000\(aq\(dq. Note: if +\fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (e.g. \fB+0600\fP) format with an +optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local +timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to -allow negative offsets. +allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .TP .B Returns -Returns the system time in HH:MM:SS AM/PM format. +Returns the system time in \fBHH:MM:SS AM/PM\fP format. .TP .B Return type \fI\%str\fP @@ -297872,7 +290155,7 @@ salt \(aq*\(aq system.halt .INDENT 0.0 .TP .B salt.modules.system.has_settable_hwclock() -Returns True if the system has a hardware clock capable of being +Returns \fBTrue\fP if the system has a hardware clock capable of being set from software. .sp CLI Example: @@ -297946,16 +290229,16 @@ salt \(aq*\(aq system.reboot .INDENT 0.0 .TP .B salt.modules.system.set_computer_desc(desc) -Set PRETTY_HOSTNAME value stored in /etc/machine\-info +Set \fBPRETTY_HOSTNAME\fP value stored in \fB/etc/machine\-info\fP This will create the file if it does not exist. If -it is unable to create or modify this file returns False. +it is unable to create or modify this file, \fBFalse\fP is returned. .INDENT 7.0 .TP .B Parameters \fBdesc\fP (\fI\%str\fP) \-\- The computer description .TP .B Returns -False on failure. True if successful. +\fBFalse\fP on failure. \fBTrue\fP if successful. .UNINDENT .sp CLI Example: @@ -297990,6 +290273,14 @@ salt \(aq*\(aq system.set_computer_name master.saltstack.com .INDENT 0.0 .TP .B salt.modules.system.set_reboot_required_witnessed() +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This only applies to Minions running on NI Linux RT +.UNINDENT +.UNINDENT +.sp This function is used to remember that an event indicating that a reboot is required was witnessed. This function writes to a temporary filesystem so the event gets cleared upon reboot. @@ -298001,6 +290292,8 @@ the event gets cleared upon reboot. .B Return type \fI\%bool\fP .UNINDENT +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp @@ -298015,7 +290308,7 @@ salt \(aq*\(aq system.set_reboot_required_witnessed .INDENT 0.0 .TP .B salt.modules.system.set_system_date(newdate, utc_offset=None) -Set the system date. Use format for the date. +Set the system date. Use \fB\fP format for the date. .INDENT 7.0 .TP .B Parameters @@ -298024,17 +290317,17 @@ Set the system date. Use format for the date. The date to set. Can be any of the following formats: .INDENT 7.0 .IP \(bu 2 -YYYY\-MM\-DD +\fBYYYY\-MM\-DD\fP .IP \(bu 2 -MM\-DD\-YYYY +\fBMM\-DD\-YYYY\fP .IP \(bu 2 -MM\-DD\-YY +\fBMM\-DD\-YY\fP .IP \(bu 2 -MM/DD/YYYY +\fBMM/DD/YYYY\fP .IP \(bu 2 -MM/DD/YY +\fBMM/DD/YY\fP .IP \(bu 2 -YYYY/MM/DD +\fBYYYY/MM/DD\fP .UNINDENT .UNINDENT @@ -298056,9 +290349,10 @@ salt \(aq*\(aq system.set_system_date \(aq03\-28\-13\(aq .B salt.modules.system.set_system_date_time(years=None, months=None, days=None, hours=None, minutes=None, seconds=None, utc_offset=None) Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for -that element will be used. For example, if you don\(aqt pass the year, the -current system year will be used. (Used by set_system_date and -set_system_time) +that element will be used. For example, if the year is not passed, the +current system year will be used. (Used by +\fI\%system.set_system_date\fP and +\fI\%system.set_system_time\fP) .sp Updates hardware clock, if present, in addition to software (kernel) clock. @@ -298067,27 +290361,27 @@ Updates hardware clock, if present, in addition to software .B Parameters .INDENT 7.0 .IP \(bu 2 -\fByears\fP (\fI\%int\fP) \-\- Years digit, ie: 2015 +\fByears\fP (\fI\%int\fP) \-\- Years digit, e.g.: \fB2015\fP .IP \(bu 2 -\fBmonths\fP (\fI\%int\fP) \-\- Months digit: 1 \- 12 +\fBmonths\fP (\fI\%int\fP) \-\- Months digit: \fB1\fP\-\fB12\fP .IP \(bu 2 -\fBdays\fP (\fI\%int\fP) \-\- Days digit: 1 \- 31 +\fBdays\fP (\fI\%int\fP) \-\- Days digit: \fB1\fP\-\fB31\fP .IP \(bu 2 -\fBhours\fP (\fI\%int\fP) \-\- Hours digit: 0 \- 23 +\fBhours\fP (\fI\%int\fP) \-\- Hours digit: \fB0\fP\-\fB23\fP .IP \(bu 2 -\fBminutes\fP (\fI\%int\fP) \-\- Minutes digit: 0 \- 59 +\fBminutes\fP (\fI\%int\fP) \-\- Minutes digit: \fB0\fP\-\fB59\fP .IP \(bu 2 -\fBseconds\fP (\fI\%int\fP) \-\- Seconds digit: 0 \- 59 +\fBseconds\fP (\fI\%int\fP) \-\- Seconds digit: \fB0\fP\-\fB59\fP .IP \(bu 2 -\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an -optional sign (+/\-). Will default to None which will use the local -timezone. To set the time based off of UTC use \(dq\(aq+0000\(aq\(dq. Note: if +\fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an +optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local +timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to -allow negative offsets. +allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP). .UNINDENT .TP .B Returns -True if successful. Otherwise False. +\fBTrue\fP if successful. Otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP @@ -298117,26 +290411,32 @@ Set the system time. \fBnewtime\fP (\fI\%str\fP) \-\- .sp The time to set. Can be any of the following formats. -\- HH:MM:SS AM/PM -\- HH:MM AM/PM -\- HH:MM:SS (24 hour) -\- HH:MM (24 hour) +.INDENT 2.0 +.IP \(bu 2 +\fBHH:MM:SS AM/PM\fP +.IP \(bu 2 +\fBHH:MM AM/PM\fP +.IP \(bu 2 +\fBHH:MM:SS\fP (24 hour) +.IP \(bu 2 +\fBHH:MM\fP (24 hour) +.UNINDENT .sp -Note that the salt command line parser parses the date/time -before we obtain the argument (preventing us from doing utc) +Note that the Salt command line parser parses the date/time +before we obtain the argument (preventing us from doing UTC) Therefore the argument must be passed in as a string. -Meaning you may have to quote the text twice from the command line. +Meaning the text might have to be quoted twice on the command line. .IP \(bu 2 -\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an -optional sign (+/\-). Will default to None which will use the local -timezone. To set the time based off of UTC use \(dq\(aq+0000\(aq\(dq. Note: if +\fButc_offset\fP (\fI\%str\fP) \-\- The UTC offset in 4 digit (\fB+0600\fP) format with an +optional sign (\fB+\fP/\fB\-\fP). Will default to \fBNone\fP which will use the local +timezone. To set the time based off of UTC use \fB+0000\fP\&. Note: If being passed through the command line will need to be quoted twice to -allow negative offsets. +allow negative offsets (e.g. \fB\(dq\(aq+0000\(aq\(dq\fP) .UNINDENT .TP .B Returns -Returns True if successful. Otherwise False. +Returns \fBTrue\fP if successful. Otherwise \fBFalse\fP\&. .TP .B Return type \fI\%bool\fP @@ -303831,7 +296131,7 @@ Linux .INDENT 0.0 .TP .B salt.modules.tuned.active() -Return current active profile +Return current active profile in stdout key if retcode is 0, otherwise raw result .sp CLI Example: .INDENT 7.0 @@ -304499,7 +296799,7 @@ minion, and it is using a different module (or gives an error similar to .UNINDENT .INDENT 0.0 .TP -.B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, system=False, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, other=\(aq\(aq, createhome=True, loginclass=None, nologinit=False, root=None, usergroup=None) +.B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, system=False, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, other=\(aq\(aq, createhome=True, loginclass=None, nologinit=False, root=None, usergroup=None, local=False) Add a user to the minion .INDENT 7.0 .TP @@ -304556,6 +296856,12 @@ Directory to chroot into .TP .B usergroup Create and add the user to a new primary group of the same name +.TP +.B local (Only on systems with luseradd available) +Specifically add the user locally rather than possibly through remote providers (e.g. LDAP) +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -304886,7 +297192,7 @@ salt \(aq*\(aq user.chworkphone foo 7735550123 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.useradd.delete(name, remove=False, force=False, root=None) +.B salt.modules.useradd.delete(name, remove=False, force=False, root=None, local=False) Remove a user from the minion .INDENT 7.0 .TP @@ -304901,6 +297207,13 @@ Force some actions that would fail otherwise .TP .B root Directory to chroot into +.TP +.B local (Only on systems with luserdel available): +Ensure the user account is removed locally ignoring global +account management (default is False). +.sp +New in version 3007.0. + .UNINDENT .sp CLI Example: @@ -305270,8 +297583,9 @@ defined by having a \fIconfig.vm.network \(dqpublic_network\(dq\fP statement in The IP address of the bridged adapter will typically be assigned by DHCP and unknown to you, but you should be able to determine what IP network the address will be chosen from. If you enter a CIDR network mask, Salt will attempt to find the VM\(aqs address for you. -The host machine will send an \(dqifconfig\(dq command to the VM (using ssh to \fIssh_host\fP:\fIssh_port\fP) -and return the IP address of the first interface it can find which matches your mask. +The host machine will send an \(dqip link show\(dq or \(dqifconfig\(dq command to the VM +(using ssh to \fIssh_host\fP:\fIssh_port\fP) and return the IP address of the first interface it +can find which matches your mask. .UNINDENT .INDENT 0.0 .TP @@ -305666,7 +297980,14 @@ salt \(aq*\(aq varnish.version .UNINDENT .SS salt.modules.vault .sp -Functions to interact with Hashicorp Vault. +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%vault Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.SS Functions to interact with Hashicorp Vault. .INDENT 0.0 .TP .B maintainer @@ -305691,81 +298012,343 @@ If you see the following error, you\(aqll need to upgrade \fBrequests\fP to at l .fi .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B configuration -The salt\-master must be configured to allow peer\-runner -configuration, as well as configuration for the module. +.SS Configuration .sp -Add this segment to the master configuration file, or -/etc/salt/master.d/vault.conf: -.INDENT 7.0 +In addition to the module configuration, it is required for the Salt master +to be configured to allow peer runs in order to use the Vault integration. +.sp +Changed in version 3007.0: The \fBvault\fP configuration structure has changed significantly to account +for many new features. If found, the old structure will be automatically +translated to the new one. +.sp +\fBPlease update your peer_run configuration\fP to take full advantage of the +updated modules. The old endpoint (\fBvault.generate_token\fP) will continue +to work, but result in unnecessary roundtrips once your minions have been +updated. + +.sp +To allow minions to pull configuration and credentials from the Salt master, +add this segment to the master configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +peer_run: + .*: + \- vault.get_config # always + \- vault.generate_new_token # relevant when \(gatoken\(ga == \(gaissue:type\(ga + \- vault.generate_secret_id # relevant when \(gaapprole\(ga == \(gaissue:type\(ga +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Minimally required configuration: +.INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vault: - url: https://vault.service.domain:8200 - verify: /etc/ssl/certs/ca\-certificates.crt - role_name: minion_role - namespace: vault_enterprice_namespace - auth: - method: approle - role_id: 11111111\-2222\-3333\-4444\-1111111111111 - secret_id: 11111111\-1111\-1111\-1111\-1111111111111 - policies: - \- saltstack/minions - \- saltstack/minion/{minion} - .. more policies - keys: - \- n63/TbrQuL3xaIW7ZZpuXj/tIfnK1/MbVxO4vT3wYD2A - \- S9OwCvMRhErEA4NVVELYBs6w/Me6+urgUr24xGK44Uy3 - \- F1j4b7JKq850NS6Kboiy5laJ0xY8dWJvB3fcwA+SraYl - \- 1cYtvjKJNDVam9c7HNqJUfINk4PYyAXIpjkpN/sIuzPv - \- 3pPK5X6vGtwLhNOFv1U2elahECz3HpRUfNXJFYLw6lid + auth: + token: abcdefg\-hijklmnop\-qrstuvw + server: + url: https://vault.example.com:8200 .ft P .fi .UNINDENT .UNINDENT +.sp +A sensible example configuration, e.g. in \fB/etc/salt/master.d/vault.conf\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +vault: + auth: + method: approle + role_id: e5a7b66e\-5d08\-da9c\-7075\-71984634b882 + secret_id: 841771dc\-11c9\-bbc7\-bcac\-6a3945a69cd9 + cache: + backend: file + issue: + token: + role_name: salt_minion + params: + explicit_max_ttl: 30 + num_uses: 10 + policies: + assign: + \- salt_minion + \- salt_role_{pillar[roles]} + server: + url: https://vault.example.com:8200 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The above configuration requires the following policies for the master: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Issue tokens +path \(dqauth/token/create\(dq { + capabilities = [\(dqcreate\(dq, \(dqread\(dq, \(dqupdate\(dq] +} + +# Issue tokens with token roles +path \(dqauth/token/create/*\(dq { + capabilities = [\(dqcreate\(dq, \(dqread\(dq, \(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A sensible example configuration that issues AppRoles to minions +from a separate authentication endpoint (notice differing mounts): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +vault: + auth: + method: approle + mount: approle # <\-\- mount the salt master authenticates at + role_id: e5a7b66e\-5d08\-da9c\-7075\-71984634b882 + secret_id: 841771dc\-11c9\-bbc7\-bcac\-6a3945a69cd9 + cache: + backend: file + issue: + type: approle + approle: + mount: salt\-minions # <\-\- mount the salt master manages + metadata: + entity: + minion\-id: \(aq{minion}\(aq + role: \(aq{pillar[role]}\(aq + server: + url: https://vault.example.com:8200 +ext_pillar: + \- vault: path=salt/minions/{minion} + \- vault: path=salt/roles/{pillar[role]} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The above configuration requires the following policies for the master: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# List existing AppRoles +path \(dqauth/salt\-minions/role\(dq { + capabilities = [\(dqlist\(dq] +} + +# Manage AppRoles +path \(dqauth/salt\-minions/role/*\(dq { + capabilities = [\(dqread\(dq, \(dqcreate\(dq, \(dqupdate\(dq, \(dqdelete\(dq] +} + +# Lookup mount accessor +path \(dqsys/auth/salt\-minions\(dq { + capabilities = [\(dqread\(dq, \(dqsudo\(dq] +} + +# Lookup entities by alias name (role\-id) and alias mount accessor +path \(dqidentity/lookup/entity\(dq { + capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] + allowed_parameters = { + \(dqalias_name\(dq = [] + \(dqalias_mount_accessor\(dq = [\(dqauth_approle_0a1b2c3d\(dq] + } +} + +# Manage entities with name prefix salt_minion_ +path \(dqidentity/entity/name/salt_minion_*\(dq { + capabilities = [\(dqread\(dq, \(dqcreate\(dq, \(dqupdate\(dq, \(dqdelete\(dq] +} + +# Create entity aliases – you can restrict the mount_accessor +# This might allow privilege escalation in case the salt master +# is compromised and the attacker knows the entity ID of an +# entity with relevant policies attached \- although you might +# have other problems at that point. +path \(dqidentity/entity\-alias\(dq { + capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] + allowed_parameters = { + \(dqid\(dq = [] + \(dqcanonical_id\(dq = [] + \(dqmount_accessor\(dq = [\(dqauth_approle_0a1b2c3d\(dq] + \(dqname\(dq = [] + } +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This enables you to write templated ACL policies like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqsalt/data/minions/{{identity.entity.metadata.minion\-id}}\(dq { + capabilities = [\(dqread\(dq] +} + +path \(dqsalt/data/roles/{{identity.entity.metadata.role}}\(dq { + capabilities = [\(dqread\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +AppRole policies and entity metadata are generally not updated +automatically. After a change, you will need to synchronize +them by running \fI\%vault.sync_approles\fP +or \fI\%vault.sync_entities\fP respectively. +.UNINDENT +.UNINDENT +.sp +All possible master configuration options with defaults: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +vault: + auth: + approle_mount: approle + approle_name: salt\-master + method: token + role_id: + secret_id: null + token: + token_lifecycle: + minimum_ttl: 10 + renew_increment: null + cache: + backend: session + config: 3600 + kv_metadata: connection + secret: ttl + issue: + allow_minion_override_params: false + type: token + approle: + mount: salt\-minions + params: + bind_secret_id: true + secret_id_num_uses: 1 + secret_id_ttl: 60 + token_explicit_max_ttl: 60 + token_num_uses: 10 + secret_id_bound_cidrs: null + token_ttl: null + token_max_ttl: null + token_no_default_policy: false + token_period: null + token_bound_cidrs: null + token: + role_name: null + params: + explicit_max_ttl: null + num_uses: 1 + ttl: null + period: null + no_default_policy: false + renewable: true + wrap: 30s + keys: [] + metadata: + entity: + minion\-id: \(aq{minion}\(aq + secret: + saltstack\-jid: \(aq{jid}\(aq + saltstack\-minion: \(aq{minion}\(aq + saltstack\-user: \(aq{user}\(aq + policies: + assign: + \- saltstack/minions + \- saltstack/{minion} + cache_time: 60 + refresh_pillar: null + server: + url: + namespace: null + verify: null +.ft P +.fi +.UNINDENT +.UNINDENT +.SS \fBauth\fP +.sp +Contains authentication information for the local machine. +.INDENT 0.0 +.TP +.B approle_mount +New in version 3007.0. + +.sp +The name of the AppRole authentication mount point. Defaults to \fBapprole\fP\&. +.TP +.B approle_name +New in version 3007.0. + +.sp +The name of the AppRole. Defaults to \fBsalt\-master\fP\&. +.sp +\fBNOTE:\fP .INDENT 7.0 +.INDENT 3.5 +Only relevant when a locally configured role_id/secret_id uses +response wrapping. +.UNINDENT +.UNINDENT .TP -.B url -Url to your Vault installation. Required. -.TP -.B verify -For details please see -\fI\%https://requests.readthedocs.io/en/master/user/advanced/#ssl\-cert\-verification\fP +.B method +Currently only \fBtoken\fP and \fBapprole\fP auth types are supported. +Defaults to \fBtoken\fP\&. .sp -New in version 2018.3.0. +AppRole is the preferred way to authenticate with Vault as it provides +some advanced options to control the authentication process. +Please see the \fI\%Vault documentation\fP +for more information. +.TP +.B role_id +The role ID of the AppRole. Required if \fBauth:method\fP == \fBapprole\fP\&. +.sp +Changed in version 3007.0: In addition to a plain string, this can also be specified as a +dictionary that includes \fBwrap_info\fP, i.e. the return payload +of a wrapping request. .TP -.B namespaces -Optional Vault Namespace. Used with Vault enterprice +.B secret_id +The secret ID of the AppRole. +Only required if the configured AppRole requires it. .sp -For detail please see: -\fI\%https://www.vaultproject.io/docs/enterprise/namespaces\fP -.sp -New in version 3004. +Changed in version 3007.0: In addition to a plain string, this can also be specified as a +dictionary that includes \fBwrap_info\fP, i.e. the return payload +of a wrapping request. .TP -.B role_name -Role name for minion tokens created. If omitted, minion tokens will be -created without any role, thus being able to inherit any master token -policy (including token creation capabilities). Optional. -.sp -For details please see: -\fI\%https://www.vaultproject.io/api/auth/token/index.html#create\-token\fP -.sp -Example configuration: -\fI\%https://www.nomadproject.io/docs/vault\-integration/index.html#vault\-token\-role\-configuration\fP -.TP -.B auth -Currently only token and approle auth types are supported. Required. -.sp -Approle is the preferred way to authenticate with Vault as it provide -some advanced options to control authentication process. -Please visit Vault documentation for more info: -\fI\%https://www.vaultproject.io/docs/auth/approle.html\fP +.B token +Token to authenticate to Vault with. Required if \fBauth:method\fP == \fBtoken\fP\&. .sp The token must be able to create tokens with the policies that should be assigned to minions. @@ -305777,10 +298360,12 @@ config example: .nf .ft C vault: - url: https://vault.service.domain:8200 auth: method: token token: sdb://osenv/VAULT_TOKEN + server: + url: https://vault.service.domain:8200 + osenv: driver: env .ft P @@ -305800,47 +298385,303 @@ export VAULT_TOKEN=11111111\-1111\-1111\-1111\-1111111111111 .UNINDENT .UNINDENT .sp -Configuration keys \fBuses\fP or \fBttl\fP may also be specified under \fBauth\fP -to configure the tokens generated on behalf of minions to be reused for the -defined number of uses or length of time in seconds. These settings may also be configured -on the minion when \fBallow_minion_override\fP is set to \fBTrue\fP in the master -config. +Changed in version 3007.0: In addition to a plain string, this can also be specified as a +dictionary that includes \fBwrap_info\fP, i.e. the return payload +of a wrapping request. + +.TP +.B token_lifecycle +Token renewal settings. .sp -Defining \fBuses\fP will cause the salt master to generate a token with that number of uses rather -than a single use token. This multi\-use token will be cached on the minion. The type of minion -cache can be specified with \fBtoken_backend: session\fP or \fBtoken_backend: disk\fP\&. The value of -\fBsession\fP is the default, and will store the vault information in memory only for that session. -The value of \fBdisk\fP will write to an on disk file, and persist between state runs (most -helpful for multi\-use tokens). +\fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 +This setting can be specified inside a minion\(aqs configuration as well +and will override the master\(aqs default for the minion. .sp -.nf -.ft C -vault: - auth: - method: token - token: xxxxxx - uses: 10 - ttl: 43200 - allow_minion_override: True - token_backend: disk +Token lifecycle settings have significancy for any authentication method, +not just \fBtoken\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBminimum_ttl\fP specifies the time (in seconds or as a time string like \fB24h\fP) +an in\-use token should be valid for. If the current validity period is less +than this and the token is renewable, a renewal will be attempted. If it is +not renewable or a renewal does not extend the ttl beyond the specified minimum, +a new token will be generated. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Since leases like database credentials are tied to a token, setting this to +a much higher value than the default can be necessary, depending on your +specific use case and configuration. +.UNINDENT +.UNINDENT +.sp +\fBrenew_increment\fP specifies the amount of time the token\(aqs validity should +be requested to be renewed for when renewing a token. When unset, will extend +the token\(aqs validity by its default ttl. +Set this to \fBfalse\fP to disable token renewals. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The Vault server is allowed to disregard this request. +.UNINDENT +.UNINDENT +.UNINDENT +.SS \fBcache\fP +.sp +Configures token/lease and metadata cache (for KV secrets) on all hosts +as well as configuration cache on minions that receive issued credentials. +.INDENT 0.0 +.TP +.B backend +Changed in version 3007.0: This used to be found in \fBauth:token_backend\fP\&. - .. versionchanged:: 3001 -.ft P -.fi +.sp +The cache backend in use. Defaults to \fBsession\fP, which will store the +Vault configuration in memory only for that specific Salt run. +\fBdisk\fP/\fBfile\fP/\fBlocalfs\fP will force using the localfs driver, regardless +of configured minion data cache. +Setting this to anything else will use the default configured cache for +minion data (\fI\%cache\fP), by default the local filesystem +as well. +.TP +.B clear_attempt_revocation +New in version 3007.0. + +.sp +When flushing still valid cached tokens and leases, attempt to have them +revoked after a (short) delay. Defaults to \fB60\fP\&. +Set this to false to disable revocation (not recommended). +.TP +.B clear_on_unauthorized +New in version 3007.0. + +.sp +When encountering an \fBUnauthorized\fP response with an otherwise valid token, +flush the cache and request new credentials. Defaults to true. +If your policies are relatively stable, disabling this will prevent +a lot of unnecessary overhead, with the tradeoff that once they change, +you might have to clear the cache manually or wait for the token to expire. +.TP +.B config +New in version 3007.0. + +.sp +The time in seconds to cache queried configuration from the master. +Defaults to \fB3600\fP (one hour). Set this to \fBnull\fP to disable +cache expiration. Changed \fBserver\fP configuration on the master will +still be recognized, but changes in \fBauth\fP and \fBcache\fP will need +a manual update using \fBvault.update_config\fP or cache clearance +using \fBvault.clear_cache\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Expiring the configuration will also clear cached authentication +credentials and leases. .UNINDENT .UNINDENT .TP -.B policies -Policies that are assigned to minions when requesting a token. These -can either be static, eg \fBsaltstack/minions\fP, or templated with grain -values, eg \fBmy\-policies/{grains[os]}\fP\&. \fB{minion}\fP is shorthand for -\fBgrains[id]\fP, eg \fBsaltstack/minion/{minion}\fP\&. +.B expire_events +New in version 3007.0. + .sp -New in version 3006.0: Policies can be templated with pillar values as well: \fBsalt_role_{pillar[roles]}\fP +Fire an event when the session cache containing leases is cleared +(\fBvault/cache//clear\fP) or cached leases have expired +(\fBvault/lease//expire\fP). +A reactor can be employed to ensure fresh leases are issued. +Defaults to false. +.TP +.B kv_metadata +New in version 3007.0. + +.sp +The time in seconds to cache KV metadata used to determine if a path +is using version 1/2 for. Defaults to \fBconnection\fP, which will clear +the metadata cache once a new configuration is requested from the +master. Setting this to \fBnull\fP will keep the information +indefinitely until the cache is cleared manually using +\fBvault.clear_cache\fP with \fBconnection=false\fP\&. +.TP +.B secret +New in version 3007.0. + +.sp +The time in seconds to cache tokens/secret IDs for. Defaults to \fBttl\fP, +which caches the secret for as long as it is valid, unless a new configuration +is requested from the master. +.UNINDENT +.SS \fBissue\fP +.sp +Configures authentication data issued by the master to minions. +.INDENT 0.0 +.TP +.B type +New in version 3007.0. + +.sp +The type of authentication to issue to minions. Can be \fBtoken\fP or \fBapprole\fP\&. +Defaults to \fBtoken\fP\&. +.sp +To be able to issue AppRoles to minions, the master needs to be able to +create new AppRoles on the configured auth mount (see policy example above). +It is strongly encouraged to create a separate mount dedicated to minions. +.TP +.B approle +New in version 3007.0. + +.sp +Configuration regarding issued AppRoles. +.sp +\fBmount\fP specifies the name of the auth mount the master manages. +Defaults to \fBsalt\-minions\fP\&. This mount should be exclusively dedicated +to the Salt master. +.sp +\fBparams\fP configures the AppRole the master creates for minions. See the +\fI\%Vault AppRole API docs\fP +for details. If you update these params, you can update the minion AppRoles +manually using the vault runner: \fBsalt\-run vault.sync_approles\fP, but they +will be updated automatically during a request by a minion as well. +.TP +.B token +New in version 3007.0. + +.sp +Configuration regarding issued tokens. +.sp +\fBrole_name\fP specifies the role name for minion tokens created. Optional. +.sp +Changed in version 3007.0: This used to be found in \fBrole_name\fP\&. + +.sp +If omitted, minion tokens will be created without any role, thus being able +to inherit any master token policy (including token creation capabilities). +.sp +Example configuration: +\fI\%https://www.nomadproject.io/docs/vault\-integration/index.html#vault\-token\-role\-configuration\fP +.sp +\fBparams\fP configures the tokens the master issues to minions. +.sp +Changed in version 3007.0: This used to be found in \fBauth:ttl\fP and \fBauth:uses\fP\&. +The possible parameters were synchronized with the Vault nomenclature: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBttl\fP previously was mapped to \fBexplicit_max_ttl\fP on Vault, not \fBttl\fP\&. +For the same behavior as before, you will need to set \fBexplicit_max_ttl\fP now. +.IP \(bu 2 +\fBuses\fP is now called \fBnum_uses\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT + +.sp +See the \fI\%Vault token API docs\fP +for details. To make full use of multi\-use tokens, you should configure a cache +that survives a single session (e.g. \fBdisk\fP). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If unset, the master issues single\-use tokens to minions, which can be quite expensive. +.UNINDENT +.UNINDENT +.TP +.B allow_minion_override_params +Changed in version 3007.0: This used to be found in \fBauth:allow_minion_override\fP\&. + +.sp +Whether to allow minions to request to override parameters for issuing credentials. +See \fBissue_params\fP below. +.TP +.B wrap +New in version 3007.0. + +.sp +The time a minion has to unwrap a wrapped secret issued by the master. +Set this to false to disable wrapping, otherwise a time string like \fB30s\fP +can be used. Defaults to \fB30s\fP\&. +.UNINDENT +.SS \fBkeys\fP +.INDENT 0.0 +.INDENT 3.5 +List of keys to use to unseal vault server with the \fBvault.unseal\fP runner. +.UNINDENT +.UNINDENT +.SS \fBmetadata\fP +.sp +New in version 3007.0. + +.sp +Configures metadata for the issued entities/secrets. Values have to be strings +and can be templated with the following variables: +.INDENT 0.0 +.IP \(bu 2 +\fB{jid}\fP Salt job ID that issued the secret. +.IP \(bu 2 +\fB{minion}\fP The minion ID the secret was issued for. +.IP \(bu 2 +\fB{user}\fP The user the Salt daemon issuing the secret was running as. +.IP \(bu 2 +\fB{pillar[]}\fP A minion pillar value that does not depend on Vault. +.IP \(bu 2 +\fB{grains[]}\fP A minion grain value. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Values have to be strings, hence templated variables that resolve to lists +will be concatenated to a lexicographically sorted comma\-separated list +(Python \fBlist.sort()\fP). +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B entity +Configures the metadata associated with the minion entity inside Vault. +Entities are only created when issuing AppRoles to minions. +.TP +.B secret +Configures the metadata associated with issued tokens/secret IDs. They +are logged in plaintext to the Vault audit log. +.UNINDENT +.SS \fBpolicies\fP +.sp +Changed in version 3007.0: This used to specify the list of policies associated with a minion token only. +The equivalent is found in \fBassign\fP\&. + +.INDENT 0.0 +.TP +.B assign +List of policies that are assigned to issued minion authentication data, +either token or AppRole. +.sp +They can be static strings or string templates with +.INDENT 7.0 +.IP \(bu 2 +\fB{minion}\fP The minion ID. +.IP \(bu 2 +\fB{pillar[]}\fP A minion pillar value. +.IP \(bu 2 +\fB{grains[]}\fP A minion grain value. +.UNINDENT +.sp +For pillar and grain values, lists are expanded, so \fBsalt_role_{pillar[roles]}\fP +with \fB[a, b]\fP results in \fBsalt_role_a\fP and \fBsalt_role_b\fP to be issued. +.sp +Defaults to \fB[saltstack/minions, saltstack/{minion}]\fP\&. +.sp +New in version 3006.0: Policies can be templated with pillar values as well: \fBsalt_role_{pillar[roles]}\fP\&. Make sure to only reference pillars that are not sourced from Vault since the latter -ones might be unavailable during policy rendering. +ones might be unavailable during policy rendering. If you use the Vault +integration in one of your pillar \fBsls\fP files, all values from that file +will be absent during policy rendering, even the ones that do not depend on Vault. .sp \fBIMPORTANT:\fP @@ -305851,26 +298692,6 @@ everything except \fBgrains[id]\fP is minion\-controlled. .UNINDENT .UNINDENT .sp -If a template contains a grain which evaluates to a list, it will be -expanded into multiple policies. For example, given the template -\fBsaltstack/by\-role/{grains[roles]}\fP, and a minion having these grains: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -grains: - roles: - \- web - \- database -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The minion will have the policies \fBsaltstack/by\-role/web\fP and -\fBsaltstack/by\-role/database\fP\&. -.sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 @@ -305880,67 +298701,186 @@ throw an exception. Strings and numbers are examples of types which work well. .UNINDENT .UNINDENT -.sp -Optional. If policies is not configured, \fBsaltstack/minions\fP and -\fBsaltstack/{minion}\fP are used as defaults. .TP -.B policies_refresh_pillar -Whether to refresh the pillar data when rendering templated policies. -When unset (=null/None), will only refresh when the cached data -is unavailable, boolean values force one behavior always. +.B cache_time +New in version 3007.0. + +.sp +Number of seconds compiled templated policies are cached on the master. +This is important when using pillar values in templates, since compiling +the pillar is an expensive operation. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Using cached pillar data only (policies_refresh_pillar=False) -might cause the policies to be out of sync. If there is no cached pillar -data available for the minion, pillar templates will fail to render at all. +Only effective when issuing tokens to minions. Token policies +need to be compiled every time a token is requested, while AppRole\-associated +policies are written to Vault configuration the first time authentication data +is requested (they can be refreshed on demand by running +\fBsalt\-run vault.sync_approles\fP). +.sp +They will also be refreshed in case other issuance parameters are changed +(such as uses/ttl), either on the master or the minion +(if allow_minion_override_params is True). +.UNINDENT +.UNINDENT +.TP +.B refresh_pillar +New in version 3007.0. + +.sp +Whether to refresh the minion pillar when compiling templated policies +that contain pillar variables. +Only effective when issuing tokens to minions (see note on cache_time above). +.INDENT 7.0 +.IP \(bu 2 +\fBnull\fP (default) only compiles the pillar when no cached pillar is found. +.IP \(bu 2 +\fBfalse\fP never compiles the pillar. This means templated policies that +contain pillar values are skipped if no cached pillar is found. +.IP \(bu 2 +\fBtrue\fP always compiles the pillar. This can cause additional strain +on the master since the compilation is costly. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Hardcoded to True when issuing AppRoles. +.sp +Using cached pillar data only (refresh_pillar=False) might cause the policies +to be out of sync. If there is no cached pillar data available for the minion, +pillar templates will fail to render at all. .sp If you use pillar values for templating policies and do not disable refreshing pillar data, make sure the relevant values are not sourced from Vault (ext_pillar, sdb) or from a pillar sls file that uses the vault -execution module. Although this will often work when cached pillar data is +execution/sdb module. Although this will often work when cached pillar data is available, if the master needs to compile the pillar data during policy rendering, all Vault modules will be broken to prevent an infinite loop. .UNINDENT .UNINDENT +.UNINDENT +.SS \fBserver\fP +.sp +Changed in version 3007.0: The values found in here were found in the \fBvault\fP root namespace previously. + +.sp +Configures Vault server details. +.INDENT 0.0 .TP -.B policies_cache_time -Policy computation can be heavy in case pillar data is used in templated policies and -it has not been cached. Therefore, a short\-lived cache specifically for rendered policies -is used. This specifies the expiration timeout in seconds. Defaults to 60. +.B url +URL of your Vault installation. Required. .TP -.B keys -List of keys to use to unseal vault server with the vault.unseal runner. +.B verify +Configures certificate verification behavior when issuing requests to the +Vault server. If unset, requests will use the CA certificates bundled with \fBcertifi\fP\&. +.sp +For details, please see \fI\%the requests documentation\fP\&. +.sp +New in version 2018.3.0. + +.sp +Changed in version 3007.0: Minions again respect the master configuration value, which was changed +implicitly in v3001. If this value is set in the minion configuration +as well, it will take precedence. +.sp +In addition, this value can now be set to a PEM\-encoded CA certificate +to use as the sole trust anchor for certificate chain verification. + .TP -.B config_location +.B namespace +Optional Vault namespace. Used with Vault Enterprise. +.sp +For details please see: +\fI\%https://www.vaultproject.io/docs/enterprise/namespaces\fP +.sp +New in version 3004. + +.UNINDENT +.sp +Minion configuration (optional): +.SS \fBconfig_location\fP +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.INDENT 3.5 Where to get the connection details for calling vault. By default, vault will try to determine if it needs to request the connection details from the master or from the local config. This optional option will force vault to use the connection details from the master or the local config. Can only be either \fBmaster\fP or \fBlocal\fP\&. -.INDENT 7.0 -.INDENT 3.5 +.UNINDENT +.UNINDENT +.sp New in version 3006.0. .UNINDENT +.UNINDENT +.SS \fBissue_params\fP +.INDENT 0.0 +.INDENT 3.5 +Request overrides for token/AppRole issuance. This needs to be allowed +on the master by setting \fBissue:allow_minion_override_params\fP to true. +See the master configuration \fBissue:token:params\fP or \fBissue:approle:params\fP +for reference. +.sp +Changed in version 3007.0: For token issuance, this used to be found in \fBauth:ttl\fP and \fBauth:uses\fP\&. +Mind that the parameter names have been synchronized with Vault, see notes +above (TLDR: \fBttl\fP => \fBexplicit_max_ttl\fP, \fBuses\fP => \fBnum_uses\fP\&. + .UNINDENT .UNINDENT .sp -Add this segment to the master configuration file, or -/etc/salt/master.d/peer_run.conf: +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBauth:token_lifecycle\fP and \fBserver:verify\fP can be set on the minion as well. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.clear_cache(connection=True, session=False) +New in version 3007.0. + +.sp +Delete Vault caches. Will ensure the current token and associated leases +are revoked by default. +.sp +The cache is organized in a hierarchy: \fB/vault/connection/session/leases\fP\&. +(\fIitalics\fP mark data that is only cached when receiving configuration from a master) +.sp +\fBconnection\fP contains KV metadata (by default), \fIconfiguration\fP and \fI(AppRole) auth credentials\fP\&. +\fBsession\fP contains the currently active token. +\fBleases\fP contains leases issued to the currently active token like database credentials. +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -peer_run: - .*: - \- vault.generate_token +salt \(aq*\(aq vault.clear_cache +salt \(aq*\(aq vault.clear_cache session=True .ft P .fi .UNINDENT .UNINDENT +.INDENT 7.0 +.TP +.B connection +Only clear the cached data scoped to a connection. This includes +configuration, auth credentials, the currently active auth token +as well as leases and KV metadata (by default). Defaults to true. +Set this to false to clear all Vault caches. +.TP +.B session +Only clear the cached data scoped to a session. This only includes +leases and the currently active auth token, but not configuration +or (AppRole) auth credentials. Defaults to false. +Setting this to true will keep the connection cache, regardless +of \fBconnection\fP\&. +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -305948,7 +298888,10 @@ peer_run: Changed in version 3001. .sp -Delete minion Vault token cache file +Changed in version 3007.0: This is now an alias for \fBvault.clear_cache\fP with \fBconnection=True\fP\&. + +.sp +Delete minion Vault token cache. .sp CLI Example: .INDENT 7.0 @@ -305964,8 +298907,9 @@ salt \(aq*\(aq vault.clear_token_cache .UNINDENT .INDENT 0.0 .TP -.B salt.modules.vault.delete_secret(path) -Delete secret at the path in vault. The vault policy used must allow this. +.B salt.modules.vault.delete_secret(path, *args) +Delete secret at . The vault policy used must allow this. +If is on KV v2, the secret will be soft\-deleted. .sp CLI Example: .INDENT 7.0 @@ -305974,10 +298918,44 @@ CLI Example: .nf .ft C salt \(aq*\(aq vault.delete_secret \(dqsecret/my/secret\(dq +salt \(aq*\(aq vault.delete_secret \(dqsecret/my/secret\(dq 1 2 3 .ft P .fi .UNINDENT .UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dq/\(dq { + capabilities = [\(dqdelete\(dq] +} + +# or KV v2 +path \(dq/data/\(dq { + capabilities = [\(dqdelete\(dq] +} + +# KV v2 versions +path \(dq/delete/\(dq { + capabilities = [\(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.UNINDENT +.sp +New in version 3007.0: For KV v2, you can specify versions to soft\-delete as supplemental +positional arguments. + .UNINDENT .INDENT 0.0 .TP @@ -305985,8 +298963,8 @@ salt \(aq*\(aq vault.delete_secret \(dqsecret/my/secret\(dq New in version 3001. .sp -Destroy specified secret version at the path in vault. The vault policy -used must allow this. Only supported on Vault KV version 2 +Destroy specified secret versions . The vault policy +used must allow this. Only supported on Vault KV version 2. .sp CLI Example: .INDENT 7.0 @@ -305999,17 +298977,60 @@ salt \(aq*\(aq vault.destroy_secret \(dqsecret/my/secret\(dq 1 2 .fi .UNINDENT .UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dq/destroy/\(dq { + capabilities = [\(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.UNINDENT +.sp +You can specify versions to destroy as supplemental positional arguments. +At least one is required. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.vault.list_secrets(path, default=) +.B salt.modules.vault.get_server_config() +New in version 3007.0. + +.sp +Return the server connection configuration that\(aqs currently in use by Salt. +Contains \fBurl\fP, \fBverify\fP and \fBnamespace\fP\&. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.get_server_config +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.list_secrets(path, default=, keys_only=False) +List secret keys at . The vault policy used must allow this. +The path should end with a trailing slash. +.sp Changed in version 3001: The \fBdefault\fP argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided. -.sp -List secret keys at the path in vault. The vault policy used must allow this. -The path should end with a trailing slash. .sp CLI Example: .INDENT 7.0 @@ -306022,59 +299043,415 @@ salt \(aq*\(aq vault.list_secrets \(dqsecret/my/\(dq .fi .UNINDENT .UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dq/\(dq { + capabilities = [\(dqlist\(dq] +} + +# or KV v2 +path \(dq/metadata/\(dq { + capabilities = [\(dqlist\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.TP +.B default +New in version 3001. + +.sp +When the path is not found, an exception will be raised, unless a default +is provided here. +.TP +.B keys_only +New in version 3007.0. + +.sp +This function used to return a dictionary like \fB{\(dqkeys\(dq: [\(dqsome/\(dq, \(dqsome/key\(dq]}\fP\&. +Setting this to True will only return the list of keys. +For backwards\-compatibility reasons, this defaults to False. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.patch_secret(path, **kwargs) +Patch secret dataset at . Fields are specified as arbitrary keyword arguments. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This works even for older Vault versions, KV v1 and with missing +\fBpatch\fP capability, but will use more than one request to simulate +the functionality by issuing a read and update request. +.sp +For proper, single\-request patching, requires versions of KV v2 that +support the \fBpatch\fP capability and the \fBpatch\fP capability to be available +for the path. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This uses JSON Merge Patch format internally. +Keys set to \fBnull\fP (JSON/YAML)/\fBNone\fP (Python) will be deleted. +.UNINDENT +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.patch_secret \(dqsecret/my/secret\(dq password=\(dqbaz\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Proper patching +path \(dq/data/\(dq { + capabilities = [\(dqpatch\(dq] +} + +# OR (!), for older KV v2 setups: + +path \(dq/data/\(dq { + capabilities = [\(dqread\(dq, \(dqupdate\(dq] +} + +# OR (!), for KV v1 setups: + +path \(dq/\(dq { + capabilities = [\(dqread\(dq, \(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.policies_list() +New in version 3007.0. + +.sp +List all ACL policies. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.policies_list +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqsys/policy\(dq { + capabilities = [\(dqread\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.policy_delete(policy) +New in version 3007.0. + +.sp +Delete an ACL policy. Returns False if the policy did not exist. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.policy_delete salt_minion +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqsys/policy/\(dq { + capabilities = [\(dqdelete\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B policy +The name of the policy to delete. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.policy_fetch(policy) +New in version 3007.0. + +.sp +Fetch the rules associated with an ACL policy. Returns None if the policy +does not exist. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.policy_fetch salt_minion +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqsys/policy/\(dq { + capabilities = [\(dqread\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B policy +The name of the policy to fetch. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.policy_write(policy, rules) +New in version 3007.0. + +.sp +Create or update an ACL policy. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.policy_write salt_minion \(aqpath \(dqsecret/foo\(dq {...}\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqsys/policy/\(dq { + capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B policy +The name of the policy to create/update. +.TP +.B rules +Rules to write, formatted as in\-line HCL. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.query(method, endpoint, payload=None) +New in version 3007.0. + +.sp +Issue arbitrary queries against the Vault API. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.query GET auth/token/lookup\-self +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: Depends on the query. +.sp +You can ask the vault CLI to output the necessary policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +vault read \-output\-policy auth/token/lookup\-self +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B method +HTTP method to use. +.TP +.B endpoint +Vault API endpoint to issue the request against. Do not include \fB/v1/\fP\&. +.TP +.B payload +Optional dictionary to use as JSON payload. +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.read_secret(path, key=None, metadata=False, default=) +Return the value of at in vault, or entire secret. +.sp Changed in version 3001: The \fBdefault\fP argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided. .sp -Return the value of key at path in vault, or entire secret +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq vault.read_secret salt/kv/secret +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dq/\(dq { + capabilities = [\(dqread\(dq] +} + +# or KV v2 +path \(dq/data/\(dq { + capabilities = [\(dqread\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT .INDENT 7.0 .TP -.B Parameters -\fBmetadata\fP \-\- -.sp -Optional \- If using KV v2 backend, display full results, including metadata -.sp +.B path +The path to the secret, including mount. +.TP +.B key +The data field at to read. If unspecified, returns the +whole dataset. +.TP +.B metadata New in version 3001. - -.UNINDENT .sp -Jinja Example: +If using KV v2 backend, display full results, including metadata. +Defaults to False. +.TP +.B default +New in version 3001. + +.sp +When the path or path/key combination is not found, an exception will +be raised, unless a default is provided here. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.vault.update_config(keep_session=False) +New in version 3007.0. + +.sp +Attempt to update the cached configuration without clearing the +currently active Vault session. +.sp +CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C -my\-secret: {{ salt[\(aqvault\(aq].read_secret(\(aqsecret/my/secret\(aq, \(aqsome\-key\(aq) }} - -{{ salt[\(aqvault\(aq].read_secret(\(aq/secret/my/secret\(aq, \(aqsome\-key\(aq, metadata=True)[\(aqdata\(aq] }} +salt \(aq*\(aq vault.update_config .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{% set supersecret = salt[\(aqvault\(aq].read_secret(\(aqsecret/my/secret\(aq) %} -secrets: - first: {{ supersecret.first }} - second: {{ supersecret.second }} -.ft P -.fi -.UNINDENT +.TP +.B keep_session +Only update configuration that can be updated without +creating a new login session. +If this is false, still tries to keep the active session, +but might clear it if the server configuration has changed +significantly. +Defaults to False. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.write_raw(path, raw) -Set raw data at the path in vault. The vault policy used must allow this. +Set raw data at . The vault policy used must allow this. .sp CLI Example: .INDENT 7.0 @@ -306087,11 +299464,22 @@ salt \(aq*\(aq vault.write_raw \(dqsecret/my/secret\(dq \(aq{\(dquser\(dq:\(dqfo .fi .UNINDENT .UNINDENT +.sp +Required policy: see write_secret +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.TP +.B raw +Secret data to write to . Has to be a mapping. +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.vault.write_secret(path, **kwargs) -Set secret at the path in vault. The vault policy used must allow this. +Set secret dataset at . The vault policy used must allow this. +Fields are specified as arbitrary keyword arguments. .sp CLI Example: .INDENT 7.0 @@ -306104,6 +299492,30 @@ salt \(aq*\(aq vault.write_secret \(dqsecret/my/secret\(dq user=\(dqfoo\(dq pass .fi .UNINDENT .UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dq/\(dq { + capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] +} + +# or KV v2 +path \(dq/data/\(dq { + capabilities = [\(dqcreate\(dq, \(dqupdate\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B path +The path to the secret, including mount. +.UNINDENT .UNINDENT .SS salt.modules.vbox_guest .sp @@ -318434,6 +311846,348 @@ salt \(aq*\(aq webutil.verify /etc/httpd/htpasswd larry maybepassword opts=ns .UNINDENT .UNINDENT .UNINDENT +.SS salt.modules.win_appx +.SS Manage provisioned apps +.sp +New in version 3007.0. + +.sp +Provisioned apps are part of the image and are installed for every user the +first time the user logs on. Provisioned apps are also updated and sometimes +reinstalled when the system is updated. +.sp +Apps removed with this module will remove the app for all users and deprovision +the app. Deprovisioned apps will neither be installed for new users nor will +they be upgraded. +.sp +An app removed with this module can only be re\-provisioned on the machine, but +it can\(aqt be re\-installed for all users. Also, once a package has been +deprovisioned, the only way to reinstall it is to download the package. This is +difficult. The steps are outlined below: +.INDENT 0.0 +.IP 1. 3 +.INDENT 3.0 +.TP +.B Obtain the Microsoft Store URL for the app: +.INDENT 7.0 +.IP \(bu 2 +Open the page for the app in the Microsoft Store +.IP \(bu 2 +Click the share button and copy the URL +.UNINDENT +.UNINDENT +.IP 2. 3 +.INDENT 3.0 +.TP +.B Look up the packages on \fI\%https://store.rg\-adguard.net/\fP: +.INDENT 7.0 +.IP \(bu 2 +Ensure \fBURL (link)\fP is selected in the first dropdown +.IP \(bu 2 +Paste the URL in the search field +.IP \(bu 2 +Ensure Retail is selected in the 2nd dropdown +.IP \(bu 2 +Click the checkmark button +.UNINDENT +.UNINDENT +.UNINDENT +.sp +This should return a list of URLs for the package and all dependencies for all +architectures. Download the package and all dependencies for your system +architecture. These will usually have one of the following file extensions: +.INDENT 0.0 +.IP \(bu 2 +\fB\&.appx\fP +.IP \(bu 2 +\fB\&.appxbundle\fP +.IP \(bu 2 +\fB\&.msix\fP +.IP \(bu 2 +\fB\&.msixbundle\fP +.UNINDENT +.sp +Dependencies will need to be installed first. +.sp +Not all packages can be found this way, but it seems like most of them can. +.sp +Use the \fBappx.install\fP function to provision the new app. +.INDENT 0.0 +.TP +.B salt.modules.win_appx.install(package) +This function uses \fBdism\fP to provision a package. This means that it will +be made a part of the online image and added to new users on the system. If +a package has dependencies, those must be installed first. +.sp +If a package installed using this function has been deprovisioned +previously, the registry entry marking it as deprovisioned will be removed. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +There is no \fBappx.present\fP state. Instead, use the +\fBdism.provisioned_package_installed\fP state. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B Parameters +\fBpackage\fP (\fI\%str\fP) \-\- +.sp +The full path to the package to install. Can be one of the +following: +.INDENT 7.0 +.IP \(bu 2 +\fB\&.appx\fP or \fB\&.appxbundle\fP +.IP \(bu 2 +\fB\&.msix\fP or \fB\&.msixbundle\fP +.IP \(bu 2 +\fB\&.ppkg\fP +.UNINDENT + +.TP +.B Returns +\fBTrue\fP if successful, otherwise \fBFalse\fP +.TP +.B Return type +\fI\%bool\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(dq*\(dq appx.install \(dqC:\eTemp\eMicrosoft.ZuneMusic.msixbundle\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_appx.list_(query=None, field=\(aqName\(aq, include_store=False, frameworks=False, bundles=True) +Get a list of Microsoft Store packages installed on the system. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBquery\fP (\fI\%str\fP) \-\- +.sp +The query string to use to filter packages to be listed. The string +can match multiple packages. \fBNone\fP will return all packages. Here +are some example strings: +.INDENT 2.0 +.IP \(bu 2 +\fB*teams*\fP \- Returns Microsoft Teams +.IP \(bu 2 +\fB*zune*\fP \- Returns Windows Media Player and ZuneVideo +.IP \(bu 2 +\fB*zuneMusic*\fP \- Only returns Windows Media Player +.IP \(bu 2 +\fB*xbox*\fP \- Returns all xbox packages, there are 5 by default +.IP \(bu 2 +\fB*\fP \- Returns everything but the Microsoft Store, unless +\fBinclude_store=True\fP +.UNINDENT + +.IP \(bu 2 +\fBfield\fP (\fI\%str\fP) \-\- +.sp +This function returns a list of packages on the system. It can +display a short name or a full name. If \fBNone\fP is passed, a +dictionary will be returned with some common fields. The default is +\fBName\fP\&. Valid options are any fields returned by the powershell +command \fBGet\-AppxPackage\fP\&. Here are some useful fields: +.INDENT 2.0 +.IP \(bu 2 +Name +.IP \(bu 2 +Version +.IP \(bu 2 +PackageFullName +.IP \(bu 2 +PackageFamilyName +.UNINDENT + +.IP \(bu 2 +\fBinclude_store\fP (\fI\%bool\fP) \-\- Include the Microsoft Store in the results. Default is \fBFalse\fP +.IP \(bu 2 +\fBframeworks\fP (\fI\%bool\fP) \-\- Include frameworks in the results. Default is \fBFalse\fP +.IP \(bu 2 +\fBbundles\fP (\fI\%bool\fP) \-\- If \fBTrue\fP, this will return application bundles only. If +\fBFalse\fP, this will return individual packages only, even if they +are part of a bundle. +.UNINDENT +.TP +.B Returns +A list of packages ordered by the string passed in field +list: A list of dictionaries of package information if field is \fBNone\fP +.TP +.B Return type +\fI\%list\fP +.TP +.B Raises +\fI\%CommandExecutionError\fP \-\- If an error is encountered retrieving packages +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +# List installed apps that contain the word \(dqcandy\(dq +salt \(aq*\(aq appx.list *candy* + +# Return more information about the package +salt \(aq*\(aq appx.list *candy* field=None + +# List all installed apps, including the Microsoft Store +salt \(aq*\(aq appx.list include_store=True + +# List all installed apps, including frameworks +salt \(aq*\(aq appx.list frameworks=True + +# List all installed apps that are bundles +salt \(aq*\(aq appx.list bundles=True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_appx.list_deprovisioned(query=None) +When an app is deprovisioned, a registry key is created that will keep it +from being reinstalled during a major system update. This function returns a +list of keys for apps that have been deprovisioned. +.INDENT 7.0 +.TP +.B Parameters +\fBquery\fP (\fI\%str\fP) \-\- +.sp +The query string to use to filter packages to be listed. The string +can match multiple packages. \fBNone\fP will return all packages. Here +are some example strings: +.INDENT 7.0 +.IP \(bu 2 +\fB*teams*\fP \- Returns Microsoft Teams +.IP \(bu 2 +\fB*zune*\fP \- Returns Windows Media Player and ZuneVideo +.IP \(bu 2 +\fB*zuneMusic*\fP \- Only returns Windows Media Player +.IP \(bu 2 +\fB*xbox*\fP \- Returns all xbox packages, there are 5 by default +.IP \(bu 2 +\fB*\fP \- Returns everything but the Microsoft Store, unless +\fBinclude_store=True\fP +.UNINDENT + +.TP +.B Returns +A list of packages matching the query criteria +.TP +.B Return type +\fI\%list\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(dq*\(dq appx.list_deprovisioned *zune* +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_appx.remove(query=None, include_store=False, frameworks=False, deprovision_only=False) +Removes Microsoft Store packages from the system. If the package is part of +a bundle, the entire bundle will be removed. +.sp +This function removes the package for all users on the system. It also +deprovisions the package so that it isn\(aqt re\-installed by later system +updates. To only deprovision a package and not remove it for all users, set +\fBdeprovision_only=True\fP\&. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBquery\fP (\fI\%str\fP) \-\- +.sp +The query string to use to select the packages to be removed. If the +string matches multiple packages, they will all be removed. Here are +some example strings: +.INDENT 2.0 +.IP \(bu 2 +\fB*teams*\fP \- Remove Microsoft Teams +.IP \(bu 2 +\fB*zune*\fP \- Remove Windows Media Player and ZuneVideo +.IP \(bu 2 +\fB*zuneMusic*\fP \- Only remove Windows Media Player +.IP \(bu 2 +\fB*xbox*\fP \- Remove all xbox packages, there are 5 by default +.IP \(bu 2 +\fB*\fP \- Remove everything but the Microsoft Store, unless +\fBinclude_store=True\fP +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 2.0 +.INDENT 3.5 +Use the \fBappx.list\fP function to make sure your query is +returning what you expect. Then use the same query to remove +those packages +.UNINDENT +.UNINDENT + +.IP \(bu 2 +\fBinclude_store\fP (\fI\%bool\fP) \-\- Include the Microsoft Store in the results of the query to be +removed. Use this with caution. It is difficult to reinstall the +Microsoft Store once it has been removed with this function. Default +is \fBFalse\fP +.IP \(bu 2 +\fBframeworks\fP (\fI\%bool\fP) \-\- Include frameworks in the results of the query to be removed. +Default is \fBFalse\fP +.IP \(bu 2 +\fBdeprovision_only\fP (\fI\%bool\fP) \-\- Only deprovision the package. The package will be removed from the +current user and added to the list of deprovisioned packages. The +package will not be re\-installed in future system updates. New users +of the system will not have the package installed. However, the +package will still be installed for existing users. Default is +\fBFalse\fP +.UNINDENT +.TP +.B Returns +\fBTrue\fP if successful, \fBNone\fP if no packages found +.TP +.B Return type +\fI\%bool\fP +.TP +.B Raises +\fI\%CommandExecutionError\fP \-\- On errors encountered removing the package +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(dq*\(dq appx.remove *candy* +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.modules.win_auditpol .sp A salt module for modifying the audit policies on the machine @@ -319314,6 +313068,64 @@ salt \(aq*\(aq dism.add_package C:\ePackages\epackage.cab .UNINDENT .INDENT 0.0 .TP +.B salt.modules.win_dism.add_provisioned_package(package, image=None, restart=False) +Provision a package using DISM. A provisioned package will install for new +users on the system. It will also be reinstalled on each user if the system +is updated. +.sp +New in version 3007.0. + +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBpackage\fP (\fI\%str\fP) \-\- +.sp +The package to install. Can be one of the following: +.INDENT 2.0 +.IP \(bu 2 +\fB\&.appx\fP or \fB\&.appxbundle\fP +.IP \(bu 2 +\fB\&.msix\fP or \fB\&.msixbundle\fP +.IP \(bu 2 +\fB\&.ppkg\fP +.UNINDENT + +.IP \(bu 2 +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP\&. +.IP \(bu 2 +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the installation. Default is +\fBFalse\fP +.UNINDENT +.TP +.B Returns +A dictionary containing the results of the command +.TP +.B Return type +\fI\%dict\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.appx +salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.appxbundle +salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.msix +salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.msixbundle +salt \(aq*\(aq dism.add_provisioned_package C:\ePackages\epackage.ppkg +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.win_dism.available_capabilities(image=None) List the capabilities available on the system .INDENT 7.0 @@ -319646,7 +313458,40 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq dism. package_info C:\epackages\epackage.cab +salt \(aq*\(aq dism.package_info C:\epackages\epackage.cab +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_dism.provisioned_packages(image=None) +List the packages installed on the system +.sp +New in version 3007.0. + +.INDENT 7.0 +.TP +.B Parameters +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline +Windows image. If \fINone\fP is passed, the running operating system is +targeted. Default is None. +.TP +.B Returns +A list of installed packages +.TP +.B Return type +\fI\%list\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt \(aq*\(aq dism.installed_packages .ft P .fi .UNINDENT @@ -322198,7 +316043,7 @@ salt \(aq*\(aq file.stats /etc/passwd .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_file.symlink(src, link, force=False, atomic=False) +.B salt.modules.win_file.symlink(src, link, force=False, atomic=False, follow_symlinks=True) Create a symbolic link to a file .sp This is only supported with Windows Vista or later and must be executed by @@ -322221,6 +316066,10 @@ If it doesn\(aqt, an error will be raised. .IP \(bu 2 \fBatomic\fP (\fI\%bool\fP) \-\- Use atomic file operations to create the symlink \&.. versionadded:: 3006.0 +.IP \(bu 2 +\fBfollow_symlinks\fP (\fI\%bool\fP) \-\- If set to \fBFalse\fP, use \fBos.path.lexists()\fP for existence checks +instead of \fBos.path.exists()\fP\&. +\&.. versionadded:: 3007.0 .UNINDENT .TP .B Returns @@ -327012,8 +320861,7 @@ salt \(aq*\(aq ntp.set_servers \(aqpool.ntp.org\(aq \(aqus.pool.ntp.org\(aq Manage the Windows System PATH .sp Note that not all Windows applications will rehash the PATH environment variable, -Only the ones that listen to the WM_SETTINGCHANGE message -\fI\%http://support.microsoft.com/kb/104011\fP +Only the ones that listen to the WM_SETTINGCHANGE message. .INDENT 0.0 .TP .B salt.modules.win_path.add(path, index=None, **kwargs) @@ -336964,7 +330812,7 @@ salt \(aq*\(aq wusa.is_installed KB123456 .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_wusa.list() +.B salt.modules.win_wusa.list_() Get a list of updates installed on the machine .INDENT 7.0 .TP @@ -338358,7 +332206,8 @@ peer: .UNINDENT .sp In order for the \fI\%Compound Matcher\fP to work with restricting signing -policies to a subset of minions, in addition calls to \fI\%match.compound\fP +policies to a subset of minions, in addition calls to +\fI\%match.compound_matches\fP by the minion acting as the CA must be permitted: .INDENT 0.0 .INDENT 3.5 @@ -338371,8 +332220,9 @@ peer: .*: \- x509.sign_remote_certificate +peer_run: ca_server: - \- match.compound + \- match.compound_matches .ft P .fi .UNINDENT @@ -338381,11 +332231,29 @@ peer: \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Compound matching in signing policies currently has security tradeoffs since the -CA server queries the requesting minion itself if it matches, not the Salt master. -It is recommended to rely on glob matching only. +When compound match expressions are employed, pillar values can only be matched +literally. This is a barrier to enumeration attacks by the CA server. +.sp +Also note that compound matching requires a minion data cache on the master. +Any certificate signing request will be denied if \fI\%minion_data_cache\fP is +disabled (it is enabled by default). .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Since grain values are controlled by minions, you should avoid using them +to restrict certificate issuance. +.sp +See \fI\%Is Targeting using Grain Data Secure?\fP\&. +.UNINDENT +.UNINDENT +.sp +Changed in version 3007.0: Previously, a compound expression match was validated by the requesting minion +itself via peer publishing, which did not protect from compromised minions. +The new match validation takes place on the master using peer running. + .SS Signing policies .sp In addition, the minion representing the CA needs to have at least one @@ -338461,6 +332329,27 @@ during the first state run. For \fBx509.private_key_managed\fP, the file mode defaults to \fB0400\fP\&. This should be considered a bug fix because writing private keys with world\-readable permissions by default is a security issue. +.IP \(bu 2 +Restricting signing policies using compound match expressions requires peer run +permissions instead of peer publishing permissions: +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# x509, x509_v2 in 3006.* +peer: + ca_server: + \- match.compound + +# x509_v2 from 3007.0 onwards +peer_run: + ca_server: + \- match.compound_matches +.ft P +.fi +.UNINDENT .UNINDENT .sp Note that when a \fBca_server\fP is involved, both peers must use the updated module version. @@ -341059,6 +334948,9 @@ automatically in place of YUM in Fedora 22 and newer. .sp New in version 3003: Support for \fBtdnf\fP on Photon OS. +.sp +New in version 3007.0: Support for \fBdnf5\(ga\fP on Fedora 39 + .INDENT 0.0 .TP .B class salt.modules.yumpkg.AvailablePackages(*args, **kwargs) @@ -343172,6 +337064,14 @@ salt \(aq*\(aq pkg.version_cmp \(aq0.2\-001\(aq \(aq0.2.0.1\-002\(aq .UNINDENT .SS salt.modules.zabbix .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Support for Zabbix .INDENT 0.0 .TP @@ -350761,7 +344661,7 @@ salt \(aq*\(aq pkg.purge pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypperpkg.refresh_db(force=None, root=None) +.B salt.modules.zypperpkg.refresh_db(force=None, root=None, gpgautoimport=False, **kwargs) Trigger a repository refresh by calling \fBzypper refresh\fP\&. Refresh will run with \fB\-\-force\fP if the \(dqforce=True\(dq flag is passed on the CLI or \fBrefreshdb_force\fP is set to \fBtrue\fP in the pillar. The CLI option @@ -350779,6 +344679,20 @@ It will return a dict: .UNINDENT .UNINDENT .INDENT 7.0 +.TP +.B gpgautoimport +False +If set to True, automatically trust and import public GPG key for +the repository. +.sp +New in version 3007.0. + +.TP +.B repos +Refresh just the specified repos +.sp +New in version 3007.0. + .TP .B root operate on a different root directory. @@ -350858,6 +344772,11 @@ salt \(aq*\(aq pkg.remove pkgs=\(aq[\(dqfoo\(dq, \(dqbar\(dq]\(aq .fi .UNINDENT .UNINDENT +.sp +Changed in version 3007.0: Can now remove also PTF packages which require a different handling in the backend. + +.sp +Can now remove also PTF packages which require a different handling in the backend. .UNINDENT .INDENT 0.0 .TP @@ -351317,7 +345236,6 @@ _ T{ \fI\%docker\fP T} T{ -Docker executor module T} _ T{ @@ -351349,6 +345267,14 @@ Directly calls the given function with arguments .UNINDENT .SS salt.executors.docker .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Docker executor module .sp New in version 2019.2.0. @@ -351549,12 +345475,6 @@ center; |l|l|. _ T{ -\fI\%azurefs\fP -T} T{ -The backend for serving files from the Azure blob storage service. -T} -_ -T{ \fI\%gitfs\fP T} T{ Git Fileserver Backend @@ -351591,68 +345511,6 @@ Subversion Fileserver Backend T} _ .TE -.SS salt.fileserver.azurefs -.sp -The backend for serving files from the Azure blob storage service. -.sp -New in version 2015.8.0. - -.sp -To enable, add \fBazurefs\fP to the \fI\%fileserver_backend\fP option in -the Master config file. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -fileserver_backend: - \- azurefs -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Starting in Salt 2018.3.0, this fileserver requires the standalone Azure -Storage SDK for Python. Theoretically any version >= v0.20.0 should work, but -it was developed against the v0.33.0 version. -.sp -Each storage container will be mapped to an environment. By default, containers -will be mapped to the \fBbase\fP environment. You can override this behavior with -the \fBsaltenv\fP configuration option. You can have an unlimited number of -storage containers, and can have a storage container serve multiple -environments, or have multiple storage containers mapped to the same -environment. Normal first\-found rules apply, and storage containers are -searched in the order they are defined. -.sp -You must have either an account_key or a sas_token defined for each container, -if it is private. If you use a sas_token, it must have READ and LIST -permissions. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurefs: - \- account_name: my_storage - account_key: \(aqfNH9cRp0+qVIVYZ+5rnZAhHc9ycOUcJnHtzpfOr0W0sxrtL2KVLuMe1xDfLwmfed+JJInZaEdWVCPHD4d/oqeA==\(aq - container_name: my_container - \- account_name: my_storage - sas_token: \(aqss=b&sp=&sv=2015\-07\-08&sig=cohxXabx8FQdXsSEHyUXMjsSfNH2tZ2OB97Ou44pkRE%3D&srt=co&se=2017\-04\-18T21%3A38%3A01Z\(aq - container_name: my_dev_container - saltenv: dev - \- account_name: my_storage - container_name: my_public_container -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Do not include the leading ? for sas_token if generated from the web -.UNINDENT -.UNINDENT .SS salt.fileserver.gitfs .sp Git Fileserver Backend @@ -352120,12 +345978,6 @@ Grains from cloud metadata servers at 169.254.169.254 T} _ T{ -\fI\%metadata_azure\fP -T} T{ -Grains from cloud metadata servers at 169.254.169.254 in Azure Virtual Machine -T} -_ -T{ \fI\%metadata_gce\fP T} T{ Grains from cloud metadata servers at 169.254.169.254 in google compute engine @@ -352162,6 +346014,12 @@ Simple grain to merge the opts into the grains directly if the grain_opts config T} _ T{ +\fI\%package\fP +T} T{ +Grains for detecting what type of package Salt is using +T} +_ +T{ \fI\%panos\fP T} T{ Generate baseline proxy minion grains for panos hosts. @@ -352675,35 +346533,6 @@ metadata_server_grains: True .TP .B salt.grains.metadata.metadata() .UNINDENT -.SS salt.grains.metadata_azure -.sp -Grains from cloud metadata servers at 169.254.169.254 in Azure Virtual Machine -.sp -New in version 3006.0. - -.INDENT 0.0 -.TP -.B depends -requests -.UNINDENT -.sp -To enable these grains that pull from the \fI\%http://169.254.169.254/metadata/instance?api\-version=2020\-09\-01\fP -metadata server set \fImetadata_server_grains: True\fP in the minion config. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -metadata_server_grains: True -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.grains.metadata_azure.metadata() -Takes no arguments, returns a dictionary of metadata values from Azure. -.UNINDENT .SS salt.grains.metadata_gce .sp Grains from cloud metadata servers at 169.254.169.254 in @@ -353241,6 +347070,18 @@ configuration value is set. .B salt.grains.opts.opts() Return the minion configuration settings .UNINDENT +.SS salt.grains.package +.sp +Grains for detecting what type of package Salt is using +.sp +New in version 3007.0. + +.INDENT 0.0 +.TP +.B salt.grains.package.package() +Function to determine if the user is currently using +onedir, pip or system level package of Salt. +.UNINDENT .SS salt.grains.panos .sp Generate baseline proxy minion grains for panos hosts. @@ -356499,7 +350340,7 @@ data: { .SS \fB/\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.SaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.SaltAPIHandler(*args, **kwargs) Main API handler for base \(dq/\(dq .INDENT 7.0 .TP @@ -356689,7 +350530,7 @@ stop on failure please use compound\-command\-execution. .SS \fB/login\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.SaltAuthHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.SaltAuthHandler(*args, **kwargs) Handler for login requests .INDENT 7.0 .TP @@ -356861,7 +350702,7 @@ Set\-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/ .SS \fB/minions\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.MinionSaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.MinionSaltAPIHandler(*args, **kwargs) A convenience endpoint for minion related functions .INDENT 7.0 .TP @@ -357031,7 +350872,7 @@ return: .SS \fB/jobs\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.JobsSaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.JobsSaltAPIHandler(*args, **kwargs) A convenience endpoint for job cache data .INDENT 7.0 .TP @@ -357164,7 +351005,7 @@ return: .SS \fB/run\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.RunSaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.RunSaltAPIHandler(*args, **kwargs) Endpoint to run commands without normal session handling .INDENT 7.0 .TP @@ -357253,7 +351094,7 @@ return: .SS \fB/events\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.EventsSaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.EventsSaltAPIHandler(*args, **kwargs) Expose the Salt event bus .sp The event bus on the Salt master exposes a large variety of things, notably @@ -357424,7 +351265,7 @@ data: {\(dqtag\(dq: \(dq20140112010149808995\(dq, \(dqdata\(dq: {\(dqfun_args\(d .SS \fB/hook\fP .INDENT 0.0 .TP -.B class salt.netapi.rest_tornado.saltnado.WebhookSaltAPIHandler(application, request, **kwargs) +.B class salt.netapi.rest_tornado.saltnado.WebhookSaltAPIHandler(*args, **kwargs) A generic web hook entry point that fires an event on Salt\(aqs event bus .sp External services can POST data to this URL to trigger an event in Salt. @@ -358776,12 +352617,6 @@ center; |l|l|. _ T{ -\fI\%azureblob\fP -T} T{ -Use Azure Blob as a Pillar source. -T} -_ -T{ \fI\%cmd_json\fP T} T{ Execute a command and read the output as JSON. @@ -359064,95 +352899,26 @@ Pillar data from vCenter or an ESXi host T} _ .TE -.SS salt.pillar.azureblob +.SS salt.pillar.cmd_json .sp -Use Azure Blob as a Pillar source. +Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion\(aqs Pillar data. +.SS Configuring the CMD_JSON ext_pillar .sp -New in version 3001. - -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\-storage\-blob\fP >= 12.0.0 -.UNINDENT -.UNINDENT -.sp -The Azure Blob ext_pillar can be configured with the following parameters: +Set the following Salt config to setup cmd json result as external pillar source: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: - \- azureblob: - container: \(aqtest_container\(aq - connection_string: \(aqconnection_string\(aq - multiple_env: False - environment: \(aqbase\(aq - blob_cache_expire: 30 - blob_sync_on_update: True + \- cmd_json: \(aqecho {\(dqarg\(dq:\(dqvalue\(dq}\(aq .ft P .fi .UNINDENT .UNINDENT -.INDENT 0.0 -.TP -.B param container -The name of the target Azure Blob Container. -.TP -.B param connection_string -The connection string to use to access the specified Azure Blob Container. -.TP -.B param multiple_env -Specifies whether the pillar should interpret top level folders as pillar environments. -Defaults to false. -.TP -.B param environment -Specifies which environment the container represents when in single environment mode. Defaults -to \(aqbase\(aq and is ignored if multiple_env is set as True. -.TP -.B param blob_cache_expire -Specifies expiration time of the Azure Blob metadata cache file. Defaults to 30s. -.TP -.B param blob_sync_on_update -Specifies if the cache is synced on update. Defaults to True. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.pillar.azureblob.ext_pillar(minion_id, pillar, container, connection_string, multiple_env=False, environment=\(aqbase\(aq, blob_cache_expire=30, blob_sync_on_update=True) -Execute a command and read the output as YAML. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBcontainer\fP \-\- The name of the target Azure Blob Container. -.IP \(bu 2 -\fBconnection_string\fP \-\- The connection string to use to access the specified Azure Blob Container. -.IP \(bu 2 -\fBmultiple_env\fP \-\- Specifies whether the pillar should interpret top level folders as pillar environments. -Defaults to false. -.IP \(bu 2 -\fBenvironment\fP \-\- Specifies which environment the container represents when in single environment mode. Defaults -to \(aqbase\(aq and is ignored if multiple_env is set as True. -.IP \(bu 2 -\fBblob_cache_expire\fP \-\- Specifies expiration time of the Azure Blob metadata cache file. Defaults to 30s. -.IP \(bu 2 -\fBblob_sync_on_update\fP \-\- Specifies if the cache is synced on update. Defaults to True. -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.pillar.cmd_json .sp -Execute a command and read the output as JSON. The JSON data is then directly overlaid onto the minion\(aqs Pillar data. +This will run the command \fBecho {arg: value}\fP on the master. +.SS Module Documentation .INDENT 0.0 .TP .B salt.pillar.cmd_json.ext_pillar(minion_id, pillar, command) @@ -365519,7 +359285,7 @@ ext_pillar: .UNINDENT .sp Each key needs to have all the key\-value pairs with the names you -require. Avoid naming every key \(aqpassword\(aq as you they will collide: +require. Avoid naming every key \(aqpassword\(aq as they will collide. .sp If you want to nest results under a nesting_key name use the following format: .INDENT 0.0 @@ -365577,7 +359343,7 @@ ext_pillar: .UNINDENT .UNINDENT .sp -You can also use nesting here as well. Identical nesting keys will get merged. +You can also use nesting here as well. Identical nesting keys will get merged. .INDENT 0.0 .INDENT 3.5 .sp @@ -365668,6 +359434,7 @@ vault ext_pillar paths. Using pillar values to template vault pillar paths requires them to be defined before the vault ext_pillar is called. Especially consider the significancy of \fI\%ext_pillar_first\fP master config setting. +You cannot use pillar values sourced from Vault in pillar\-templated policies. .sp If a pillar pattern matches multiple paths, the results are merged according to the master configuration values \fI\%pillar_source_merging_strategy\fP @@ -365969,7 +359736,6 @@ _ T{ \fI\%docker\fP T} T{ -Docker Proxy Minion T} _ T{ @@ -366764,6 +360530,14 @@ For this proxy shutdown is a no\-op .UNINDENT .SS salt.proxy.docker .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Docker Proxy Minion .sp New in version 2019.2.0. @@ -371702,6 +365476,12 @@ General management functions for salt, tools like seeing what hosts are up and w T} _ T{ +\fI\%match\fP +T} T{ +Run matchers from the master context. +T} +_ +T{ \fI\%mattermost\fP T} T{ Module for sending messages to Mattermost @@ -371824,7 +365604,6 @@ _ T{ \fI\%vault\fP T} T{ -Runner functions supporting the Vault modules. T} _ T{ @@ -375565,6 +369344,55 @@ salt\-run manage.versions .UNINDENT .UNINDENT .UNINDENT +.SS salt.runners.match +.sp +Run matchers from the master context. +.sp +New in version 3007.0. + +.INDENT 0.0 +.TP +.B salt.runners.match.compound_matches(expr, minion_id) +Check whether a minion is matched by a given compound match expression. +On success, this function will return the minion ID, otherwise False. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Pillar values will be matched literally only since this function is intended +for remote calling. This also applies to node groups defined on the master. +Custom matchers are not respected. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If a module calls this runner from a minion, you will need to explicitly +allow the remote call. See \fI\%peer_run\fP\&. +.UNINDENT +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run match.compound_matches \(aqI@foo:bar and G@os:Deb* and not db*\(aq myminion +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B expr +The \fI\%Compound Matcher\fP expression to validate against. +.TP +.B minion_id +The minion ID of the minion to check the match for. +.UNINDENT +.UNINDENT .SS salt.runners.mattermost .sp \fBNote for 2017.7 releases!\fP @@ -378251,6 +372079,41 @@ salt\-run saltutil.sync_wheel .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.saltutil.sync_wrapper(saltenv=\(aqbase\(aq, extmod_whitelist=None, extmod_blacklist=None) +New in version 3007.0. + +.sp +Sync salt\-ssh wrapper modules from \fBsalt://_wrapper\fP to the master. +.INDENT 7.0 +.TP +.B saltenv +base +The fileserver environment from which to sync. To sync from more than +one environment, pass a comma\-separated list. +.TP +.B extmod_whitelist +None +comma\-seperated list of modules to sync +.TP +.B extmod_blacklist +None +comma\-seperated list of modules to blacklist based on type +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run saltutil.sync_wrapper +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.runners.sdb .sp Runner for setting and querying data via the sdb API on the master @@ -379478,8 +373341,16 @@ salt\-run thin.generate_min .UNINDENT .SS salt.runners.vault .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%vault Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Runner functions supporting the Vault modules. Configuration instructions are -documented in the execution module docs. +documented in the \fI\%execution module docs\fP\&. .INDENT 0.0 .TP .B maintainer @@ -379499,12 +373370,145 @@ once an item is requested. .UNINDENT .INDENT 0.0 .TP -.B salt.runners.vault.generate_token(minion_id, signature, impersonated_by_master=False, ttl=None, uses=None) -Generate a Vault token for minion minion_id +.B salt.runners.vault.cleanup_auth() +New in version 3007.0. + +.sp +Removes AppRoles and entities associated with unknown minion IDs. +Can only clean up entities if the AppRole still exists. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Make absolutely sure that the configured minion approle issue mount is +exclusively dedicated to the Salt master, otherwise you might lose data +by using this function! (config: \fBvault:issue:approle:mount\fP) +.sp +This detects unknown existing AppRoles by listing all roles on the +configured minion AppRole mount and deducting known minions from the +returned list. +.UNINDENT +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.cleanup_auth +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.clear_cache(master=True, minions=True) +New in version 3007.0. + +.sp +Clears master cache of Vault\-specific data. This can include: +\- AppRole metadata +\- rendered policies +\- cached authentication credentials for impersonated minions +\- cached KV metadata for impersonated minions +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.clear_cache +salt\-run vault.clear_cache minions=false +salt\-run vault.clear_cache master=false minions=\(aq[minion1, minion2]\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B master +Clear cached data for the master context. +Includes cached master authentication data and KV metadata. +Defaults to true. +.TP +.B minions +Clear cached data for minions on the master. +Can include cached authentication credentials and KV metadata +for pillar compilation as well as AppRole metadata and +rendered policies for credential issuance. +Defaults to true. Set this to a list of minion IDs to only clear +cached data pertaining to thse minions. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.generate_new_token(minion_id, signature, impersonated_by_master=False, issue_params=None) +New in version 3007.0. + +.sp +Generate a Vault token for minion . .INDENT 7.0 .TP .B minion_id -The id of the minion that requests a token +The ID of the minion that requests a token. +.TP +.B signature +Cryptographic signature which validates that the request is indeed sent +by the minion (or the master, see impersonated_by_master). +.TP +.B impersonated_by_master +If the master needs to create a token on behalf of the minion, this is +True. This happens when the master generates minion pillars. +.TP +.B issue_params +Dictionary of parameters for the generated tokens. +See master configuration \fBvault:issue:token:params\fP for possible values. +Requires \fBvault:issue:allow_minion_override_params\fP master configuration +setting to be effective. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.generate_secret_id(minion_id, signature, impersonated_by_master=False, issue_params=None) +New in version 3007.0. + +.sp +Generate a Vault secret ID for minion . Requires the master to be configured +to generate AppRoles for minions (configuration: \fBvault:issue:type\fP). +.INDENT 7.0 +.TP +.B minion_id +The ID of the minion that requests a secret ID. +.TP +.B signature +Cryptographic signature which validates that the request is indeed sent +by the minion (or the master, see impersonated_by_master). +.TP +.B impersonated_by_master +If the master needs to create a token on behalf of the minion, this is +True. This happens when the master generates minion pillars. +.TP +.B issue_params +Dictionary of configuration values for the generated AppRole. +See master configuration vault:issue:approle:params for possible values. +Requires \fBvault:issue:allow_minion_override_params\fP master configuration +setting to be effective. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.generate_token(minion_id, signature, impersonated_by_master=False, ttl=None, uses=None, upgrade_request=False) +Deprecated since version 3007.0. + +.sp +Generate a Vault token for minion . +.INDENT 7.0 +.TP +.B minion_id +The ID of the minion that requests a token. .TP .B signature Cryptographic signature which validates that the request is indeed sent @@ -379519,6 +373523,180 @@ Ticket time to live in seconds, 1m minutes, or 2h hrs .TP .B uses Number of times a token can be used +.TP +.B upgrade_request +In case the new runner endpoints have not been whitelisted for peer running, +this endpoint serves as a gateway to \fBvault.get_config\fP\&. +Defaults to False. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.get_config(minion_id, signature, impersonated_by_master=False, issue_params=None, config_only=False) +New in version 3007.0. + +.sp +Return Vault configuration for minion . +.INDENT 7.0 +.TP +.B minion_id +The ID of the minion that requests the configuration. +.TP +.B signature +Cryptographic signature which validates that the request is indeed sent +by the minion (or the master, see impersonated_by_master). +.TP +.B impersonated_by_master +If the master needs to contact the Vault server on behalf of the minion, this is +True. This happens when the master generates minion pillars. +.TP +.B issue_params +Parameters for credential issuance. +Requires \fBvault:issue:allow_minion_override_params\fP master configuration +setting to be effective. +.TP +.B config_only +In case the master is configured to issue tokens, do not include a new +token in the response. This is used for configuration update checks. +Defaults to false. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.get_role_id(minion_id, signature, impersonated_by_master=False, issue_params=None) +New in version 3007.0. + +.sp +Return the Vault role\-id for minion . Requires the master to be configured +to generate AppRoles for minions (configuration: \fBvault:issue:type\fP). +.INDENT 7.0 +.TP +.B minion_id +The ID of the minion that requests a role\-id. +.TP +.B signature +Cryptographic signature which validates that the request is indeed sent +by the minion (or the master, see impersonated_by_master). +.TP +.B impersonated_by_master +If the master needs to create a token on behalf of the minion, this is +True. This happens when the master generates minion pillars. +.TP +.B issue_params +Dictionary of configuration values for the generated AppRole. +See master configuration vault:issue:approle:params for possible values. +Requires \fBvault:issue:allow_minion_override_params\fP master configuration +setting to be effective. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.list_approles() +New in version 3007.0. + +.sp +List all AppRoles that have been created by the Salt master. +They are named after the minions. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.list_approles +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqauth//role\(dq { + capabilities = [\(dqlist\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.list_entities() +New in version 3007.0. + +.sp +List all entities that have been created by the Salt master. +They are named \fIsalt_minion_{minion_id}\fP\&. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.list_entities +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Required policy: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +path \(dqidentity/entity/name\(dq { + capabilities = [\(dqlist\(dq] +} +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.show_approle(minion_id) +New in version 3007.0. + +.sp +Show AppRole configuration for . +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.show_approle db1 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.show_entity(minion_id) +New in version 3007.0. + +.sp +Show entity metadata for . +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.show_entity db1 +.ft P +.fi +.UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 @@ -379528,19 +373706,28 @@ Show the Vault policies that are applied to tokens for the given minion. .INDENT 7.0 .TP .B minion_id -The minion\(aqs id. +The ID of the minion to show policies for. .TP .B refresh_pillar Whether to refresh the pillar data when rendering templated policies. None will only refresh when the cached data is unavailable, boolean values force one behavior always. -Defaults to config value \fBpolicies_refresh_pillar\fP or None. +Defaults to config value \fBvault:policies:refresh_pillar\fP or None. .TP .B expire Policy computation can be heavy in case pillar data is used in templated policies and it has not been cached. Therefore, a short\-lived cache specifically for rendered policies is used. This specifies the expiration timeout in seconds. -Defaults to config value \fBpolicies_cache_time\fP or 60. +Defaults to config value \fBvault:policies:cache_time\fP or 60. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When issuing AppRoles to minions, the shown policies are read from Vault +configuration for the minion\(aqs AppRole and thus refresh_pillar/expire +will not be honored. +.UNINDENT .UNINDENT .sp CLI Example: @@ -379557,6 +373744,107 @@ salt\-run vault.show_policies myminion .UNINDENT .INDENT 0.0 .TP +.B salt.runners.vault.sync_approles(minions=None, up=False, down=False) +New in version 3007.0. + +.sp +Sync minion AppRole parameters with current settings, including associated +token policies. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Only updates existing AppRoles. They are issued during the first request +for one by the minion. +Running this will reset minion overrides, which are reapplied automatically +during the next request for authentication details. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Unlike when issuing tokens, AppRole\-associated policies are not regularly +refreshed automatically. It is advised to schedule regular runs of this function. +.UNINDENT +.UNINDENT +.sp +If no parameter is specified, will try to sync AppRoles for all known minions. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.sync_approles +salt\-run vault.sync_approles ecorp +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B minions +(List of) ID(s) of the minion(s) to update the AppRole for. +Defaults to None. +.TP +.B up +Find all minions that are up and update their AppRoles. +Defaults to False. +.TP +.B down +Find all minions that are down and update their AppRoles. +Defaults to False. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.runners.vault.sync_entities(minions=None, up=False, down=False) +New in version 3007.0. + +.sp +Sync minion entities with current settings. Only updates entities for minions +with existing AppRoles. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This updates associated metadata only. Entities are created only +when issuing AppRoles to minions (\fBvault:issue:type\fP == \fBapprole\fP). +.UNINDENT +.UNINDENT +.sp +If no parameter is specified, will try to sync entities for all known minions. +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +salt\-run vault.sync_entities +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B minions +(List of) ID(s) of the minion(s) to update the entity for. +Defaults to None. +.TP +.B up +Find all minions that are up and update their associated entities. +Defaults to False. +.TP +.B down +Find all minions that are down and update their associated entities. +Defaults to False. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.runners.vault.unseal() Unseal Vault server .sp @@ -380976,7 +375264,7 @@ New in version 2016.11.0. .sp This module allows access to Hashicorp Vault using an \fBsdb://\fP URI. .sp -Base configuration instructions are documented in the execution module docs. +Base configuration instructions are documented in the \fI\%execution module docs\fP\&. Below are noted extra configuration required for the sdb module, but the base configuration must also be completed. .sp @@ -381021,6 +375309,20 @@ $ vault read \-field=mypassword secret/passwords .ft P .fi .UNINDENT +.UNINDENT +.SS Further configuration +.sp +The following options can be set in the profile: +.INDENT 0.0 +.TP +.B patch +When writing data, partially update the secret instead of overwriting it completely. +This is usually the expected behavior, since without this option, +each secret path can only contain a single mapping key safely. +Defaults to \fBFalse\fP for backwards\-compatibility reasons. +.sp +New in version 3007.0. + .UNINDENT .INDENT 0.0 .TP @@ -382107,25 +376409,21 @@ _ T{ \fI\%apache\fP T} T{ -Apache state T} _ T{ \fI\%apache_conf\fP T} T{ -Manage Apache Confs T} _ T{ \fI\%apache_module\fP T} T{ -Manage Apache Modules T} _ T{ \fI\%apache_site\fP T} T{ -Manage Apache Sites T} _ T{ @@ -382165,30 +376463,6 @@ Manage SQS Queues T} _ T{ -\fI\%azurearm_compute\fP -T} T{ -Azure (ARM) Compute State Module -T} -_ -T{ -\fI\%azurearm_dns\fP -T} T{ -Azure (ARM) DNS State Module -T} -_ -T{ -\fI\%azurearm_network\fP -T} T{ -Azure (ARM) Network State Module -T} -_ -T{ -\fI\%azurearm_resource\fP -T} T{ -Azure (ARM) Resource State Module -T} -_ -T{ \fI\%beacon\fP T} T{ Management of the Salt beacons @@ -382539,25 +376813,21 @@ _ T{ \fI\%docker_container\fP T} T{ -Management of Docker containers T} _ T{ \fI\%docker_image\fP T} T{ -Management of Docker images T} _ T{ \fI\%docker_network\fP T} T{ -Management of Docker networks T} _ T{ \fI\%docker_volume\fP T} T{ -Management of Docker volumes T} _ T{ @@ -382707,7 +376977,7 @@ _ T{ \fI\%gpg\fP T} T{ -Management of the GPG keychains +Manage GPG keychains T} _ T{ @@ -383012,7 +377282,6 @@ _ T{ \fI\%kubernetes\fP T} T{ -Manage kubernetes resources as salt states T} _ T{ @@ -383600,7 +377869,6 @@ _ T{ \fI\%pushover\fP T} T{ -Send a message to PushOver T} _ T{ @@ -383929,7 +378197,6 @@ _ T{ \fI\%vault\fP T} T{ -States for managing Hashicorp Vault. T} _ T{ @@ -383963,6 +378230,12 @@ Support for htpasswd module. T} _ T{ +\fI\%win_appx\fP +T} T{ +Manage Microsoft Store apps on Windows. +T} +_ +T{ \fI\%win_certutil\fP T} T{ Installing of certificates to the Windows Certificate Manager @@ -384071,6 +378344,12 @@ Management of Windows system information T} _ T{ +\fI\%win_task\fP +T} T{ +State module for adding and removing scheduled tasks using the Windows Task Scheduler. +T} +_ +T{ \fI\%win_wua\fP T} T{ Installation of Windows Updates using the Windows Update Agent @@ -384121,55 +378400,46 @@ _ T{ \fI\%zabbix_action\fP T} T{ -Management of Zabbix Action object over Zabbix API. T} _ T{ \fI\%zabbix_host\fP T} T{ -Management of Zabbix hosts. T} _ T{ \fI\%zabbix_hostgroup\fP T} T{ -Management of Zabbix host groups. T} _ T{ \fI\%zabbix_mediatype\fP T} T{ -Management of Zabbix mediatypes. T} _ T{ \fI\%zabbix_template\fP T} T{ -New in version 2017.7.0. T} _ T{ \fI\%zabbix_user\fP T} T{ -Management of Zabbix users. T} _ T{ \fI\%zabbix_usergroup\fP T} T{ -Management of Zabbix user groups. T} _ T{ \fI\%zabbix_usermacro\fP T} T{ -Management of Zabbix usermacros. T} _ T{ \fI\%zabbix_valuemap\fP T} T{ -Management of Zabbix Valuemap object over Zabbix API. T} _ T{ @@ -384247,7 +378517,7 @@ dev.example.com: .UNINDENT .INDENT 0.0 .TP -.B salt.states.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None) +.B salt.states.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None, manual_auth_hook=None, manual_cleanup_hook=None) Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt. .INDENT 7.0 .TP @@ -384298,6 +378568,10 @@ will still attempt to connect on port 80. \fBdns_plugin\fP \-\- Name of a DNS plugin to use (currently only \(aqcloudflare\(aq) .IP \(bu 2 \fBdns_plugin_credentials\fP \-\- Path to the credentials file if required by the specified DNS plugin +.IP \(bu 2 +\fBmanual_auth_hook\fP \-\- Path to the authentication hook script. +.IP \(bu 2 +\fBmanual_cleanup_hook\fP \-\- Path to the cleanup or post\-authentication hook script. .UNINDENT .UNINDENT .UNINDENT @@ -384573,6 +378847,14 @@ run nginx install: .UNINDENT .SS salt.states.apache .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Apache state .sp New in version 2014.7.0. @@ -384676,6 +378958,14 @@ it still needs keyword \fBthis\fP with empty string (or \(dq\(dq if nicer outpu .UNINDENT .SS salt.states.apache_conf .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Manage Apache Confs .sp New in version 2016.3.0. @@ -384720,6 +379010,14 @@ Name of the Apache conf .UNINDENT .SS salt.states.apache_module .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Manage Apache Modules .sp New in version 2014.7.0. @@ -384770,6 +379068,14 @@ Name of the Apache module .UNINDENT .SS salt.states.apache_site .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%apache Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Manage Apache Sites .sp New in version 2016.3.0. @@ -384832,7 +379138,7 @@ New in version 2014.1.0. .INDENT 0.0 .TP -.B salt.states.archive.extracted(name, source, source_hash=None, source_hash_name=None, source_hash_update=False, skip_files_list_verify=False, skip_verify=False, password=None, options=None, list_options=None, force=False, overwrite=False, clean=False, clean_parent=False, user=None, group=None, if_missing=None, trim_output=False, use_cmd_unzip=None, extract_perms=True, enforce_toplevel=True, enforce_ownership_on=None, archive_format=None, use_etag=False, **kwargs) +.B salt.states.archive.extracted(name, source, source_hash=None, source_hash_name=None, source_hash_update=False, skip_files_list_verify=False, skip_verify=False, password=None, options=None, list_options=None, force=False, overwrite=False, clean=False, clean_parent=False, user=None, group=None, if_missing=None, trim_output=False, use_cmd_unzip=None, extract_perms=True, enforce_toplevel=True, enforce_ownership_on=None, archive_format=None, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) New in version 2014.1.0. .sp @@ -385458,6 +379764,76 @@ the \fBsource_hash\fP parameter. .sp New in version 3005. +.TP +.B signature +Ensure a valid GPG signature exists on the selected \fBsource\fP file. +This needs to be a file URI retrievable by +\fI:py:func:\(gacp.cache_file \fP which +identifies a detached signature. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature is only enforced directly after caching the file, +before it is extracted to its final destination. Existing files +at the target will never be modified. +.sp +It will be enforced regardless of source type. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B source_hash_sig +When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, +\fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a +valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature on the \fBsource_hash\fP file is enforced regardless of +changes since its contents are used to check if an existing file +is in the correct state \- but only for remote sources! +As for \fBsignature\fP, existing target files will not be modified, +only the cached source_hash and source_hash_sig files will be removed. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying signatures either on the managed file or its source hash file, +require at least one valid signature from one of a list of key fingerprints. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying signatures either on the managed file or its source hash file, +require a valid signature from each of the key fingerprints in this list. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying signatures, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying signatures, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .sp \fBExamples\fP @@ -385837,31 +380213,6 @@ New in version 0.17.0. This state requires the \fBaugeas\fP Python module. .sp \fI\%Augeas\fP can be used to manage configuration files. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -Minimal installations of Debian and Ubuntu have been seen to have packaging -bugs with python\-augeas, causing the augeas module to fail to import. If -the minion has the augeas module installed, and the state fails with a -comment saying that the state is unavailable, first restart the salt\-minion -service. If the problem persists past that, the following command can be -run from the master to determine what is causing the import to fail: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt minion\-id cmd.run \(aqpython \-c \(dqfrom augeas import Augeas\(dq\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -For affected Debian/Ubuntu hosts, installing \fBlibpython2.7\fP has been -known to resolve the issue. -.UNINDENT -.UNINDENT .INDENT 0.0 .TP .B salt.states.augeas.change(name, context=None, changes=None, lens=None, load_path=None, **kwargs) @@ -386023,7 +380374,7 @@ zabbix\-service: \- set \(dqservice\-name[. = \(aqzabbix\-agent\(aq]/protocol\(dq tcp \- set \(dqservice\-name[. = \(aqzabbix\-agent\(aq]/#comment\(dq \(dqZabbix Agent service\(dq \- rm \(dqservice\-name[. = \(aqim\-obsolete\(aq]\(dq - \- unless: grep \(dqzabbix\-agent\(dq /etc/services + \- unless: grep \(aq^zabbix\-agent\es\(aq /etc/services .ft P .fi .UNINDENT @@ -386111,2131 +380462,6 @@ Name of the user performing the SQS operations Include additional arguments and options to the aws command line .UNINDENT .UNINDENT -.SS salt.states.azurearm_compute -.sp -Azure (ARM) Compute State Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as a dictionary of -keyword arguments to the \fBconnection_auth\fP parameter in order to work properly. Since the authentication -parameters are sensitive, it\(aqs recommended to pass them to the states via pillar. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 7.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.sp -Example Pillar for Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurearm: - user_pass_auth: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - username: fletch - password: 123pass - mysubscription: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - secret: XXXXXXXXXXXXXXXXXXXXXXXX - cloud_environment: AZURE_PUBLIC_CLOUD -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Example states using Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{% set profile = salt[\(aqpillar.get\(aq](\(aqazurearm:mysubscription\(aq) %} -Ensure availability set exists: - azurearm_compute.availability_set_present: - \- name: my_avail_set - \- resource_group: my_rg - \- virtual_machines: - \- my_vm1 - \- my_vm2 - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - -Ensure availability set is absent: - azurearm_compute.availability_set_absent: - \- name: other_avail_set - \- resource_group: my_rg - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_compute.availability_set_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure an availability set does not exist in a resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the availability set. -.IP \(bu 2 -\fBresource_group\fP \-\- Name of the resource group containing the availability set. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_compute.availability_set_present(name, resource_group, tags=None, platform_update_domain_count=None, platform_fault_domain_count=None, virtual_machines=None, sku=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure an availability set exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the availability set. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the availability set. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the availability set object. -.IP \(bu 2 -\fBplatform_update_domain_count\fP \-\- An optional parameter which indicates groups of virtual machines and underlying physical hardware that can be -rebooted at the same time. -.IP \(bu 2 -\fBplatform_fault_domain_count\fP \-\- An optional parameter which defines the group of virtual machines that share a common power source and network -switch. -.IP \(bu 2 -\fBvirtual_machines\fP \-\- A list of names of existing virtual machines to be included in the availability set. -.IP \(bu 2 -\fBsku\fP \-\- The availability set SKU, which specifies whether the availability set is managed or not. Possible values are -\(aqAligned\(aq or \(aqClassic\(aq. An \(aqAligned\(aq availability set is managed, \(aqClassic\(aq is not. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure availability set exists: - azurearm_compute.availability_set_present: - \- name: aset1 - \- resource_group: group1 - \- platform_update_domain_count: 5 - \- platform_fault_domain_count: 3 - \- sku: aligned - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.states.azurearm_dns -.sp -Azure (ARM) DNS State Module -.sp -New in version 3000. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-dns\fP >= 1.0.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as a dictionary of -keyword arguments to the \fBconnection_auth\fP parameter in order to work properly. Since the authentication -parameters are sensitive, it\(aqs recommended to pass them to the states via pillar. -.UNINDENT -.sp -Required provider parameters: -.INDENT 0.0 -.INDENT 3.5 -if using username and password: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.UNINDENT -.UNINDENT -.sp -if using a service principal: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 0.0 -.INDENT 3.5 -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: -.sp -Possible values: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Example Pillar for Azure Resource Manager authentication: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurearm: - user_pass_auth: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - username: fletch - password: 123pass - mysubscription: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - secret: XXXXXXXXXXXXXXXXXXXXXXXX - cloud_environment: AZURE_PUBLIC_CLOUD -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Example states using Azure Resource Manager authentication: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{% set profile = salt[\(aqpillar.get\(aq](\(aqazurearm:mysubscription\(aq) %} -Ensure DNS zone exists: - azurearm_dns.zone_present: - \- name: contoso.com - \- resource_group: my_rg - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - -Ensure DNS record set exists: - azurearm_dns.record_set_present: - \- name: web - \- zone_name: contoso.com - \- resource_group: my_rg - \- record_type: A - \- ttl: 300 - \- arecords: - \- ipv4_address: 10.0.0.1 - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - -Ensure DNS record set is absent: - azurearm_dns.record_set_absent: - \- name: web - \- zone_name: contoso.com - \- resource_group: my_rg - \- record_type: A - \- connection_auth: {{ profile }} - -Ensure DNS zone is absent: - azurearm_dns.zone_absent: - \- name: contoso.com - \- resource_group: my_rg - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_dns.record_set_absent(name, zone_name, resource_group, connection_auth=None) -New in version 3000. - -.sp -Ensure a record set does not exist in the DNS zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the record set. -.IP \(bu 2 -\fBzone_name\fP \-\- Name of the DNS zone. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the DNS zone. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_dns.record_set_present(name, zone_name, resource_group, record_type, if_match=None, if_none_match=None, etag=None, metadata=None, ttl=None, arecords=None, aaaa_records=None, mx_records=None, ns_records=None, ptr_records=None, srv_records=None, txt_records=None, cname_record=None, soa_record=None, caa_records=None, connection_auth=None, **kwargs) -New in version 3000. - -.sp -Ensure a record set exists in a DNS zone. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- The name of the record set, relative to the name of the zone. -.IP \(bu 2 -\fBzone_name\fP \-\- Name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the DNS zone. -.IP \(bu 2 -\fBrecord_type\fP \-\- The type of DNS record in this record set. Record sets of type SOA can be updated but not created -(they are created when the DNS zone is created). Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, -\(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq -.IP \(bu 2 -\fBif_match\fP \-\- The etag of the record set. Omit this value to always overwrite the current record set. Specify the last\-seen -etag value to prevent accidentally overwritting any concurrent changes. -.IP \(bu 2 -\fBif_none_match\fP \-\- Set to \(aq*\(aq to allow a new record set to be created, but to prevent updating an existing record set. Other values -will be ignored. -.IP \(bu 2 -\fBetag\fP \-\- The etag of the record set. \fI\%Etags\fP are -used to handle concurrent changes to the same resource safely. -.IP \(bu 2 -\fBmetadata\fP \-\- A dictionary of strings can be passed as tag metadata to the record set object. -.IP \(bu 2 -\fBttl\fP \-\- The TTL (time\-to\-live) of the records in the record set. Required when specifying record information. -.IP \(bu 2 -\fBarecords\fP \-\- The list of A records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBaaaa_records\fP \-\- The list of AAAA records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBmx_records\fP \-\- The list of MX records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBns_records\fP \-\- The list of NS records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBptr_records\fP \-\- The list of PTR records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBsrv_records\fP \-\- The list of SRV records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBtxt_records\fP \-\- The list of TXT records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBcname_record\fP \-\- The CNAME record in the record set. View the -\fI\%Azure SDK documentation\fP -to create a dictionary representing the record object. -.IP \(bu 2 -\fBsoa_record\fP \-\- The SOA record in the record set. View the -\fI\%Azure SDK documentation\fP -to create a dictionary representing the record object. -.IP \(bu 2 -\fBcaa_records\fP \-\- The list of CAA records in the record set. View the -\fI\%Azure SDK documentation\fP -to create a list of dictionaries representing the record objects. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure record set exists: - azurearm_dns.record_set_present: - \- name: web - \- zone_name: contoso.com - \- resource_group: my_rg - \- record_type: A - \- ttl: 300 - \- arecords: - \- ipv4_address: 10.0.0.1 - \- metadata: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_dns.zone_absent(name, resource_group, connection_auth=None) -New in version 3000. - -.sp -Ensure a DNS zone does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the DNS zone. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the DNS zone. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_dns.zone_present(name, resource_group, etag=None, if_match=None, if_none_match=None, registration_virtual_networks=None, resolution_virtual_networks=None, tags=None, zone_type=\(aqPublic\(aq, connection_auth=None, **kwargs) -New in version 3000. - -.sp -Ensure a DNS zone exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the DNS zone (without a terminating dot). -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the DNS zone. -.IP \(bu 2 -\fBetag\fP \-\- The etag of the zone. \fI\%Etags\fP are used -to handle concurrent changes to the same resource safely. -.IP \(bu 2 -\fBif_match\fP \-\- The etag of the DNS zone. Omit this value to always overwrite the current zone. Specify the last\-seen etag -value to prevent accidentally overwritting any concurrent changes. -.IP \(bu 2 -\fBif_none_match\fP \-\- Set to \(aq*\(aq to allow a new DNS zone to be created, but to prevent updating an existing zone. Other values will -be ignored. -.IP \(bu 2 -\fBregistration_virtual_networks\fP \-\- -.sp -A list of references to virtual networks that register hostnames in this DNS zone. This is only when zone_type -is Private. (requires \fI\%azure\-mgmt\-dns\fP >= 2.0.0rc1) - -.IP \(bu 2 -\fBresolution_virtual_networks\fP \-\- -.sp -A list of references to virtual networks that resolve records in this DNS zone. This is only when zone_type is -Private. (requires \fI\%azure\-mgmt\-dns\fP >= 2.0.0rc1) - -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the DNS zone object. -.IP \(bu 2 -\fBzone_type\fP \-\- .INDENT 2.0 -.TP -.B The type of this DNS zone (Public or Private). Possible values include: \(aqPublic\(aq, \(aqPrivate\(aq. Default value: \(aqPublic\(aq -(requires \fI\%azure\-mgmt\-dns\fP >= 2.0.0rc1) -.UNINDENT - -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure DNS zone exists: - azurearm_dns.zone_present: - \- name: contoso.com - \- resource_group: my_rg - \- zone_type: Private - \- registration_virtual_networks: - \- /subscriptions/{{ sub }}/resourceGroups/my_rg/providers/Microsoft.Network/virtualNetworks/test_vnet - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.states.azurearm_network -.sp -Azure (ARM) Network State Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as a dictionary of -keyword arguments to the \fBconnection_auth\fP parameter in order to work properly. Since the authentication -parameters are sensitive, it\(aqs recommended to pass them to the states via pillar. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 7.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.sp -Example Pillar for Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurearm: - user_pass_auth: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - username: fletch - password: 123pass - mysubscription: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - secret: XXXXXXXXXXXXXXXXXXXXXXXX - cloud_environment: AZURE_PUBLIC_CLOUD -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Example states using Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{% set profile = salt[\(aqpillar.get\(aq](\(aqazurearm:mysubscription\(aq) %} -Ensure virtual network exists: - azurearm_network.virtual_network_present: - \- name: my_vnet - \- resource_group: my_rg - \- address_prefixes: - \- \(aq10.0.0.0/8\(aq - \- \(aq192.168.0.0/16\(aq - \- dns_servers: - \- \(aq8.8.8.8\(aq - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - -Ensure virtual network is absent: - azurearm_network.virtual_network_absent: - \- name: other_vnet - \- resource_group: my_rg - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.load_balancer_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a load balancer does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the load balancer. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the load balancer. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.load_balancer_present(name, resource_group, sku=None, frontend_ip_configurations=None, backend_address_pools=None, load_balancing_rules=None, probes=None, inbound_nat_rules=None, inbound_nat_pools=None, outbound_nat_rules=None, tags=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a load balancer exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the load balancer. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the load balancer. -.IP \(bu 2 -\fBsku\fP \-\- The load balancer SKU, which can be \(aqBasic\(aq or \(aqStandard\(aq. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the load balancer object. -.IP \(bu 2 -\fBfrontend_ip_configurations\fP \-\- -.sp -An optional list of dictionaries representing valid FrontendIPConfiguration objects. A frontend IP -configuration can be either private (using private IP address and subnet parameters) or public (using a -reference to a public IP address object). Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBprivate_ip_address\fP: The private IP address of the IP configuration. Required if -\(aqprivate_ip_allocation_method\(aq is \(aqStatic\(aq. -.IP \(bu 2 -\fBprivate_ip_allocation_method\fP: The Private IP allocation method. Possible values are: \(aqStatic\(aq and -\(aqDynamic\(aq. -.IP \(bu 2 -\fBsubnet\fP: Name of an existing subnet inside of which the frontend IP will reside. -.IP \(bu 2 -\fBpublic_ip_address\fP: Name of an existing public IP address which will be assigned to the frontend IP object. -.UNINDENT - -.IP \(bu 2 -\fBbackend_address_pools\fP \-\- An optional list of dictionaries representing valid BackendAddressPool objects. Only the \(aqname\(aq parameter is -valid for a BackendAddressPool dictionary. All other parameters are read\-only references from other objects -linking to the backend address pool. Inbound traffic is randomly load balanced across IPs in the backend IPs. -.IP \(bu 2 -\fBprobes\fP \-\- -.sp -An optional list of dictionaries representing valid Probe objects. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBprotocol\fP: The protocol of the endpoint. Possible values are \(aqHttp\(aq or \(aqTcp\(aq. If \(aqTcp\(aq is specified, a -received ACK is required for the probe to be successful. If \(aqHttp\(aq is specified, a 200 OK response from the -specified URI is required for the probe to be successful. -.IP \(bu 2 -\fBport\fP: The port for communicating the probe. Possible values range from 1 to 65535, inclusive. -.IP \(bu 2 -\fBinterval_in_seconds\fP: The interval, in seconds, for how frequently to probe the endpoint for health status. -Typically, the interval is slightly less than half the allocated timeout period (in seconds) which allows two -full probes before taking the instance out of rotation. The default value is 15, the minimum value is 5. -.IP \(bu 2 -\fBnumber_of_probes\fP: The number of probes where if no response, will result in stopping further traffic from -being delivered to the endpoint. This values allows endpoints to be taken out of rotation faster or slower -than the typical times used in Azure. -.IP \(bu 2 -\fBrequest_path\fP: The URI used for requesting health status from the VM. Path is required if a protocol is -set to \(aqHttp\(aq. Otherwise, it is not allowed. There is no default value. -.UNINDENT - -.IP \(bu 2 -\fBload_balancing_rules\fP \-\- -.sp -An optional list of dictionaries representing valid LoadBalancingRule objects. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBload_distribution\fP: The load distribution policy for this rule. Possible values are \(aqDefault\(aq, \(aqSourceIP\(aq, -and \(aqSourceIPProtocol\(aq. -.IP \(bu 2 -\fBfrontend_port\fP: The port for the external endpoint. Port numbers for each rule must be unique within the -Load Balancer. Acceptable values are between 0 and 65534. Note that value 0 enables \(aqAny Port\(aq. -.IP \(bu 2 -\fBbackend_port\fP: The port used for internal connections on the endpoint. Acceptable values are between 0 and -65535. Note that value 0 enables \(aqAny Port\(aq. -.IP \(bu 2 -\fBidle_timeout_in_minutes\fP: The timeout for the TCP idle connection. The value can be set between 4 and 30 -minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP. -.IP \(bu 2 -\fBenable_floating_ip\fP: Configures a virtual machine\(aqs endpoint for the floating IP capability required -to configure a SQL AlwaysOn Availability Group. This setting is required when using the SQL AlwaysOn -Availability Groups in SQL server. This setting can\(aqt be changed after you create the endpoint. -.IP \(bu 2 -\fBdisable_outbound_snat\fP: Configures SNAT for the VMs in the backend pool to use the public IP address -specified in the frontend of the load balancing rule. -.IP \(bu 2 -\fBfrontend_ip_configuration\fP: Name of the frontend IP configuration object used by the load balancing rule -object. -.IP \(bu 2 -\fBbackend_address_pool\fP: Name of the backend address pool object used by the load balancing rule object. -Inbound traffic is randomly load balanced across IPs in the backend IPs. -.IP \(bu 2 -\fBprobe\fP: Name of the probe object used by the load balancing rule object. -.UNINDENT - -.IP \(bu 2 -\fBinbound_nat_rules\fP \-\- -.sp -An optional list of dictionaries representing valid InboundNatRule objects. Defining inbound NAT rules on your -load balancer is mutually exclusive with defining an inbound NAT pool. Inbound NAT pools are referenced from -virtual machine scale sets. NICs that are associated with individual virtual machines cannot reference an -Inbound NAT pool. They have to reference individual inbound NAT rules. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBfrontend_ip_configuration\fP: Name of the frontend IP configuration object used by the inbound NAT rule -object. -.IP \(bu 2 -\fBprotocol\fP: Possible values include \(aqUdp\(aq, \(aqTcp\(aq, or \(aqAll\(aq. -.IP \(bu 2 -\fBfrontend_port\fP: The port for the external endpoint. Port numbers for each rule must be unique within the -Load Balancer. Acceptable values range from 1 to 65534. -.IP \(bu 2 -\fBbackend_port\fP: The port used for the internal endpoint. Acceptable values range from 1 to 65535. -.IP \(bu 2 -\fBidle_timeout_in_minutes\fP: The timeout for the TCP idle connection. The value can be set between 4 and 30 -minutes. The default value is 4 minutes. This element is only used when the protocol is set to TCP. -.IP \(bu 2 -\fBenable_floating_ip\fP: Configures a virtual machine\(aqs endpoint for the floating IP capability required -to configure a SQL AlwaysOn Availability Group. This setting is required when using the SQL AlwaysOn -Availability Groups in SQL server. This setting can\(aqt be changed after you create the endpoint. -.UNINDENT - -.IP \(bu 2 -\fBinbound_nat_pools\fP \-\- -.sp -An optional list of dictionaries representing valid InboundNatPool objects. They define an external port range -for inbound NAT to a single backend port on NICs associated with a load balancer. Inbound NAT rules are created -automatically for each NIC associated with the Load Balancer using an external port from this range. Defining an -Inbound NAT pool on your Load Balancer is mutually exclusive with defining inbound NAT rules. Inbound NAT pools -are referenced from virtual machine scale sets. NICs that are associated with individual virtual machines cannot -reference an inbound NAT pool. They have to reference individual inbound NAT rules. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBfrontend_ip_configuration\fP: Name of the frontend IP configuration object used by the inbound NAT pool -object. -.IP \(bu 2 -\fBprotocol\fP: Possible values include \(aqUdp\(aq, \(aqTcp\(aq, or \(aqAll\(aq. -.IP \(bu 2 -\fBfrontend_port_range_start\fP: The first port number in the range of external ports that will be used to -provide Inbound NAT to NICs associated with a load balancer. Acceptable values range between 1 and 65534. -.IP \(bu 2 -\fBfrontend_port_range_end\fP: The last port number in the range of external ports that will be used to -provide Inbound NAT to NICs associated with a load balancer. Acceptable values range between 1 and 65535. -.IP \(bu 2 -\fBbackend_port\fP: The port used for internal connections to the endpoint. Acceptable values are between 1 and -65535. -.UNINDENT - -.IP \(bu 2 -\fBoutbound_nat_rules\fP \-\- -.sp -An optional list of dictionaries representing valid OutboundNatRule objects. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBname\fP: The name of the resource that is unique within a resource group. -.IP \(bu 2 -\fBfrontend_ip_configuration\fP: Name of the frontend IP configuration object used by the outbound NAT rule -object. -.IP \(bu 2 -\fBbackend_address_pool\fP: Name of the backend address pool object used by the outbound NAT rule object. -Outbound traffic is randomly load balanced across IPs in the backend IPs. -.IP \(bu 2 -\fBallocated_outbound_ports\fP: The number of outbound ports to be used for NAT. -.UNINDENT - -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure load balancer exists: - azurearm_network.load_balancer_present: - \- name: lb1 - \- resource_group: group1 - \- location: eastus - \- frontend_ip_configurations: - \- name: lb1_feip1 - public_ip_address: pub_ip1 - \- backend_address_pools: - \- name: lb1_bepool1 - \- probes: - \- name: lb1_webprobe1 - protocol: tcp - port: 80 - interval_in_seconds: 5 - number_of_probes: 2 - \- load_balancing_rules: - \- name: lb1_webprobe1 - protocol: tcp - frontend_port: 80 - backend_port: 80 - idle_timeout_in_minutes: 4 - frontend_ip_configuration: lb1_feip1 - backend_address_pool: lb1_bepool1 - probe: lb1_webprobe1 - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists - \- azurearm_network: Ensure public IP exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.network_interface_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a network interface does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the network interface. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the network interface. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.network_interface_present(name, ip_configurations, subnet, virtual_network, resource_group, tags=None, virtual_machine=None, network_security_group=None, dns_settings=None, mac_address=None, primary=None, enable_accelerated_networking=None, enable_ip_forwarding=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a network interface exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the network interface. -.IP \(bu 2 -\fBip_configurations\fP \-\- A list of dictionaries representing valid NetworkInterfaceIPConfiguration objects. The \(aqname\(aq key is required at -minimum. At least one IP Configuration must be present. -.IP \(bu 2 -\fBsubnet\fP \-\- Name of the existing subnet assigned to the network interface. -.IP \(bu 2 -\fBvirtual_network\fP \-\- Name of the existing virtual network containing the subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the virtual network. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the network interface object. -.IP \(bu 2 -\fBnetwork_security_group\fP \-\- The name of the existing network security group to assign to the network interface. -.IP \(bu 2 -\fBvirtual_machine\fP \-\- The name of the existing virtual machine to assign to the network interface. -.IP \(bu 2 -\fBdns_settings\fP \-\- -.sp -An optional dictionary representing a valid NetworkInterfaceDnsSettings object. Valid parameters are: -.INDENT 2.0 -.IP \(bu 2 -\fBdns_servers\fP: List of DNS server IP addresses. Use \(aqAzureProvidedDNS\(aq to switch to Azure provided DNS -resolution. \(aqAzureProvidedDNS\(aq value cannot be combined with other IPs, it must be the only value in -dns_servers collection. -.IP \(bu 2 -\fBinternal_dns_name_label\fP: Relative DNS name for this NIC used for internal communications between VMs in -the same virtual network. -.IP \(bu 2 -\fBinternal_fqdn\fP: Fully qualified DNS name supporting internal communications between VMs in the same virtual -network. -.IP \(bu 2 -\fBinternal_domain_name_suffix\fP: Even if internal_dns_name_label is not specified, a DNS entry is created for -the primary NIC of the VM. This DNS name can be constructed by concatenating the VM name with the value of -internal_domain_name_suffix. -.UNINDENT - -.IP \(bu 2 -\fBmac_address\fP \-\- Optional string containing the MAC address of the network interface. -.IP \(bu 2 -\fBprimary\fP \-\- Optional boolean allowing the interface to be set as the primary network interface on a virtual machine -with multiple interfaces attached. -.IP \(bu 2 -\fBenable_accelerated_networking\fP \-\- Optional boolean indicating whether accelerated networking should be enabled for the interface. -.IP \(bu 2 -\fBenable_ip_forwarding\fP \-\- Optional boolean indicating whether IP forwarding should be enabled for the interface. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure network interface exists: - azurearm_network.network_interface_present: - \- name: iface1 - \- subnet: vnet1_sn1 - \- virtual_network: vnet1 - \- resource_group: group1 - \- ip_configurations: - \- name: iface1_ipc1 - public_ip_address: pub_ip2 - \- dns_settings: - internal_dns_name_label: decisionlab\-int\-test\-label - \- primary: True - \- enable_accelerated_networking: True - \- enable_ip_forwarding: False - \- network_security_group: nsg1 - \- connection_auth: {{ profile }} - \- require: - \- azurearm_network: Ensure subnet exists - \- azurearm_network: Ensure network security group exists - \- azurearm_network: Ensure another public IP exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.network_security_group_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a network security group does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the network security group. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the network security group. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.network_security_group_present(name, resource_group, tags=None, security_rules=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a network security group exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the network security group. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the network security group. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the network security group object. -.IP \(bu 2 -\fBsecurity_rules\fP \-\- An optional list of dictionaries representing valid SecurityRule objects. See the -documentation for the security_rule_present state or security_rule_create_or_update execution module -for more information on required and optional parameters for security rules. The rules are only -managed if this parameter is present. When this parameter is absent, implemented rules will not be removed, -and will merely become unmanaged. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure network security group exists: - azurearm_network.network_security_group_present: - \- name: nsg1 - \- resource_group: group1 - \- security_rules: - \- name: nsg1_rule1 - priority: 100 - protocol: tcp - access: allow - direction: outbound - source_address_prefix: virtualnetwork - destination_address_prefix: internet - source_port_range: \(aq*\(aq - destination_port_range: \(aq*\(aq - \- name: nsg1_rule2 - priority: 101 - protocol: tcp - access: allow - direction: inbound - source_address_prefix: internet - destination_address_prefix: virtualnetwork - source_port_range: \(aq*\(aq - destination_port_ranges: - \- \(aq80\(aq - \- \(aq443\(aq - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.public_ip_address_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a public IP address does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the public IP address. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the public IP address. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.public_ip_address_present(name, resource_group, tags=None, sku=None, public_ip_allocation_method=None, public_ip_address_version=None, dns_settings=None, idle_timeout_in_minutes=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a public IP address exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the public IP address. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the public IP address. -.IP \(bu 2 -\fBdns_settings\fP \-\- An optional dictionary representing a valid PublicIPAddressDnsSettings object. Parameters include -\(aqdomain_name_label\(aq and \(aqreverse_fqdn\(aq, which accept strings. The \(aqdomain_name_label\(aq parameter is concatenated -with the regionalized DNS zone make up the fully qualified domain name associated with the public IP address. -If a domain name label is specified, an A DNS record is created for the public IP in the Microsoft Azure DNS -system. The \(aqreverse_fqdn\(aq parameter is a user\-visible, fully qualified domain name that resolves to this public -IP address. If the reverse FQDN is specified, then a PTR DNS record is created pointing from the IP address in -the in\-addr.arpa domain to the reverse FQDN. -.IP \(bu 2 -\fBsku\fP \-\- The public IP address SKU, which can be \(aqBasic\(aq or \(aqStandard\(aq. -.IP \(bu 2 -\fBpublic_ip_allocation_method\fP \-\- The public IP allocation method. Possible values are: \(aqStatic\(aq and \(aqDynamic\(aq. -.IP \(bu 2 -\fBpublic_ip_address_version\fP \-\- The public IP address version. Possible values are: \(aqIPv4\(aq and \(aqIPv6\(aq. -.IP \(bu 2 -\fBidle_timeout_in_minutes\fP \-\- An integer representing the idle timeout of the public IP address. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the public IP address object. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure public IP exists: - azurearm_network.public_ip_address_present: - \- name: pub_ip1 - \- resource_group: group1 - \- dns_settings: - domain_name_label: decisionlab\-ext\-test\-label - \- sku: basic - \- public_ip_allocation_method: static - \- public_ip_address_version: ipv4 - \- idle_timeout_in_minutes: 4 - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.route_absent(name, route_table, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a route table does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the route table. -.IP \(bu 2 -\fBroute_table\fP \-\- The name of the existing route table containing the route. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the route table. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.route_present(name, address_prefix, next_hop_type, route_table, resource_group, next_hop_ip_address=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a route exists within a route table. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the route. -.IP \(bu 2 -\fBaddress_prefix\fP \-\- The destination CIDR to which the route applies. -.IP \(bu 2 -\fBnext_hop_type\fP \-\- The type of Azure hop the packet should be sent to. Possible values are: \(aqVirtualNetworkGateway\(aq, \(aqVnetLocal\(aq, -\(aqInternet\(aq, \(aqVirtualAppliance\(aq, and \(aqNone\(aq. -.IP \(bu 2 -\fBnext_hop_ip_address\fP \-\- The IP address packets should be forwarded to. Next hop values are only allowed in routes where the next hop -type is \(aqVirtualAppliance\(aq. -.IP \(bu 2 -\fBroute_table\fP \-\- The name of the existing route table which will contain the route. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the route table. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure route exists: - azurearm_network.route_present: - \- name: rt1_route2 - \- route_table: rt1 - \- resource_group: group1 - \- address_prefix: \(aq192.168.0.0/16\(aq - \- next_hop_type: vnetlocal - \- connection_auth: {{ profile }} - \- require: - \- azurearm_network: Ensure route table exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.route_table_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a route table does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the route table. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the route table. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.route_table_present(name, resource_group, tags=None, routes=None, disable_bgp_route_propagation=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a route table exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the route table. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the route table. -.IP \(bu 2 -\fBroutes\fP \-\- An optional list of dictionaries representing valid Route objects contained within a route table. See the -documentation for the route_present state or route_create_or_update execution module for more information on -required and optional parameters for routes. The routes are only managed if this parameter is present. When this -parameter is absent, implemented routes will not be removed, and will merely become unmanaged. -.IP \(bu 2 -\fBdisable_bgp_route_propagation\fP \-\- An optional boolean parameter setting whether to disable the routes learned by BGP on the route table. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the route table object. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure route table exists: - azurearm_network.route_table_present: - \- name: rt1 - \- resource_group: group1 - \- routes: - \- name: rt1_route1 - address_prefix: \(aq0.0.0.0/0\(aq - next_hop_type: internet - \- name: rt1_route2 - address_prefix: \(aq192.168.0.0/16\(aq - next_hop_type: vnetlocal - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.security_rule_absent(name, security_group, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a security rule does not exist in the network security group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the security rule. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The network security group containing the security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the network security group. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.security_rule_present(name, access, direction, priority, protocol, security_group, resource_group, destination_address_prefix=None, destination_port_range=None, source_address_prefix=None, source_port_range=None, description=None, destination_address_prefixes=None, destination_port_ranges=None, source_address_prefixes=None, source_port_ranges=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a security rule exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the security rule. -.IP \(bu 2 -\fBaccess\fP \-\- \(aqallow\(aq or \(aqdeny\(aq -.IP \(bu 2 -\fBdirection\fP \-\- \(aqinbound\(aq or \(aqoutbound\(aq -.IP \(bu 2 -\fBpriority\fP \-\- Integer between 100 and 4096 used for ordering rule application. -.IP \(bu 2 -\fBprotocol\fP \-\- \(aqtcp\(aq, \(aqudp\(aq, or \(aq*\(aq -.IP \(bu 2 -\fBsecurity_group\fP \-\- The name of the existing network security group to contain the security rule. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the network security group. -.IP \(bu 2 -\fBdescription\fP \-\- Optional description of the security rule. -.IP \(bu 2 -\fBdestination_address_prefix\fP \-\- The CIDR or destination IP range. Asterix \(aq*\(aq can also be used to match all destination IPs. -Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. -If this is an ingress rule, specifies where network traffic originates from. -.IP \(bu 2 -\fBdestination_port_range\fP \-\- The destination port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq -can also be used to match all ports. -.IP \(bu 2 -\fBsource_address_prefix\fP \-\- The CIDR or source IP range. Asterix \(aq*\(aq can also be used to match all source IPs. -Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. -If this is an ingress rule, specifies where network traffic originates from. -.IP \(bu 2 -\fBsource_port_range\fP \-\- The source port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq -can also be used to match all ports. -.IP \(bu 2 -\fBdestination_address_prefixes\fP \-\- A list of destination_address_prefix values. This parameter overrides destination_address_prefix -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBdestination_port_ranges\fP \-\- A list of destination_port_range values. This parameter overrides destination_port_range -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBsource_address_prefixes\fP \-\- A list of source_address_prefix values. This parameter overrides source_address_prefix -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBsource_port_ranges\fP \-\- A list of source_port_range values. This parameter overrides source_port_range -and will cause any value entered there to be ignored. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure security rule exists: - azurearm_network.security_rule_present: - \- name: nsg1_rule2 - \- security_group: nsg1 - \- resource_group: group1 - \- priority: 101 - \- protocol: tcp - \- access: allow - \- direction: inbound - \- source_address_prefix: internet - \- destination_address_prefix: virtualnetwork - \- source_port_range: \(aq*\(aq - \- destination_port_ranges: - \- \(aq80\(aq - \- \(aq443\(aq - \- connection_auth: {{ profile }} - \- require: - \- azurearm_network: Ensure network security group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.subnet_absent(name, virtual_network, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a virtual network does not exist in the virtual network. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the subnet. -.IP \(bu 2 -\fBvirtual_network\fP \-\- Name of the existing virtual network containing the subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the virtual network. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.subnet_present(name, address_prefix, virtual_network, resource_group, security_group=None, route_table=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a subnet exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the subnet. -.IP \(bu 2 -\fBaddress_prefix\fP \-\- A CIDR block used by the subnet within the virtual network. -.IP \(bu 2 -\fBvirtual_network\fP \-\- Name of the existing virtual network to contain the subnet. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the virtual network. -.IP \(bu 2 -\fBsecurity_group\fP \-\- The name of the existing network security group to assign to the subnet. -.IP \(bu 2 -\fBroute_table\fP \-\- The name of the existing route table to assign to the subnet. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure subnet exists: - azurearm_network.subnet_present: - \- name: vnet1_sn1 - \- virtual_network: vnet1 - \- resource_group: group1 - \- address_prefix: \(aq192.168.1.0/24\(aq - \- security_group: nsg1 - \- route_table: rt1 - \- connection_auth: {{ profile }} - \- require: - \- azurearm_network: Ensure virtual network exists - \- azurearm_network: Ensure network security group exists - \- azurearm_network: Ensure route table exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.virtual_network_absent(name, resource_group, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a virtual network does not exist in the resource group. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the virtual network. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the virtual network. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_network.virtual_network_present(name, address_prefixes, resource_group, dns_servers=None, tags=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a virtual network exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the virtual network. -.IP \(bu 2 -\fBresource_group\fP \-\- The resource group assigned to the virtual network. -.IP \(bu 2 -\fBaddress_prefixes\fP \-\- A list of CIDR blocks which can be used by subnets within the virtual network. -.IP \(bu 2 -\fBdns_servers\fP \-\- A list of DNS server addresses. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the virtual network object. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure virtual network exists: - azurearm_network.virtual_network_present: - \- name: vnet1 - \- resource_group: group1 - \- address_prefixes: - \- \(aq10.0.0.0/8\(aq - \- \(aq192.168.0.0/16\(aq - \- dns_servers: - \- \(aq8.8.8.8\(aq - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - \- require: - \- azurearm_resource: Ensure resource group exists -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.SS salt.states.azurearm_resource -.sp -Azure (ARM) Resource State Module -.sp -New in version 2019.2.0. - -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This cloud provider will be removed from Salt in version 3007 in favor of -the \fI\%saltext.azurerm Salt Extension\fP -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B maintainer -<\fI\%devops@eitr.tech\fP> -.TP -.B maturity -new -.TP -.B depends -.INDENT 7.0 -.IP \(bu 2 -\fI\%azure\fP >= 2.0.0 -.IP \(bu 2 -\fI\%azure\-common\fP >= 1.1.8 -.IP \(bu 2 -\fI\%azure\-mgmt\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-compute\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-network\fP >= 1.7.1 -.IP \(bu 2 -\fI\%azure\-mgmt\-resource\fP >= 1.1.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-storage\fP >= 1.0.0 -.IP \(bu 2 -\fI\%azure\-mgmt\-web\fP >= 0.32.0 -.IP \(bu 2 -\fI\%azure\-storage\fP >= 0.34.3 -.IP \(bu 2 -\fI\%msrestazure\fP >= 0.4.21 -.UNINDENT -.TP -.B platform -linux -.TP -.B configuration -This module requires Azure Resource Manager credentials to be passed as a dictionary of -keyword arguments to the \fBconnection_auth\fP parameter in order to work properly. Since the authentication -parameters are sensitive, it\(aqs recommended to pass them to the states via pillar. -.sp -Required provider parameters: -.INDENT 7.0 -.TP -.B if using username and password: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBusername\fP -.IP \(bu 2 -\fBpassword\fP -.UNINDENT -.TP -.B if using a service principal: -.INDENT 7.0 -.IP \(bu 2 -\fBsubscription_id\fP -.IP \(bu 2 -\fBtenant\fP -.IP \(bu 2 -\fBclient_id\fP -.IP \(bu 2 -\fBsecret\fP -.UNINDENT -.UNINDENT -.sp -Optional provider parameters: -.INDENT 7.0 -.TP -\fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: -.INDENT 7.0 -.IP \(bu 2 -\fBAZURE_PUBLIC_CLOUD\fP (default) -.IP \(bu 2 -\fBAZURE_CHINA_CLOUD\fP -.IP \(bu 2 -\fBAZURE_US_GOV_CLOUD\fP -.IP \(bu 2 -\fBAZURE_GERMAN_CLOUD\fP -.UNINDENT -.UNINDENT -.sp -Example Pillar for Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -azurearm: - user_pass_auth: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - username: fletch - password: 123pass - mysubscription: - subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 - tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF - secret: XXXXXXXXXXXXXXXXXXXXXXXX - cloud_environment: AZURE_PUBLIC_CLOUD -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Example states using Azure Resource Manager authentication: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -{% set profile = salt[\(aqpillar.get\(aq](\(aqazurearm:mysubscription\(aq) %} -Ensure resource group exists: - azurearm_resource.resource_group_present: - \- name: my_rg - \- location: westus - \- tags: - how_awesome: very - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} - -Ensure resource group is absent: - azurearm_resource.resource_group_absent: - \- name: other_rg - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.policy_assignment_absent(name, scope, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a policy assignment does not exist in the provided scope. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the policy assignment. -.IP \(bu 2 -\fBscope\fP \-\- The scope of the policy assignment. -.UNINDENT -.UNINDENT -.INDENT 7.0 -.TP -.B connection_auth -A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.policy_assignment_present(name, scope, definition_name, display_name=None, description=None, assignment_type=None, parameters=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a security policy assignment exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the policy assignment. -.IP \(bu 2 -\fBscope\fP \-\- The scope of the policy assignment. -.IP \(bu 2 -\fBdefinition_name\fP \-\- The name of the policy definition to assign. -.IP \(bu 2 -\fBdisplay_name\fP \-\- The display name of the policy assignment. -.IP \(bu 2 -\fBdescription\fP \-\- The policy assignment description. -.IP \(bu 2 -\fBassignment_type\fP \-\- The type of policy assignment. -.IP \(bu 2 -\fBparameters\fP \-\- Required dictionary if a parameter is used in the policy rule. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure policy assignment exists: - azurearm_resource.policy_assignment_present: - \- name: testassign - \- scope: /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 - \- definition_name: testpolicy - \- display_name: Test Assignment - \- description: Test assignment for testing assignments. - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.policy_definition_absent(name, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a policy definition does not exist in the current subscription. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the policy definition. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.policy_definition_present(name, policy_rule=None, policy_type=None, mode=None, display_name=None, description=None, metadata=None, parameters=None, policy_rule_json=None, policy_rule_file=None, template=\(aqjinja\(aq, source_hash=None, source_hash_name=None, skip_verify=False, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a security policy definition exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the policy definition. -.IP \(bu 2 -\fBpolicy_rule\fP \-\- A YAML dictionary defining the policy rule. See \fI\%Azure Policy Definition documentation\fP for details on the -structure. One of \fBpolicy_rule\fP, \fBpolicy_rule_json\fP, or \fBpolicy_rule_file\fP is required, in that order of -precedence for use if multiple parameters are used. -.IP \(bu 2 -\fBpolicy_rule_json\fP \-\- -.sp -A text field defining the entirety of a policy definition in JSON. See \fI\%Azure Policy Definition documentation\fP for details on the -structure. One of \fBpolicy_rule\fP, \fBpolicy_rule_json\fP, or \fBpolicy_rule_file\fP is required, in that order of -precedence for use if multiple parameters are used. Note that the \fIname\fP field in the JSON will override the -\fBname\fP parameter in the state. - -.IP \(bu 2 -\fBpolicy_rule_file\fP \-\- -.sp -The source of a JSON file defining the entirety of a policy definition. See \fI\%Azure Policy Definition -documentation\fP for -details on the structure. One of \fBpolicy_rule\fP, \fBpolicy_rule_json\fP, or \fBpolicy_rule_file\fP is required, -in that order of precedence for use if multiple parameters are used. Note that the \fIname\fP field in the JSON -will override the \fBname\fP parameter in the state. - -.IP \(bu 2 -\fBskip_verify\fP \-\- Used for the \fBpolicy_rule_file\fP parameter. If \fBTrue\fP, hash verification of remote file sources -(\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP) will be skipped, and the \fBsource_hash\fP argument will be ignored. -.IP \(bu 2 -\fBsource_hash\fP \-\- This can be a source hash string or the URI of a file that contains source hash strings. -.IP \(bu 2 -\fBsource_hash_name\fP \-\- When \fBsource_hash\fP refers to a hash file, Salt will try to find the correct hash by matching the -filename/URI associated with that hash. -.IP \(bu 2 -\fBpolicy_type\fP \-\- The type of policy definition. Possible values are NotSpecified, BuiltIn, and Custom. Only used with the -\fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBmode\fP \-\- The policy definition mode. Possible values are NotSpecified, Indexed, and All. Only used with the -\fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBdisplay_name\fP \-\- The display name of the policy definition. Only used with the \fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBdescription\fP \-\- The policy definition description. Only used with the \fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBmetadata\fP \-\- The policy definition metadata defined as a dictionary. Only used with the \fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBparameters\fP \-\- Required dictionary if a parameter is used in the policy rule. Only used with the \fBpolicy_rule\fP parameter. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure policy definition exists: - azurearm_resource.policy_definition_present: - \- name: testpolicy - \- display_name: Test Policy - \- description: Test policy for testing policies. - \- policy_rule: - if: - allOf: - \- equals: Microsoft.Compute/virtualMachines/write - source: action - \- field: location - in: - \- eastus - \- eastus2 - \- centralus - then: - effect: deny - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.resource_group_absent(name, connection_auth=None) -New in version 2019.2.0. - -.sp -Ensure a resource group does not exist in the current subscription. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the resource group. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.states.azurearm_resource.resource_group_present(name, location, managed_by=None, tags=None, connection_auth=None, **kwargs) -New in version 2019.2.0. - -.sp -Ensure a resource group exists. -.INDENT 7.0 -.TP -.B Parameters -.INDENT 7.0 -.IP \(bu 2 -\fBname\fP \-\- Name of the resource group. -.IP \(bu 2 -\fBlocation\fP \-\- The Azure location in which to create the resource group. This value cannot be updated once -the resource group is created. -.IP \(bu 2 -\fBmanaged_by\fP \-\- The ID of the resource that manages this resource group. This value cannot be updated once -the resource group is created. -.IP \(bu 2 -\fBtags\fP \-\- A dictionary of strings can be passed as tag metadata to the resource group object. -.IP \(bu 2 -\fBconnection_auth\fP \-\- A dict with subscription and authentication parameters to be used in connecting to the -Azure Resource Manager API. -.UNINDENT -.UNINDENT -.sp -Example usage: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -Ensure resource group exists: - azurearm_resource.resource_group_present: - \- name: group1 - \- location: eastus - \- tags: - contact_name: Elmer Fudd Gantry - \- connection_auth: {{ profile }} -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT .SS salt.states.beacon .SS Management of the Salt beacons .sp @@ -403671,13 +395897,13 @@ mappedname: \- size=256 swap: - crypted.mapped: + cryptdev.mapped: \- device: /dev/sdx4 \- keyfile: /dev/urandom \- opts: swap,cipher=aes\-cbc\-essiv:sha256,size=256 mappedbyuuid: - crypted.mapped: + cryptdev.mapped: \- device: UUID=066e0200\-2867\-4ebe\-b9e6\-f30026ca2314 \- keyfile: /etc/keyfile.key \- config: /etc/alternate\-crypttab @@ -404869,6 +397095,14 @@ Set to \fITrue\fP to evaluate the free space instead. .UNINDENT .SS salt.states.docker_container .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Docker containers .sp New in version 2017.7.0. @@ -407368,6 +399602,14 @@ containers are absent. Set this to \fBFalse\fP to suppress that error. .UNINDENT .SS salt.states.docker_image .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Docker images .sp New in version 2017.7.0. @@ -407704,6 +399946,14 @@ Additional keyword arguments to pass to .UNINDENT .SS salt.states.docker_network .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Docker networks .sp New in version 2017.7.0. @@ -408352,6 +400602,14 @@ mynet: .UNINDENT .SS salt.states.docker_volume .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%docker Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Docker volumes .sp New in version 2017.7.0. @@ -411987,7 +404245,7 @@ text 4 .UNINDENT .INDENT 0.0 .TP -.B salt.states.file.cached(name, source_hash=\(aq\(aq, source_hash_name=None, skip_verify=False, saltenv=\(aqbase\(aq, use_etag=False) +.B salt.states.file.cached(name, source_hash=\(aq\(aq, source_hash_name=None, skip_verify=False, saltenv=\(aqbase\(aq, use_etag=False, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None) New in version 2017.7.3. .sp @@ -412059,6 +404317,54 @@ the \fBsource_hash\fP parameter. .sp New in version 3005. +.TP +.B source_hash_sig +When \fBname\fP is a remote file source, \fBsource_hash\fP is a file, +\fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a +valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature on the \fBsource_hash\fP file is enforced regardless of +changes since its contents are used to check if an existing file +is in the correct state \- but only for remote sources! +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying \fBsource_hash_sig\fP, require at least one valid signature +from one of a list of key fingerprints. This is passed to +\fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying \fBsource_hash_sig\fP, require a valid signature from each +of the key fingerprints in this list. This is passed to +\fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying signatures, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying signatures, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .sp This state will in most cases not be useful in SLS files, but it is useful @@ -412808,7 +405114,7 @@ permissions for those directories. .UNINDENT .INDENT 0.0 .TP -.B salt.states.file.keyvalue(name, key=None, value=None, key_values=None, separator=\(aq=\(aq, append_if_not_found=False, prepend_if_not_found=False, search_only=False, show_changes=True, ignore_if_missing=False, count=1, uncomment=None, key_ignore_case=False, value_ignore_case=False) +.B salt.states.file.keyvalue(name, key=None, value=None, key_values=None, separator=\(aq=\(aq, append_if_not_found=False, prepend_if_not_found=False, search_only=False, show_changes=True, ignore_if_missing=False, count=1, uncomment=None, key_ignore_case=False, value_ignore_case=False, create_if_missing=False) Key/Value based editing of a file. .sp New in version 3001. @@ -412893,6 +405199,12 @@ key is kept as\-is. Values are checked case insensitively, trying to set e.g. \(aqYes\(aq while the current value is \(aqyes\(aq, will not result in changes when \fBvalue_ignore_case\fP is set to True. +.TP +.B create_if_missing +Create the file if the destination file is not found. +.sp +New in version 3007.0. + .UNINDENT .sp An example of using \fBfile.keyvalue\fP to ensure sshd does not allow @@ -413357,7 +405669,7 @@ line present to be present in between \fBbefore\fP and \fBafter\fP\&. .UNINDENT .INDENT 0.0 .TP -.B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, source_hash_name=None, keep_source=True, user=None, group=None, mode=None, attrs=None, template=None, makedirs=False, dir_mode=None, context=None, replace=True, defaults=None, backup=\(aq\(aq, show_changes=True, create=True, contents=None, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, contents_pillar=None, contents_grains=None, contents_newline=True, contents_delimiter=\(aq:\(aq, encoding=None, encoding_errors=\(aqstrict\(aq, allow_empty=True, follow_symlinks=True, check_cmd=None, skip_verify=False, selinux=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, verify_ssl=True, use_etag=False, **kwargs) +.B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, source_hash_name=None, keep_source=True, user=None, group=None, mode=None, attrs=None, template=None, makedirs=False, dir_mode=None, context=None, replace=True, defaults=None, backup=\(aq\(aq, show_changes=True, create=True, contents=None, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, contents_pillar=None, contents_grains=None, contents_newline=True, contents_delimiter=\(aq:\(aq, encoding=None, encoding_errors=\(aqstrict\(aq, allow_empty=True, follow_symlinks=True, check_cmd=None, skip_verify=False, selinux=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False, verify_ssl=True, use_etag=False, signature=None, source_hash_sig=None, signed_by_any=None, signed_by_all=None, keyring=None, gnupghome=None, **kwargs) Manage a given file, this function allows for a file to be downloaded from the salt master and potentially run through a templating system. .INDENT 7.0 @@ -413830,6 +406142,17 @@ be used instead. However, this will not work for binary files in Salt releases before 2015.8.4. .UNINDENT .UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For information on using Salt Slots and how to incorporate +execution module returns into file content or data, refer to the +\fI\%Salt Slots documentation\fP\&. +.UNINDENT +.UNINDENT +.INDENT 7.0 .TP .B contents_grains New in version 2014.7.0. @@ -414129,6 +406452,80 @@ the \fBsource_hash\fP parameter. .sp New in version 3005. +.TP +.B signature +Ensure a valid GPG signature exists on the selected \fBsource\fP file. +Set this to true for inline signatures, or to a file URI retrievable +by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature is only enforced directly after caching the file, +before it is moved to its final destination. Existing target files +(with the correct checksum) will neither be checked nor deleted. +.sp +It will be enforced regardless of source type and will be +required on the final output, therefore this does not lend itself +well when templates are rendered. +The file will not be modified, meaning inline signatures are not +removed. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B source_hash_sig +When \fBsource\fP is a remote file source, \fBsource_hash\fP is a file, +\fBskip_verify\fP is not true and \fBuse_etag\fP is not true, ensure a +valid GPG signature exists on the source hash file. +Set this to \fBtrue\fP for an inline (clearsigned) signature, or to a +file URI retrievable by \fI:py:func:\(gacp.cache_file \fP +for a detached one. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +A signature on the \fBsource_hash\fP file is enforced regardless of +changes since its contents are used to check if an existing file +is in the correct state \- but only for remote sources! +As for \fBsignature\fP, existing target files will not be modified, +only the cached source_hash and source_hash_sig files will be removed. +.UNINDENT +.UNINDENT +.sp +New in version 3007.0. + +.TP +.B signed_by_any +When verifying signatures either on the managed file or its source hash file, +require at least one valid signature from one of a list of key fingerprints. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B signed_by_all +When verifying signatures either on the managed file or its source hash file, +require a valid signature from each of the key fingerprints in this list. +This is passed to \fI\%gpg.verify\fP\&. +.sp +New in version 3007.0. + +.TP +.B keyring +When verifying signatures, use this keyring. +.sp +New in version 3007.0. + +.TP +.B gnupghome +When verifying signatures, use this GnuPG home. +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .INDENT 0.0 @@ -414240,8 +406637,8 @@ state argument for supported state functions. It should not be called directly. .B salt.states.file.mod_run_check_cmd(cmd, filename, **check_cmd_opts) Execute the check_cmd logic. .sp -Return a result dict if \fBcheck_cmd\fP succeeds (check_cmd == 0) -otherwise return True +Return True if \fBcheck_cmd\fP succeeds (check_cmd == 0) +otherwise return a result dict .UNINDENT .INDENT 0.0 .TP @@ -414438,10 +406835,10 @@ may specify a single line of text or a list of lines to append. .INDENT 7.0 .TP .B name -The location of the file to append to. +The location of the file to prepend to. .TP .B text -The text to be appended, which can be a single string or a list +The text to be prepended, which can be a single string or a list of strings. .TP .B makedirs @@ -414451,7 +406848,7 @@ the parent directories will be created to facilitate the creation of the named file. Defaults to False. .TP .B source -A single source file to append. This source file can be hosted on either +A single source file to prepend. This source file can be hosted on either the salt master server, or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre\-configured and automatic IAM credentials @@ -414502,7 +406899,7 @@ md5 32 See the \fBsource_hash\fP parameter description for \fI\%file.managed\fP function for more details and examples. .TP .B template -The named templating engine will be used to render the appended\-to file. +The named templating engine will be used to render the source file(s). Defaults to \fBjinja\fP\&. The following templates are supported: .INDENT 7.0 .IP \(bu 2 @@ -414520,7 +406917,7 @@ Defaults to \fBjinja\fP\&. The following templates are supported: .UNINDENT .TP .B sources -A list of source files to append. If the files are hosted on an HTTP or +A list of source files to prepend. If the files are hosted on an HTTP or FTP server, the source_hashes argument is also required. .TP .B source_hashes @@ -414540,6 +406937,10 @@ New in version 2015.8.4. Spaces and Tabs in text are ignored by default, when searching for the appending content, one space or multiple tabs are the same for salt. Set this option to \fBFalse\fP if you want to change this behavior. +.TP +.B header +Forces the text to be prepended. If it exists in the file but not at +the beginning, then it prepends a duplicate. .UNINDENT .sp Multi\-line example: @@ -415192,7 +407593,7 @@ Usage example: .UNINDENT .INDENT 0.0 .TP -.B salt.states.file.serialize(name, dataset=None, dataset_pillar=None, user=None, group=None, mode=None, backup=\(aq\(aq, makedirs=False, show_changes=True, create=True, merge_if_exists=False, encoding=None, encoding_errors=\(aqstrict\(aq, serializer=None, serializer_opts=None, deserializer_opts=None, **kwargs) +.B salt.states.file.serialize(name, dataset=None, dataset_pillar=None, user=None, group=None, mode=None, backup=\(aq\(aq, makedirs=False, show_changes=True, create=True, merge_if_exists=False, encoding=None, encoding_errors=\(aqstrict\(aq, serializer=None, serializer_opts=None, deserializer_opts=None, check_cmd=None, tmp_dir=\(aq\(aq, tmp_ext=\(aq\(aq, **kwargs) Serializes dataset and store it into managed file. Useful for sharing simple configuration files. .INDENT 7.0 @@ -415212,6 +407613,17 @@ causing indentation mismatches. .sp New in version 2015.8.0. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For information on using Salt Slots and how to incorporate +execution module returns into file content or data, refer to the +\fI\%Salt Slots documentation\fP\&. +.UNINDENT +.UNINDENT +.INDENT 7.0 .TP .B serializer (or formatter) Write the data as this format. See the list of @@ -415362,6 +407774,61 @@ which accept a callable object cannot be handled in an SLS file. .sp New in version 2019.2.0. +.TP +.B check_cmd +The specified command will be run with an appended argument of a +\fItemporary\fP file containing the new file contents. If the command +exits with a zero status the new file contents will be written to +the state output destination. If the command exits with a nonzero exit +code, the state will fail and no changes will be made to the file. +.sp +For example, the following could be used to verify sudoers before making +changes: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +/etc/consul.d/my_config.json: + file.serialize: + \- dataset: + datacenter: \(dqeast\-aws\(dq + data_dir: \(dq/opt/consul\(dq + log_level: \(dqINFO\(dq + node_name: \(dqfoobar\(dq + server: true + watches: + \- type: checks + handler: \(dq/usr/bin/health\-check\-handler.sh\(dq + telemetry: + statsite_address: \(dq127.0.0.1:2180\(dq + \- serializer: json + \- check_cmd: consul validate +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE\fP: This \fBcheck_cmd\fP functions differently than the requisite +\fBcheck_cmd\fP\&. +.sp +New in version 3007.0. + +.TP +.B tmp_dir +Directory for temp file created by \fBcheck_cmd\fP\&. Useful for checkers +dependent on config file location (e.g. daemons restricted to their +own config directories by an apparmor profile). +.sp +New in version 3007.0. + +.TP +.B tmp_ext +Suffix for temp file created by \fBcheck_cmd\fP\&. Useful for checkers +dependent on config file extension. +.sp +New in version 3007.0. + .UNINDENT .sp For example, this state: @@ -415467,7 +407934,7 @@ process. For existing files and directories it\(aqs not enforced. .UNINDENT .INDENT 0.0 .TP -.B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=None, atomic=False, disallow_copy_and_unlink=False, inherit_user_and_group=False, **kwargs) +.B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=None, atomic=False, disallow_copy_and_unlink=False, inherit_user_and_group=False, follow_symlinks=True, **kwargs) Create a symbolic link (symlink, soft link) .sp If the file already exists and is a symlink pointing to any location other @@ -415578,6 +408045,14 @@ override this behavior. .sp New in version 3006.0. +.TP +.B follow_symlinks (bool): +If set to \fBFalse\fP, the underlying \fBfile.symlink\fP execution module +and any checks in this state will use \fBos.path.lexists()\fP for +existence checks instead of \fBos.path.exists()\fP\&. +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .INDENT 0.0 @@ -415994,7 +408469,7 @@ Returns a pretty dictionary meant for command line output. .UNINDENT .INDENT 0.0 .TP -.B salt.states.firewalld.present(name, block_icmp=None, prune_block_icmp=False, default=None, masquerade=False, ports=None, prune_ports=False, port_fwd=None, prune_port_fwd=False, services=None, prune_services=False, interfaces=None, prune_interfaces=False, sources=None, prune_sources=False, rich_rules=None, prune_rich_rules=False) +.B salt.states.firewalld.present(name, block_icmp=None, prune_block_icmp=False, default=None, masquerade=None, ports=None, prune_ports=False, port_fwd=None, prune_port_fwd=False, services=None, prune_services=False, interfaces=None, prune_interfaces=False, sources=None, prune_sources=False, rich_rules=None, prune_rich_rules=False) Ensure a zone has specific attributes. .INDENT 7.0 .TP @@ -416006,8 +408481,8 @@ None Set this zone as the default zone if \fBTrue\fP\&. .TP .B masquerade -False -Enable or disable masquerade for a zone. +None +Enable or disable masquerade for a zone. By default it will not change it. .TP .B block_icmp None @@ -417895,55 +410370,76 @@ desktop_lockdown: sets values in the org.gnome.desktop.lockdown schema wm_preferences: sets values in the org.gnome.desktop.wm.preferences schema .UNINDENT .SS salt.states.gpg -.SS Management of the GPG keychains +.SS Manage GPG keychains .sp New in version 2016.3.0. .INDENT 0.0 .TP -.B salt.states.gpg.absent(name, keys=None, user=None, gnupghome=None, **kwargs) -Ensure GPG public key is absent in keychain +.B salt.states.gpg.absent(name, keys=None, user=None, gnupghome=None, keyring=None, keyring_absent_if_empty=False, **kwargs) +Ensure a GPG public key is absent from the keychain. .INDENT 7.0 .TP .B name -The unique name or keyid for the GPG public key. +The key ID of the GPG public key. .TP .B keys -The keyId or keyIds to add to the GPG keychain. +The key ID or key IDs to remove from the GPG keychain. .TP .B user -Remove GPG keys from the specified user\(aqs keychain +Remove GPG keys from the specified user\(aqs keychain. .TP .B gnupghome -Override GNUPG Home directory +Override GnuPG home directory. +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + +.TP +.B keyring_absent_if_empty +Make sure to not leave behind an empty keyring file +if \fBkeyring\fP was specified. Defaults to false. +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.states.gpg.present(name, keys=None, user=None, keyserver=None, gnupghome=None, trust=None, **kwargs) -Ensure GPG public key is present in keychain +.B salt.states.gpg.present(name, keys=None, user=None, keyserver=None, gnupghome=None, trust=None, keyring=None, **kwargs) +Ensure a GPG public key is present in the GPG keychain. .INDENT 7.0 .TP .B name -The unique name or keyid for the GPG public key. +The key ID of the GPG public key. .TP .B keys -The keyId or keyIds to add to the GPG keychain. +The key ID or key IDs to add to the GPG keychain. .TP .B user -Add GPG keys to the specified user\(aqs keychain +Add GPG keys to the specified user\(aqs keychain. .TP .B keyserver The keyserver to retrieve the keys from. .TP .B gnupghome -Override GNUPG Home directory +Override GnuPG home directory. .TP .B trust Trust level for the key in the keychain, -ignored by default. Valid trust levels: +ignored by default. Valid trust levels: expired, unknown, not_trusted, marginally, fully, ultimately +.TP +.B keyring +Limit the operation to this specific keyring, specified as +a local filesystem path. +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .SS salt.states.grafana @@ -419185,12 +411681,24 @@ cheese: .UNINDENT .INDENT 0.0 .TP -.B salt.states.group.absent(name) +.B salt.states.group.absent(name, local=False) Ensure that the named group is absent .INDENT 7.0 .TP .B Parameters +.INDENT 7.0 +.IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the group to remove +.IP \(bu 2 +\fBlocal\fP (\fIOnly on systems with lgroupdel available\fP) \-\- +.sp +Ensure the group account is removed locally ignoring global +account management (default is False). +.sp +New in version 3007.0. + + +.UNINDENT .UNINDENT .sp Example: @@ -419209,7 +411717,7 @@ db_admin: .UNINDENT .INDENT 0.0 .TP -.B salt.states.group.present(name, gid=None, system=False, addusers=None, delusers=None, members=None, non_unique=False) +.B salt.states.group.present(name, gid=None, system=False, addusers=None, delusers=None, members=None, non_unique=False, local=False) Changed in version 3006.0. .sp @@ -419245,6 +411753,15 @@ Allow creating groups with duplicate (non\-unique) GIDs New in version 3006.0. +.IP \(bu 2 +\fBlocal\fP (\fIOnly on systems with lgroupadd available\fP) \-\- +.sp +Create the group account locally ignoring global account management +(default is False). +.sp +New in version 3007.0. + + .UNINDENT .UNINDENT .sp @@ -424264,6 +416781,14 @@ New in version 2016.3.0. .UNINDENT .UNINDENT .SS salt.states.kubernetes +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%kubernetes Salt Extension\fP\&. +.UNINDENT +.UNINDENT .SS Manage kubernetes resources as salt states .sp NOTE: This module requires the proper pillar values set. See @@ -425462,6 +417987,23 @@ root: .UNINDENT .UNINDENT .sp +Ensure a Linux ACL is present as a default for all new objects +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +root: + acl.present: + \- name: /root + \- acl_type: \(dqdefault:user\(dq + \- acl_name: damian + \- perms: rwx +.ft P +.fi +.UNINDENT +.UNINDENT +.sp Ensure a Linux ACL does not exist .INDENT 0.0 .INDENT 3.5 @@ -425516,6 +418058,26 @@ root: .fi .UNINDENT .UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The effective permissions of Linux file access control lists (ACLs) are +governed by the \(dqeffective rights mask\(dq (the \fImask\fP line in the output of +the \fIgetfacl\fP command) combined with the \fIperms\fP set by this module: any +permission bits (for example, r=read) present in an ACL but not in the mask +are ignored. The mask is automatically recomputed when setting an ACL, so +normally this isn\(aqt important. However, if the file permissions are +changed (with \fIchmod\fP or \fIfile.managed\fP, for example), the mask will +generally be set based on just the group bits of the file permissions. +.sp +As a result, when using \fIfile.managed\fP or similar to control file +permissions as well as this module, you should set your group permissions +to be at least as broad as any permissions in your ACL. Otherwise, the two +state declarations will each register changes each run, and if the \fIfile\fP +declaration runs later, your ACL will be ineffective. +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B salt.states.linux_acl.absent(name, acl_type, acl_name=\(aq\(aq, perms=\(aq\(aq, recurse=False) @@ -436833,8 +429395,7 @@ Make sure the package is installed .B name The name of the python package to install. You can also specify version numbers here using the standard operators \fB==, >=, <=\fP\&. If -\fBrequirements\fP is given, this parameter will be ignored. -.UNINDENT +\fBrequirements\fP or \fBpkgs\fP is given, this parameter will be ignored. .sp Example: .INDENT 7.0 @@ -436852,9 +429413,33 @@ django: .UNINDENT .UNINDENT .sp -This will install the latest Django version greater than 1.6 but less +Installs the latest Django version greater than 1.6 but less than 1.7. +.TP +.B pkgs +A list of python packages to install. This let you install multiple +packages at the same time. +.sp +Example: .INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +django\-and\-psycopg2: + pip.installed: + \- pkgs: + \- django >= 1.6, <= 1.7 + \- psycopg2 >= 2.8.4 + \- require: + \- pkg: python\-pip +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Installs the latest Django version greater than 1.6 but less than 1.7 +and the latest psycopg2 greater than 2.8.4 at the same time. .TP .B requirements Path to a pip requirements file. If the path begins with salt:// @@ -437271,7 +429856,7 @@ done to keep systemd from killing the package manager commands spawned by Salt, when Salt updates itself (see \fBKillMode\fP in the \fI\%systemd.kill(5)\fP manpage for more information). If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fI\%config option\fP -called \fBsystemd.use_scope\fP, with a value of \fBFalse\fP (no quotes). +called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .UNINDENT .UNINDENT .sp @@ -437673,6 +430258,9 @@ By default, this parameter is set to \fBFalse\fP\&. .INDENT 0.0 .TP .B salt.states.pkg.installed(name, version=None, refresh=None, fromrepo=None, skip_verify=False, skip_suggestions=False, pkgs=None, sources=None, allow_updates=False, pkg_verify=False, normalize=True, ignore_epoch=None, reinstall=False, update_holds=False, **kwargs) +Changed in version 3007.0. + +.sp Ensure that the package is installed, and that it is the correct version (if specified). .sp @@ -437706,6 +430294,16 @@ Any argument that is passed through to the \fBinstall\fP function, which is not defined for that function, will be silently ignored. .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +In Windows, some packages are installed using the task manager. The Salt +minion installer does this. In that case, there is no way to know if the +package installs correctly. All that can be reported is that the task +that launches the installer started successfully. +.UNINDENT +.UNINDENT .INDENT 7.0 .TP .B Parameters @@ -438585,6 +431183,9 @@ small reductions in waiting time can add up. .INDENT 0.0 .TP .B salt.states.pkg.latest(name, refresh=None, fromrepo=None, skip_verify=False, pkgs=None, watch_flags=True, **kwargs) +Changed in version 3007.0. + +.sp Ensure that the named package is installed and the latest available package. If the package can be updated, this state function will update the package. Generally it is better for the @@ -440307,7 +432908,18 @@ The name of the database to manage Default tablespace for the database .TP .B encoding -The character encoding scheme to be used in this database +The character encoding scheme to be used in this database. The encoding +has to be defined in the following format (without hyphen). +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +\- encoding: UTF8 +.ft P +.fi +.UNINDENT +.UNINDENT .TP .B lc_collate The LC_COLLATE setting to be used in this database @@ -441628,6 +434240,14 @@ macOS .UNINDENT .UNINDENT .SS salt.states.pushover +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%pushover Salt Extension\fP\&. +.UNINDENT +.UNINDENT .SS Send a message to PushOver .sp This state is useful for sending messages to PushOver during state runs. @@ -444460,6 +437080,24 @@ sync_everything: .UNINDENT .INDENT 0.0 .TP +.B salt.states.saltutil.sync_tops(name, **kwargs) +Performs the same task as saltutil.sync_tops module +See \fI\%saltutil module for full list of options\fP +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +sync_everything: + saltutil.sync_tops: + \- refresh: True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.states.saltutil.sync_utils(name, **kwargs) Performs the same task as saltutil.sync_utils module See \fI\%saltutil module for full list of options\fP @@ -444476,6 +437114,27 @@ sync_everything: .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.states.saltutil.sync_wrapper(name, **kwargs) +New in version 3007.0. + +.sp +Performs the same task as saltutil.sync_wrapper module +See \fI\%saltutil module for full list of options\fP +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +sync_everything: + saltutil.sync_wrapper: + \- refresh: True +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.states.schedule .SS Management of the Salt scheduler .INDENT 0.0 @@ -444773,6 +437432,9 @@ period ends. .TP .B offline Add the scheduled job to the Salt minion when the Salt minion is not running. +.sp +New in version 3006.3. + .UNINDENT .UNINDENT .SS salt.states.selinux @@ -447888,7 +440550,7 @@ is\-pillar\-foo\-present\-and\-bar\-is\-int: .UNINDENT .INDENT 0.0 .TP -.B salt.states.test.configurable_test_state(name, changes=True, result=True, comment=\(aq\(aq, warnings=None) +.B salt.states.test.configurable_test_state(name, changes=True, result=True, comment=\(aq\(aq, warnings=None, allow_test_mode_failure=False) New in version 2014.7.0. .sp @@ -447955,6 +440617,14 @@ Default is None .sp New in version 3000. +.TP +.B allow_test_mode_failure +When False, running this state in test mode can only return a True +or None result. When set to True and result is set to False, the +test mode result will be False. Default is False +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .INDENT 0.0 @@ -448705,11 +441375,9 @@ Example tuned.sls file to set profile to virtual\-guest .B tuned: .INDENT 7.0 .TP -.B tuned: +.B tuned.profile .INDENT 7.0 .IP \(bu 2 -profile -.IP \(bu 2 name: virtual\-guest .UNINDENT .UNINDENT @@ -448806,7 +441474,7 @@ testuser: .UNINDENT .INDENT 0.0 .TP -.B salt.states.user.absent(name, purge=False, force=False) +.B salt.states.user.absent(name, purge=False, force=False, local=False) Ensure that the named user is absent .INDENT 7.0 .TP @@ -448821,11 +441489,18 @@ Default is \fBFalse\fP\&. If the user is logged in, the absent state will fail. Set the force option to True to remove the user even if they are logged in. Not supported in FreeBSD and Solaris, Default is \fBFalse\fP\&. +.TP +.B local (Only on systems with luserdel available): +Ensure the user account is removed locally ignoring global account management +(default is False). +.sp +New in version 3007.0. + .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.states.user.present(name, uid=None, gid=None, usergroup=None, groups=None, optional_groups=None, remove_groups=True, home=None, createhome=True, password=None, hash_password=False, enforce_password=True, empty_password=False, shell=None, unique=True, system=False, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None, loginclass=None, date=None, mindays=None, maxdays=None, inactdays=None, warndays=None, expire=None, win_homedrive=None, win_profile=None, win_logonscript=None, win_description=None, nologinit=False, allow_uid_change=False, allow_gid_change=False, password_lock=None) +.B salt.states.user.present(name, uid=None, gid=None, usergroup=None, groups=None, optional_groups=None, remove_groups=True, home=None, createhome=True, password=None, hash_password=False, enforce_password=True, empty_password=False, shell=None, unique=True, system=False, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None, loginclass=None, date=None, mindays=None, maxdays=None, inactdays=None, warndays=None, expire=None, win_homedrive=None, win_profile=None, win_logonscript=None, win_description=None, nologinit=False, allow_uid_change=False, allow_gid_change=False, password_lock=None, local=False) Ensure that the named user is present with the specified properties .INDENT 7.0 .TP @@ -449026,6 +441701,13 @@ Number of days prior to maxdays to warn users. .B expire Date that account expires, represented in days since epoch (January 1, 1970). +.TP +.B local (Only on systems with luseradd available): +Create the user account locally ignoring global account management +(default is False). +.sp +New in version 3007.0. + .UNINDENT .sp The below parameters apply to windows only: @@ -449344,8 +442026,17 @@ node_name: .UNINDENT .SS salt.states.vault .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%vault Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp States for managing Hashicorp Vault. -Currently handles policies. Configuration instructions are documented in the execution module docs. +Currently handles policies. +Configuration instructions are documented in the \fI\%execution module docs\fP\&. .INDENT 0.0 .TP .B maintainer @@ -449360,6 +442051,16 @@ all .sp New in version 2017.7.0. +.INDENT 0.0 +.TP +.B salt.states.vault.policy_absent(name) +Ensure a Vault policy with the given name and rules is absent. +.INDENT 7.0 +.TP +.B name +The name of the policy +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B salt.states.vault.policy_present(name, rules) @@ -451879,6 +444580,94 @@ Update an existing user\(aqs password if it\(aqs different from what\(aqs in the htpasswd file (unlike force, which updates regardless) .UNINDENT .UNINDENT +.SS salt.states.win_appx +.sp +Manage Microsoft Store apps on Windows. Removing an app with this modules will +deprovision the app from the online Windows image. +.sp +New in version 3007.0. + +.INDENT 0.0 +.TP +.B salt.states.win_appx.absent(name, query, include_store=False, frameworks=False, deprovision_only=False) +Removes Microsoft Store packages from the system. If the package is part of +a bundle, the entire bundle will be removed. +.sp +This function removes the package for all users on the system. It also +deprovisions the package so that it isn\(aqt re\-installed by later system +updates. To only deprovision a package and not remove it for all users, set +\fBdeprovision_only=True\fP\&. +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBquery\fP (\fI\%str\fP) \-\- +.sp +The query string to use to select the packages to be removed. If the +string matches multiple packages, they will all be removed. Here are +some example strings: +.nf +string | description | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\- | +\fB*teams*\fP | Remove Microsoft Teams | +\fB*zune*\fP | Remove Windows Media Player and Zune Video | +\fB*zuneMusic*\fP | Only remove Windows Media Player | +\fB*xbox*\fP | Remove all xBox packages, there are 5 by default +\fB*\fP | Remove everything but the Microsoft Store, unless \fBinclude_store=True\fP | +.fi +.sp +.sp +\fBNOTE:\fP +.INDENT 2.0 +.INDENT 3.5 +Use the \fBappx.list\fP function to make sure your query is +returning what you expect. Then use the same query to remove +those packages +.UNINDENT +.UNINDENT + +.IP \(bu 2 +\fBinclude_store\fP (\fI\%bool\fP) \-\- Include the Microsoft Store in the results of the query to be +removed. Use this with caution. It is difficult to reinstall the +Microsoft Store once it has been removed with this function. Default +is \fBFalse\fP +.IP \(bu 2 +\fBframeworks\fP (\fI\%bool\fP) \-\- Include frameworks in the results of the query to be removed. +Default is \fBFalse\fP +.IP \(bu 2 +\fBdeprovision_only\fP (\fI\%bool\fP) \-\- Only deprovision the package. The package will be removed from the +current user and added to the list of deprovisioned packages. The +package will not be re\-installed in future system updates. New users +of the system will not have the package installed. However, the +package will still be installed for existing users. Default is +\fBFalse\fP +.UNINDENT +.TP +.B Returns +\fBTrue\fP if successful, \fBNone\fP if no packages found +.TP +.B Return type +\fI\%bool\fP +.TP +.B Raises +\fI\%CommandExecutionError\fP \-\- On errors encountered removing the package +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +remove_candy_crush: + appx.absent: + \- query: \(dq*candy*\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.states.win_certutil .SS Installing of certificates to the Windows Certificate Manager .sp @@ -452107,7 +444896,7 @@ Ensure an ACE is present .SS salt.states.win_dism .SS Installing of Windows features using DISM .sp -Install windows features/capabilties with DISM +Install Windows features, capabilities, and packages with DISM .INDENT 0.0 .INDENT 3.5 .sp @@ -452135,12 +444924,11 @@ Install a DISM capability .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The optional source of the capability .IP \(bu 2 -\fBlimit_access\fP (\fI\%bool\fP) \-\- Prevent DISM from contacting Windows Update for -online images +\fBlimit_access\fP (\fI\%bool\fP) \-\- Prevent DISM from contacting Windows Update for online images .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT @@ -452149,7 +444937,7 @@ targeted. Default is None. Example .sp Run \fBdism.available_capabilities\fP to get a list of available -capabilities. This will help you get the proper name to use. +capabilities. This will help you get the proper name to use .INDENT 7.0 .INDENT 3.5 .sp @@ -452174,19 +444962,18 @@ Uninstall a DISM capability .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The capability to uninstall .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 -\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the -uninstall +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .UNINDENT .sp Example .sp Run \fBdism.installed_capabilities\fP to get a list of installed -capabilities. This will help you get the proper name to use. +capabilities. This will help you get the proper name to use .INDENT 7.0 .INDENT 3.5 .sp @@ -452211,21 +444998,19 @@ Install a DISM feature .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The feature in which to install .IP \(bu 2 -\fBpackage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The parent package for the feature. You do not -have to specify the package if it is the Windows Foundation Package. -Otherwise, use package to specify the parent package of the feature +\fBpackage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The parent package for the feature. You do not have to specify the +package if it is the Windows Foundation Package. Otherwise, use +package to specify the parent package of the feature .IP \(bu 2 \fBsource\fP (\fI\%str\fP) \-\- The optional source of the feature .IP \(bu 2 -\fBlimit_access\fP (\fI\%bool\fP) \-\- Prevent DISM from contacting Windows Update for -online images +\fBlimit_access\fP (\fI\%bool\fP) \-\- Prevent DISM from contacting Windows Update for online images .IP \(bu 2 -\fBenable_parent\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- True will enable all parent features of -the specified feature +\fBenable_parent\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- \fBTrue\fP will enable all parent features of the specified feature .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT @@ -452234,7 +445019,7 @@ targeted. Default is None. Example .sp Run \fBdism.available_features\fP to get a list of available features. -This will help you get the proper name to use. +This will help you get the proper name to use .INDENT 7.0 .INDENT 3.5 .sp @@ -452259,22 +445044,21 @@ Disables a feature. .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The feature to disable .IP \(bu 2 -\fBremove_payload\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Remove the feature\(aqs payload. Must -supply source when enabling in the future. +\fBremove_payload\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Remove the feature\(aqs payload. Must supply source when enabling in +the future. .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 -\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the -uninstall +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .UNINDENT .sp Example .sp Run \fBdism.installed_features\fP to get a list of installed features. -This will help you get the proper name to use. +This will help you get the proper name to use .INDENT 7.0 .INDENT 3.5 .sp @@ -452301,15 +445085,13 @@ New in version 3006.0. .B Parameters .INDENT 7.0 .IP \(bu 2 -\fBname\fP (\fI\%str\fP) \-\- The name of the KB. Can be with or without the KB at the -beginning. +\fBname\fP (\fI\%str\fP) \-\- The name of the KB. Can be with or without the KB at the beginning .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 -\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the -uninstall +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .UNINDENT .sp @@ -452342,18 +445124,16 @@ Install a package. .B Parameters .INDENT 7.0 .IP \(bu 2 -\fBname\fP (\fI\%str\fP) \-\- The package to install. Can be a .cab file, a .msu file, -or a folder +\fBname\fP (\fI\%str\fP) \-\- The package to install. Can be a .cab file, a .msu file, or a folder .IP \(bu 2 -\fBignore_check\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip installation of the package if the -applicability checks fail +\fBignore_check\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip installation of the package if the applicability checks fail .IP \(bu 2 -\fBprevent_pending\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip the installation of the package -if there are pending online actions +\fBprevent_pending\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Skip the installation of the package if there are pending online +actions .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 \fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the install .UNINDENT @@ -452382,17 +445162,16 @@ Uninstall a package .B Parameters .INDENT 7.0 .IP \(bu 2 -\fBname\fP (\fI\%str\fP) \-\- The full path to the package. Can be either a .cab file or a -folder. Should point to the original source of the package, not to -where the file is installed. This can also be the name of a package as listed in -\fBdism.installed_packages\fP +\fBname\fP (\fI\%str\fP) \-\- The full path to the package. Can be either a .cab file or a folder. +Should point to the original source of the package, not to where the +file is installed. This can also be the name of a package as listed +in \fBdism.installed_packages\fP .IP \(bu 2 -\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline -Windows image. If \fINone\fP is passed, the running operating system is -targeted. Default is None. +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP .IP \(bu 2 -\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the -uninstall +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the uninstall .UNINDENT .UNINDENT .sp @@ -452416,6 +445195,58 @@ remove_KB1231231: .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.states.win_dism.provisioned_package_installed(name, image=None, restart=False) +Provision a package on a Windows image. +.sp +New in version 3007.0. + +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBname\fP (\fI\%str\fP) \-\- +.sp +The package to install. Can be one of the following: +.INDENT 2.0 +.IP \(bu 2 +\fB\&.appx\fP or \fB\&.appxbundle\fP +.IP \(bu 2 +\fB\&.msix\fP or \fB\&.msixbundle\fP +.IP \(bu 2 +\fB\&.ppkg\fP +.UNINDENT +.sp +The name of the file before the file extension must match the name +of the package after it is installed. This name can be found by +running \fBdism.provisioned_packages\fP + +.IP \(bu 2 +\fBimage\fP (\fIOptional\fP\fI[\fP\fI\%str\fP\fI]\fP) \-\- The path to the root directory of an offline Windows image. If +\fBNone\fP is passed, the running operating system is targeted. +Default is \fBNone\fP +.IP \(bu 2 +\fBrestart\fP (\fIOptional\fP\fI[\fP\fI\%bool\fP\fI]\fP) \-\- Reboot the machine if required by the installation. Default is +\fBFalse\fP +.UNINDENT +.UNINDENT +.sp +Example +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +install_windows_media_player: + dism.provisioned_package_installed: + \- name: C:\ePackages\eMicrosoft.ZuneVideo_2019.22091.10036.0_neutral_~_8wekyb3d8bbwe.Msixbundle +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.states.win_dns_client .sp Module for configuring DNS Client on Windows systems @@ -455409,6 +448240,118 @@ set workgroup: .UNINDENT .UNINDENT .UNINDENT +.SS salt.states.win_task +.sp +State module for adding and removing scheduled tasks using the Windows Task +Scheduler. +.INDENT 0.0 +.TP +.B salt.states.win_task.absent(name, location=\(aq\e\e\(aq) +Delete a task from the task scheduler. +.sp +New in version 3007.0. + +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBname\fP (\fI\%str\fP) \-\- The name of the task to delete. +.IP \(bu 2 +\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task. +Default is \(dq\e\(dq which is the root for the task scheduler +(C:WindowsSystem32tasks). +.UNINDENT +.TP +.B Returns +\fBTrue\fP if successful, otherwise \fBFalse\fP +.TP +.B Return type +\fI\%bool\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +test_win_task_absent: + task.absent: + \- name: salt + \- location: \(dq\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.states.win_task.present(name, location=\(aq\e\e\(aq, user_name=\(aqSystem\(aq, password=None, force=False, **kwargs) +Create a new task in the designated location. This function has many keyword +arguments that are not listed here. For additional arguments see: +.sp +New in version 3007.0. + +.INDENT 7.0 +.IP \(bu 2 +\fBedit_task()\fP +.IP \(bu 2 +\fBadd_action()\fP +.IP \(bu 2 +\fBadd_trigger()\fP +.UNINDENT +.INDENT 7.0 +.TP +.B Parameters +.INDENT 7.0 +.IP \(bu 2 +\fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task +scheduler. +.IP \(bu 2 +\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to +create the task. Default is \(dq\e\(dq which is the root for the task +scheduler (C:WindowsSystem32tasks). +.IP \(bu 2 +\fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To +specify the \(dqSystem\(dq account, use \(dqSystem\(dq. The password will be +ignored. +.IP \(bu 2 +\fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set +the task to run whether the user is logged in or not, but is +currently not working. +.IP \(bu 2 +\fBforce\fP (\fI\%bool\fP) \-\- Overwrite the existing task. +.UNINDENT +.TP +.B Returns +A dictionary containing the results of the state +.TP +.B Return type +\fI\%dict\fP +.UNINDENT +.sp +CLI Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +test_win_task_present: + task.present: + \- name: salt + \- location: \(dq\(dq + \- force: True + \- action_type: Execute + \- cmd: \(dqdel /Q /S C:\e\eTemp\(dq + \- trigger_type: Once + \- start_date: 12\-1\-16 + \- start_time: 01:00 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT .SS salt.states.win_wua .sp Installation of Windows Updates using the Windows Update Agent @@ -457194,6 +450137,14 @@ The message to send to the XMPP user .UNINDENT .SS salt.states.zabbix_action .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix Action object over Zabbix API. .sp New in version 2017.7.0. @@ -457295,6 +450246,14 @@ zabbix\-action\-present: .UNINDENT .SS salt.states.zabbix_host .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix hosts. .INDENT 0.0 .TP @@ -457447,6 +450406,14 @@ create_test_host: .UNINDENT .SS salt.states.zabbix_hostgroup .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix host groups. .INDENT 0.0 .TP @@ -457523,6 +450490,14 @@ create_testing_host_group: .UNINDENT .SS salt.states.zabbix_mediatype .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix mediatypes. .INDENT 0.0 .TP @@ -457600,6 +450575,14 @@ make_new_mediatype: .UNINDENT .SS salt.states.zabbix_template .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp New in version 2017.7.0. .sp @@ -457832,6 +450815,14 @@ zabbix\-template\-present: .UNINDENT .SS salt.states.zabbix_user .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix users. .INDENT 0.0 .TP @@ -457997,6 +450988,14 @@ make_user: .UNINDENT .SS salt.states.zabbix_usergroup .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix user groups. .INDENT 0.0 .TP @@ -458079,6 +451078,14 @@ make_new_thai_monks_usergroup: .UNINDENT .SS salt.states.zabbix_usermacro .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix usermacros. :codeauthor: Raymond Kuiper <\fI\%qix@the\-wired.net\fP> .INDENT 0.0 @@ -458153,6 +451160,14 @@ override host usermacro: .UNINDENT .SS salt.states.zabbix_valuemap .sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This module will be removed from Salt in version 3009 in favor of +the \fI\%zabbix Salt Extension\fP\&. +.UNINDENT +.UNINDENT +.sp Management of Zabbix Valuemap object over Zabbix API. .sp New in version 2017.7.0. @@ -462168,7 +455183,7 @@ The key to return information about. .sp .nf .ft C ->>> wheel.cmd(\(aqkey.key_str\(aq, [\(aqminion1\(aq]) +>>> wheel.cmd(\(aqkey.print\(aq, [\(aqminion1\(aq]) {\(aqminions\(aq: {\(aqminion1\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\enMIIBIjANBgkqhkiG9w0B \&... TWugEQpPt\eniQIDAQAB\en\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq}} @@ -464093,6 +457108,19 @@ your deployment as needed for redundancy, geographical distribution, and scale. Salt supports several features for high availability and fault tolerance. Brief documentation for these features is listed alongside their configuration parameters in \fI\%Configuration file examples\fP\&. +.SS Master Cluster +.sp +New in version 3007. + +.sp +Salt masters can be configured to act as a cluster. All masters in a cluster +are peers. Job workloads are shared accross the cluster. Master clusters +provide a way to scale masters horizontally. They do not require changes to +the minions\(aq configuration to add more resources. Cluster implementations are +expected to use a load balancer, shared filesystem, and run on a reliable +network. +.sp +\fI\%Master Cluster Tutorial\fP .SS Multimaster .sp Salt minions can connect to multiple masters at one time by configuring the @@ -464590,6 +457618,128 @@ file\-in\-user\-home: .fi .UNINDENT .UNINDENT +.SS Example Usage +.sp +In Salt, slots are a powerful feature that allows you to populate information +dynamically within your Salt states. One of the best use cases for slots is when +you need to reference data that is created or modified during the course of a +Salt run. +.sp +Consider the following example, where we aim to add a user named \(aqfoobar\(aq to a +group named \(aqknown_users\(aq with specific user and group IDs. To achieve this, we +utilize slots to retrieve the group ID of \(aqknown_users\(aq as it is created or +modified during the Salt run. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +add_group_known_users: + group.present: + \- name: known_users + +add_user: + user.present: + \- name: foobar + \- uid: 600 + \- gid: __slot__:salt:group.info(\(dqknown_users\(dq).gid + \- require: + \- group: add_group_known_users +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In this example, the \fBadd_group_known_users\fP state ensures the presence of the +\(aqknown_users\(aq group. Then, within the \fBadd_user\fP state, we use the slot +\fB__slot__:salt:group.info(\(dqknown_users\(dq).gid\fP to dynamically retrieve the +group ID of \(aqknown_users,\(aq which may have been modified during the execution of +the previous state. This approach ensures that our user \(aqfoobar\(aq is associated +with the correct group, even if the group information changes during the Salt +run. +.sp +Slots offer a flexible way to work with changing data and dynamically populate +your Salt states, making your configurations adaptable and robust. +.SS Execution module returns as file contents or data +.sp +The following examples demonstrate how to use execution module returns as file +contents or data in Salt states. These examples show how to incorporate the +output of execution functions into file contents or data in the \fIfile.managed\fP +and \fIfile.serialize\fP states. +.SS Content from execution modules +.sp +You can use the results of execution modules directly as file contents in Salt +states. This can be useful for dynamically generating file content based on the +output of execution functions. +.sp +\fBExample 1: Using \(gatest.echo\(ga Output as File Content\fP +.sp +The following Salt state uses the \fItest.echo\fP execution function to generate the +text \(dqhello world.\(dq This output is then used as the content of the file +\fI/tmp/things.txt\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +content\-from\-slots: + file.managed: + \- name: /tmp/things.txt + \- contents: __slot__:salt:test.echo(\(dqhello world\(dq) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBExample 2: Using Multiple \(gatest.echo\(ga Outputs as Appended Content\fP +.sp +In this example, two \fItest.echo\fP execution functions are used to generate +\(dqhello\(dq and \(dqworld\(dq strings. These strings are then joined by newline characters +and then used as the content of the file \fI/tmp/things.txt\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +content\-from\-multiple\-slots: + file.managed: + \- name: /tmp/things.txt + \- contents: + \- __slot__:salt:test.echo(\(dqhello\(dq) + \- __slot__:salt:test.echo(\(dqworld\(dq) +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Serializing data from execution modules +.sp +You can also serialize data obtained from execution modules and write it to +files using Salt states. This allows you to capture and store structured data +for later use. +.sp +\fBExample: Serializing \(gagrains.items()\(ga Output to JSON\fP +.sp +In this example, the \fIgrains.items()\fP execution function retrieves system +information. The obtained data is then serialized into JSON format and saved to +the file \fI/tmp/grains.json\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +serialize\-dataset\-from\-slots: + file.serialize: + \- name: /tmp/grains.json + \- serializer: json + \- dataset: __slot__:salt:grains.items() +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +These examples showcase how to leverage Salt\(aqs flexibility to use execution +module returns as file contents or serialized data in your Salt states, allowing +for dynamic and customized configurations. .SH WINDOWS .sp This section contains details on the Windows Package Manager, and specific information you need @@ -464825,92 +457975,196 @@ ssm.exe set ObjectName \(dq.\e\(dq \(dq\(dq .SS Windows Package Manager .SS Introduction .sp -The Windows Package Manager provides a software repository and a package manager -similar to what is provided by \fByum\fP and \fBapt\fP on Linux. This tool enables -the installation of software on remote Windows systems. +Salt provides a Windows package management tool for installing, updating, +removing, and managing software packages on remote Windows systems. This tool +provides a software repository and a package manager similar to what is provided +by \fByum\fP and \fBapt\fP on Linux. The repository contains a collection of package +definition files. +.SS What are package definition files? .sp -The repository contains a collection of software definition files. A software -definition file is a YAML/JINJA file with an \fB\&.sls\fP file extension. It -contains all the information Salt needs to install a software package on a -Windows system, including the download location of the installer, required -command\-line switches for silent install, etc. -.sp -Software definition files can be hosted in one or more Git repositories. The -default repository is hosted on GitHub by SaltStack. It is maintained by -SaltStack and the Salt community and contains software definition files for many -common Windows packages. Anyone is welcome to submit a pull request to this -repo to add new software definitions. The default github repository is: +A package definition file is a YAML/JINJA2 file with a \fB\&.sls\fP file extension +that contains all the information needed to install software using Salt. It +defines: .INDENT 0.0 .IP \(bu 2 +Full name of the software package +.IP \(bu 2 +The version of the software package +.IP \(bu 2 +Download location of the software package +.IP \(bu 2 +Command\-line switches for silent install and uninstall +.IP \(bu 2 +Whether or not to use the Windows task scheduler to install the package +.UNINDENT +.sp +Package definition files can be hosted in one or more Git repositories. The +\fB\&.sls\fP files used to install Windows packages are not distributed by default +with Salt. You have to initialize and clone the default repository \fI\%salt\-winrepo\-ng\fP -.UNINDENT +which is hosted on GitHub by SaltStack. The repository contains package +definition files for many common Windows packages and is maintained by SaltStack +and the Salt community. Anyone can submit a pull request to this repo to add +new package definitions. .sp -The Windows Package Manager is used the same way as other package managers Salt -is aware of. For example: +You can manage the package definition file through either Salt or Git. You can +download software packages from either a git repository or from HTTP(S) or FTP +URLs. You can store the installer defined in the package definition file +anywhere as long as it is accessible from the host running Salt. +.sp +You can use the Salt Windows package manager like \fByum\fP on Linux. You do not +have to know the underlying command to install the software. .INDENT 0.0 .IP \(bu 2 -the \fBpkg.installed\fP and similar states work on Windows. +Use \fBpkg.install\fP to install a package using a package manager based on +the OS the system runs on. .IP \(bu 2 -the \fBpkg.install\fP and similar module functions work on Windows. +Use \fBpkg.installed\fP to check if a particular package is installed in the +minion. .UNINDENT .sp -High level differences to \fByum\fP and \fBapt\fP are: +\fBNOTE:\fP .INDENT 0.0 -.IP \(bu 2 -The repository metadata (SLS files) can be managed through either Salt or git -.IP \(bu 2 -Packages can be downloaded from within the Salt repository, a git repository -or from HTTP(S) or FTP URLs -.IP \(bu 2 -No dependencies are managed. Dependencies between packages need to be managed -manually +.INDENT 3.5 +The Salt Windows package manager does not automatically resolve dependencies +while installing, updating, or removing packages. You have to manage the +dependencies between packages manually. .UNINDENT -.SS Requirements +.UNINDENT +.SS Quickstart .sp -If using the a software definition files hosted on a Git repo, the following -libraries are required: +This quickstart guides you through using the Windows Salt package manager +(winrepo) to install software packages in four steps: .INDENT 0.0 -.IP \(bu 2 -GitPython 0.3 or later -.sp -or -.IP \(bu 2 -pygit2 0.20.3 with libgit 0.20.0 or later +.IP 1. 3 +(Optional) \fI\%Install libraries\fP +.IP 2. 3 +\fI\%Populate the local Git repository\fP +.IP 3. 3 +\fI\%Update minion database\fP +.IP 4. 3 +\fI\%Install software packages\fP .UNINDENT -.SS Quick Start +.SS Install libraries .sp -You can get up and running with winrepo pretty quickly just using the defaults. -Assuming no changes to the default configuration (ie, \fBfile_roots\fP) run the -following commands on the master: +(Optional) If you are using the Salt Windows package manager with package +definition files hosted on a Salt Git repo, install the libraries \fBGitPython\fP +or \fBpygit2\fP\&. +.SS Populate the local Git repository +.sp +The SLS files used to install Windows packages are not distributed by default +with Salt. Assuming no changes to the default configuration (\fBfile_roots\fP), +initialize and clone \fI\%salt\-winrepo\-ng\fP +repository. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run winrepo.update_git_repos -salt * pkg.refresh_db -salt * pkg.install firefox_x64 .ft P .fi .UNINDENT .UNINDENT .sp -On a masterless minion run the following: +On successful execution of \fI\%winrepo.update_git_repos\fP, +the winrepo repository is cloned on the master in the location specified in +\fBwinrepo_dir_ng\fP and all package definition files are pulled down from the Git +repository. +.sp +On a masterless minion, use \fBsalt\-call\fP to initialize and clone the +\fI\%salt\-winrepo\-ng\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local winrepo.update_git_repos -salt\-call \-\-local pkg.refresh_db -salt\-call \-\-local pkg.install firefox_x64 .ft P .fi .UNINDENT .UNINDENT .sp -These commands clone the default winrepo from github, update the winrepo -database on the minion, and install the latest version of Firefox. +On successful execution of the runner, the winrepo repository is cloned on the +minion in the location specified in \fBwinrepo_dir_ng\fP and all package +definition files are pulled down from the Git repository. +.SS Update minion database +.sp +Run \fI\%pkg.refresh_db\fP on all Windows +minions to create a database entry for every package definition file and build +the package database. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# From the master +salt \-G \(aqos:windows\(aq pkg.refresh_db + +# From the minion in masterless mode +salt\-call \-\-local pkg.refresh_db +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fI\%pkg.refresh_db\fP command parses the +YAML/JINJA package definition files and generates the database. The above +command returns the following summary denoting the number of packages that +succeeded or failed to compile: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +local: + \-\-\-\-\-\-\-\-\-\- + failed: + 0 + success: + 301 + total: + 301 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This command can take a few minutes to complete as all the package +definition files are copied to the minion and the database is generated. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +You can use \fBpkg.refresh_db\fP when writing new Windows package definitions +to check for errors in the definitions against one or more Windows minions. +.UNINDENT +.UNINDENT +.SS Install software package +.sp +You can now install a software package using +\fI\%pkg.install\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# From the master +salt * pkg.install \(aqfirefox_x64\(aq + +# From the minion in masterless mode +salt\-call \-\-local pkg.install \(dqfirefox_x64\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The above command installs the latest version of Firefox on the minions. .SS Configuration .sp The Github repository (winrepo) is synced to the \fBfile_roots\fP in a location @@ -464924,7 +458178,7 @@ Masterless minion: \fBC:\esalt\esrv\esalt\ewin\erepo\-ng\fP (\fBsalt://win/repo\ .UNINDENT .SS Master Configuration .sp -The following are settings are available for configuring the winrepo on the +The following settings are available for configuring the winrepo on the master: .INDENT 0.0 .IP \(bu 2 @@ -464963,8 +458217,8 @@ is \fB/srv/salt/win/repo\-ng\fP\&. .INDENT 0.0 .INDENT 3.5 You can change the location of the winrepo directory. However, it must -always be set to a path that is inside the \fBfile_roots\fP\&. -Otherwise the software definition files will be unreachable by the minion. +always be set to a path that is inside the \fBfile_roots\fP\&. Otherwise, the +software definition files will be unreachable by the minion. .UNINDENT .UNINDENT .sp @@ -465001,7 +458255,7 @@ winrepo_remotes: [] .sp \fI\%winrepo_remotes_ng\fP (list) .sp -This setting tells the \fBwinrepo.upgate_git_repos\fP command where the next +This setting tells the \fBwinrepo.update_git_repos\fP command where the next generation winrepo is hosted. This a list of URLs to multiple git repos. The default is a list containing a single URL: .sp @@ -465103,20 +458357,20 @@ minions whether in masterless mode or not. \fI\%winrepo_cache_expire_max\fP (int) .sp Sets the maximum age in seconds of the winrepo metadata file to avoid it -becoming stale. If the metadata file is older than this setting it will trigger +becoming stale. If the metadata file is older than this setting, it will trigger a \fBpkg.refresh_db\fP on the next run of any \fBpkg\fP module function that requires the metadata file. Default is 604800 (1 week). .sp Software package definitions are automatically refreshed if stale after -\fI\%winrepo_cache_expire_max\fP\&. Running a highstate normal forces the -refresh of the package definition and generation of the metadata, unless -the metadata is younger than \fI\%winrepo_cache_expire_max\fP\&. +\fI\%winrepo_cache_expire_max\fP\&. Running a highstate forces the refresh +of the package definitions and regenerates the metadata, unless the metadata is +younger than \fI\%winrepo_cache_expire_max\fP\&. .SS winrepo_cache_expire_min .sp \fI\%winrepo_cache_expire_min\fP (int) .sp Sets the minimum age in seconds of the winrepo metadata file to avoid refreshing -too often. If the metadata file is older than this setting the metadata will be +too often. If the metadata file is older than this setting, the metadata will be refreshed unless you pass \fBrefresh: False\fP in the state. Default is 1800 (30 min). .SS winrepo_cachefile @@ -465136,16 +458390,16 @@ different environments. Default is \fBsalt://win/repo\-ng/\fP\&. .INDENT 0.0 .INDENT 3.5 If the default for \fBwinrepo_dir_ng\fP is changed, this setting may need to -changed on each minion. The default setting for \fBwinrepo_dir_ng\fP is -\fB/srv/salt/win/repo\-ng\fP\&. If that were changed to \fB/srv/salt/new/repo\-ng\fP -then the \fBwinrepo_source_dir\fP would need to be changed to -\fBsalt://new/repo\-ng\fP +be changed on each minion. The default setting for \fBwinrepo_dir_ng\fP is +\fB/srv/salt/win/repo\-ng\fP\&. If that were changed to +\fB/srv/salt/new/repo\-ng\fP, then the \fBwinrepo_source_dir\fP would need to be +changed to \fBsalt://new/repo\-ng\fP .UNINDENT .UNINDENT .SS Masterless Minion Configuration .sp -The following are settings are available for configuring the winrepo on a -masterless minion: +The following settings are available for configuring the winrepo on a masterless +minion: .INDENT 0.0 .IP \(bu 2 \fI\%winrepo_dir\fP @@ -465170,15 +458424,15 @@ The default is: \fBC:\esalt\esrv\esalt\ewin\erepo\fP .sp \fI\%winrepo_dir_ng\fP (str) .sp -The location in the \fBfile_roots where the winrepo files are kept. The default -is \(ga\(gaC:\esalt\esrv\esalt\ewin\erepo\-ng\fP\&. +The location in the \fBfile_roots\fP where the winrepo files are kept. The default +is \fBC:\esalt\esrv\esalt\ewin\erepo\-ng\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 You can change the location of the winrepo directory. However, it must -always be set to a path that is inside the \fBfile_roots\fP\&. -Otherwise the software definition files will be unreachable by the minion. +always be set to a path that is inside the \fBfile_roots\fP\&. Otherwise, the +software definition files will be unreachable by the minion. .UNINDENT .UNINDENT .sp @@ -465216,134 +458470,15 @@ winrepo_remotes: [] .sp \fI\%winrepo_remotes_ng\fP (list) .sp -This setting tells the \fBwinrepo.upgate_git_repos\fP command where the next +This setting tells the \fBwinrepo.update_git_repos\fP command where the next generation winrepo is hosted. This a list of URLs to multiple git repos. The default is a list containing a single URL: .sp \fI\%https://github.com/saltstack/salt\-winrepo\-ng\fP -.SS Initialization -.SS Populate the Local Repository -.sp -The SLS files used to install Windows packages are not distributed by default -with Salt. Use the \fI\%winrepo.update_git_repos\fP -runner initialize the repository in the location specified by \fBwinrepo_dir_ng\fP -in the master config. This will pull the software definition files down from the -git repository. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-run winrepo.update_git_repos -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If running a minion in masterless mode, the same command can be run using -\fBsalt\-call\fP\&. The repository will be initialized in the location specified by -\fBwinrepo_dir_ng\fP in the minion config. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-call \-\-local winrepo.update_git_repos -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -These commands will also sync down the legacy repo to maintain backwards -compatibility with legacy minions. See \fI\%Legacy Minions\fP -.sp -The legacy repo can be disabled by setting it to an empty list in the master or -minion config. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -winrepo_remotes: [] -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Generate the Metadata File (Legacy) -.sp -This step is only required if you are supporting legacy minions. In current -usage the metadata file is generated on the minion in the next step, Update -the Minion Database. For legacy minions the metadata file is generated on the -master using the \fI\%winrepo.genrepo\fP runner. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-run winrepo.genrepo -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Update the Minion Database -.sp -Run \fI\%pkg.refresh_db\fP on each of your -Windows minions to synchronize the package repository to the minion and build -the package database. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# From the master -salt \-G \(aqos:windows\(aq pkg.refresh_db - -# From the minion in masterless mode -salt\-call \-\-local pkg.refresh_db -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The above command returns the following summary denoting the number of packages -that succeeded or failed to compile: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -local: - \-\-\-\-\-\-\-\-\-\- - failed: - 0 - success: - 301 - total: - 301 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -This command can take a few minutes to complete as the software definition -files are copied to the minion and the database is generated. -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Use \fBpkg.refresh_db\fP when developing new Windows package definitions to -check for errors in the definitions against one or more Windows minions. -.UNINDENT -.UNINDENT .SS Usage .sp -After completing the configuration and initialization steps, you are ready to -manage software on your Windows minions. +After completing the configuration and initialization, you can use the Salt +package manager commands to manage software on Windows minions. .sp \fBNOTE:\fP .INDENT 0.0 @@ -465352,10 +458487,54 @@ The following example commands can be run from the master using \fBsalt\fP or on a masterless minion using \fBsalt\-call\fP .UNINDENT .UNINDENT -.SS List Installed Packages +.TS +center; +|l|l|l|. +_ +T{ +T} T{ +Command +T} T{ +Description +T} +_ +T{ +1 +T} T{ +\fI\%pkg.list_pkgs\fP +T} T{ +Displays a list of all packages installed in the system. +T} +_ +T{ +2 +T} T{ +\fI\%pkg.list_available\fP +T} T{ +Displays the versions available of a particular package to be installed. +T} +_ +T{ +3 +T} T{ +\fI\%pkg.install\fP +T} T{ +Installs a given package. +T} +_ +T{ +4 +T} T{ +\fI\%pkg.remove\fP +T} T{ +Uninstalls a given package. +T} +_ +.TE +.SS List installed packages .sp -You can get a list of packages installed on the system using -\fI\%pkg.list_pkgs\fP\&. +Use \fI\%pkg.list_pkgs\fP to display a list of +packages installed on the system. .INDENT 0.0 .INDENT 3.5 .sp @@ -465371,8 +458550,9 @@ salt\-call \-\-local pkg.list_pkgs .UNINDENT .UNINDENT .sp -This will return all software installed on the system whether it is managed by -Salt or not as shown below: +The command displays the software name and the version for every package +installed on the system irrespective of whether it was installed by the Salt +package manager. .INDENT 0.0 .INDENT 3.5 .sp @@ -465399,19 +458579,23 @@ local: .UNINDENT .UNINDENT .sp -You can tell by how the software name is displayed which software is managed by -Salt and which software is not. When Salt finds a match in the winrepo database -it displays the short name as defined in the software definition file. It is -usually a single\-word, lower\-case name. All other software names will be -displayed with the full name as they are shown in Add/Remove Programs. So, in -the return above, you can see that Git (git), Nullsoft Installer (nsis), Python -3.7 (python3_x64) and Salt (salt\-minion\-py3) all have a corresponding software -definition file. The others do not. -.SS List Available Versions +The software name indicates whether the software is managed by Salt or not. .sp -You can query the available version of a package using -\fI\%pkg.list_available\fP and passing the -name of the software: +If Salt finds a match in the winrepo database, then the software name is the +short name as defined in the package definition file. It is usually a +single\-word, lower\-case name. +.sp +All other software names are displayed as the full name as shown in +Add/Remove Programs. In the above example, Git (git), Nullsoft Installer (nsis), +Python 3.7 (python3_x64), and Salt (salt\-minion\-py3) have corresponding package +definition files and are managed by Salt, while Frhed 1.6.0, GNU Privacy guard, +and GPG4win are not. +.SS List available versions +.sp +Use \fI\%pkg.list_available\fP to display +a list of versions of a package available for installation. You can pass the +name of the software in the command. You can refer to the software by its +\fBname\fP or its \fBfull_name\fP surrounded by quotes. .INDENT 0.0 .INDENT 3.5 .sp @@ -465427,7 +458611,7 @@ salt\-call \-\-local pkg.list_available firefox_x64 .UNINDENT .UNINDENT .sp -The above command will return the following: +The command lists all versions of Firefox available for installation. .INDENT 0.0 .INDENT 3.5 .sp @@ -465452,21 +458636,18 @@ winminion: .UNINDENT .UNINDENT .sp -As you can see, there are many versions of Firefox available for installation. -You can refer to a software package by its \fBname\fP or its \fBfull_name\fP -surrounded by quotes. -.sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -From a Linux master it is OK to use single\-quotes. However, the \fBcmd\fP -shell on Windows requires you to use double\-quotes when wrapping strings -that may contain spaces. Powershell seems to accept either one. +For a Linux master, you can surround the file name with single quotes. +However, for the \fBcmd\fP shell on Windows, use double quotes when wrapping +strings that may contain spaces. Powershell accepts either single quotes or +double quotes. .UNINDENT .UNINDENT -.SS Install a Package +.SS Install a package .sp -You can install a package using \fI\%pkg.install\fP: +Use \fI\%pkg.install\fP: to install a package. .INDENT 0.0 .INDENT 3.5 .sp @@ -465482,7 +458663,7 @@ salt\-call \-\-local pkg.install \(dqfirefox_x64\(dq .UNINDENT .UNINDENT .sp -The above will install the latest version of Firefox. +The command installs the latest version of Firefox. .INDENT 0.0 .INDENT 3.5 .sp @@ -465498,13 +458679,13 @@ salt\-call \-\-local pkg.install \(dqfirefox_x64\(dq version=74.0 .UNINDENT .UNINDENT .sp -The above will install version 74.0 of Firefox. +The command installs version 74.0 of Firefox. .sp -If a different version of the package is already installed it will be replaced -with the version in the winrepo (only if the package itself supports live +If a different version of the package is already installed, then the old version +is replaced with the version in the winrepo (only if the package supports live updating). .sp -You can also specify the full name: +You can also specify the full name of the software while installing: .INDENT 0.0 .INDENT 3.5 .sp @@ -465519,9 +458700,9 @@ salt\-call \-\-local pkg.install \(dqMozilla Firefox 17.0.1 (x86 en\-US)\(dq .fi .UNINDENT .UNINDENT -.SS Remove a Package +.SS Remove a package .sp -You can uninstall a package using \fI\%pkg.remove\fP: +Use \fI\%pkg.remove\fP to remove a package. .INDENT 0.0 .INDENT 3.5 .sp @@ -465536,28 +458717,21 @@ salt\-call \-\-local pkg.remove firefox_x64 .fi .UNINDENT .UNINDENT -.SS Software Definition Files +.SS Package definition file directory structure and naming .sp -A software definition file is a YAML/JINJA2 file that contains all the -information needed to install a piece of software using Salt. It defines -information about the package to include version, full name, flags required for -the installer and uninstaller, whether or not to use the Windows task scheduler -to install the package, where to download the installation package, etc. -.SS Directory Structure and Naming +All package definition files are stored in the location configured in the +\fBwinrepo_dir_ng\fP setting. All files in this directory with a \fB\&.sls\fP file +extension are considered package definition files. These files are evaluated to +create the metadata file on the minion. .sp -The files are stored in the location designated by the \fBwinrepo_dir_ng\fP -setting. All files in this directory that have a \fB\&.sls\fP file extension are -considered software definition files. The files are evaluated to create the -metadata file on the minion. -.sp -You can maintain standalone software definition files that point to software on -other servers or on the internet. In this case the file name would be the short -name of the software with the \fB\&.sls\fP extension, ie \fBfirefox.sls\fP\&. +You can maintain standalone package definition files that point to software on +other servers or on the internet. In this case the file name is the short name +of the software with the \fB\&.sls\fP extension, for example,\(ga\(gafirefox.sls\(ga\(ga. .sp You can also store the binaries for your software together with their software definition files in their own directory. In this scenario, the directory name -would be the short name for the software and the software definition file would -be inside that directory and named \fBinit.sls\fP\&. +is the short name for the software and the package definition file stored that +directory is named \fBinit.sls\fP\&. .sp Look at the following example directory structure on a Linux master assuming default config settings: @@ -465602,98 +458776,54 @@ srv/ .UNINDENT .UNINDENT .sp -In the above directory structure, the user has created the \fBcustom_defs\fP -directory in which to store their custom software definition files. In that -directory you see a folder for MS Office 2013 that contains all the installer -files along with a software definition file named \fBinit.sls\fP\&. The user has -also created two more standalone software definition files; \fBopenssl.sls\fP and -\fBzoom.sls\fP\&. -.sp -The \fBsalt\-winrepo\-ng\fP directory is created by the \fBwinrepo.update_git_repos\fP -command. This folder contains the clone of the git repo designated by the -\fBwinrepo_remotes_ng\fP config setting. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -It is recommended that the user not modify the files in the -\fBsalt\-winrepo\-ng\fP directory as it will break future runs of -\fBwinrepo.update_git_repos\fP\&. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -It is recommended that the user not place any custom software definition -files in the \fBsalt\-winrepo\-ng\fP directory. The \fBwinrepo.update_git_repos\fP -command wipes out the contents of the \fBsalt\-winrepo\-ng\fP directory each -time it is run. Any extra files stored there will be lost. -.UNINDENT -.UNINDENT -.SS Writing Software Definition Files -.sp -A basic software definition file is really easy to write if you already know -some basic things about your software: +In the above directory structure: .INDENT 0.0 .IP \(bu 2 -The full name as shown in Add/Remove Programs +The \fBcustom_defs\fP directory contains the following custom package definition +files. +.INDENT 2.0 +.IP \(bu 2 +A folder for MS Office 2013 that contains the installer files for all the +MS Office software and a package definition file named \fBinit.sls\fP\&. +.IP \(bu 2 +Two additional standalone package definition files \fBopenssl.sls\fP and +\fBzoom.sls\fP to install OpenSSl and Zoom. +.UNINDENT +.IP \(bu 2 +The \fBsalt\-winrepo\-ng\fP directory contains the clone of the git repo specified +by the \fBwinrepo_remotes_ng\fP config setting. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Do not modify the files in the \fBsalt\-winrepo\-ng\fP directory as it breaks +future runs of \fBwinrepo.update_git_repos\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Do not place any custom software definition files in the \fBsalt\-winrepo\-ng\fP +directory as the \fBwinrepo.update_git_repos\fP command wipes out the contents +of the \fBsalt\-winrepo\-ng\fP directory each time it is run and any extra files +stored in the Salt winrepo are lost. +.UNINDENT +.UNINDENT +.SS Writing package definition files +.sp +You can write your own software definition file if you know: +.INDENT 0.0 +.IP \(bu 2 +The full name of the software as shown in Add/Remove Programs .IP \(bu 2 The exact version number as shown in Add/Remove Programs .IP \(bu 2 How to install your software silently from the command line .UNINDENT .sp -The software definition file itself is just a data structure written in YAML. -The top level item is a short name that Salt will use to reference the software. -There can be only one short name in the file and it must be unique across all -software definition files in the repo. This is the name that will be used to -install/remove the software. It is also the name that will appear when Salt -finds a match in the repo when running \fBpkg.list_pkgs\fP\&. -.sp -The next indentation level is the version number. There can be many of these, -but they must be unique within the file. This is also displayed in -\fBpkg.list_pkgs\fP\&. -.sp -The last indentation level contains the information Salt needs to actually -install the software. Available parameters are: -.INDENT 0.0 -.IP \(bu 2 -\fBfull_name\fP : The full name as displayed in Add/Remove Programs -.IP \(bu 2 -\fBinstaller\fP : The location of the installer binary -.IP \(bu 2 -\fBinstall_flags\fP : The flags required to install silently -.IP \(bu 2 -\fBuninstaller\fP : The location of the uninstaller binary -.IP \(bu 2 -\fBuninstall_flags\fP : The flags required to uninstall silently -.IP \(bu 2 -\fBmsiexec\fP : Use msiexec to install this package -.IP \(bu 2 -\fBallusers\fP : If this is an MSI, install to all users -.IP \(bu 2 -\fBcache_dir\fP : Cache the entire directory in the installer URL if it starts with \fBsalt://\fP -.IP \(bu 2 -\fBcache_file\fP : Cache a single file in the installer URL if it starts with \fBsalt://\fP -.IP \(bu 2 -\fBuse_scheduler\fP : Launch the installer using the task scheduler -.IP \(bu 2 -\fBsource_hash\fP : The hash sum for the installer -.UNINDENT -.sp -Usage of these parameters is demonstrated in the following examples and -discussed in more detail below. To understand these examples you\(aqll need a basic -understanding of Jinja. The following links have some basic tips and best -practices for working with Jinja in Salt: -.sp -\fI\%Understanding Jinja\fP -.sp -\fI\%Jinja\fP -.SS Example: Basic -.sp -Take a look at this basic, pure YAML example for a software definition file for -Firefox: +Here is a YAML software definition file for Firefox: .INDENT 0.0 .INDENT 3.5 .sp @@ -465717,40 +458847,157 @@ firefox_x64: .UNINDENT .UNINDENT .sp -You can see the first item is the short name for the software, in this case -\fBfirefox_x64\fP\&. It is the first line in the definition. The next line is -indented two spaces and contains the software \fBversion\fP\&. The lines following -the \fBversion\fP are indented two more spaces and contain all the information -needed to install the Firefox package. +The package definition file itself is a data structure written in YAML with +three indentation levels: +.INDENT 0.0 +.IP \(bu 2 +The first level item is a short name that Salt uses to reference the software. +This short name is used to install and remove the software and it must be +unique across all package definition files in the repo. Also, there must be +only one short name in the file. +.IP \(bu 2 +The second level item is the version number. There can be multiple version +numbers for a package but they must be unique within the file. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +When running \fBpkg.list_pkgs\fP, the short name and version number are +displayed when Salt finds a match in the repo. Otherwise, the full package +name is displayed. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.IP \(bu 2 +The third indentation level contains all parameters that Salt needs to install +the software. The parameters are: +.INDENT 2.0 +.IP \(bu 2 +\fBfull_name\fP : The full name as displayed in Add/Remove Programs +.IP \(bu 2 +\fBinstaller\fP : The location of the installer binary +.IP \(bu 2 +\fBinstall_flags\fP : The flags required to install silently +.IP \(bu 2 +\fBuninstaller\fP : The location of the uninstaller binary +.IP \(bu 2 +\fBuninstall_flags\fP : The flags required to uninstall silently +.IP \(bu 2 +\fBmsiexec\fP : Use msiexec to install this package +.IP \(bu 2 +\fBallusers\fP : If this is an MSI, install to all users +.IP \(bu 2 +\fBcache_dir\fP : Cache the entire directory in the installer URL if it starts +with \fBsalt://\fP +.IP \(bu 2 +\fBcache_file\fP : Cache a single file in the installer URL if it starts with +\fBsalt://\fP +.IP \(bu 2 +\fBuse_scheduler\fP : Launch the installer using the task scheduler +.IP \(bu 2 +\fBsource_hash\fP : The hash sum for the installer +.UNINDENT +.UNINDENT +.SS Example package definition files +.sp +This section provides some examples of package definition files for different +use cases such as: +.INDENT 0.0 +.IP \(bu 2 +Writing a \fI\%simple package definition file\fP +.IP \(bu 2 +Writing a \fI\%JINJA templated package definition file\fP +.IP \(bu 2 +Writing a package definition file to \fI\%install the latest version of the software\fP +.IP \(bu 2 +Writing a package definition file to \fI\%install an MSI patch\fP +.UNINDENT +.sp +These examples enable you to gain a better understanding of the usage of +different file parameters. To understand the examples, you need a basic +\fI\%Understanding Jinja\fP\&. +For an exhaustive dive into Jinja, refer to the official +\fI\%Jinja Template Designer documentation\fP\&. +.SS Example: Simple +.sp +Here is a pure YAML example of a simple package definition file for Firefox: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +firefox_x64: + \(aq74.0\(aq: + full_name: Mozilla Firefox 74.0 (x64 en\-US) + installer: \(aqhttps://download\-installer.cdn.mozilla.net/pub/firefox/releases/74.0/win64/en\-US/Firefox%20Setup%2074.0.exe\(aq + install_flags: \(aq/S\(aq + uninstaller: \(aq%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe\(aq + uninstall_flags: \(aq/S\(aq + \(aq73.0.1\(aq: + full_name: Mozilla Firefox 73.0.1 (x64 en\-US) + installer: \(aqhttps://download\-installer.cdn.mozilla.net/pub/firefox/releases/73.0.1/win64/en\-US/Firefox%20Setup%2073.0.1.exe\(aq + install_flags: \(aq/S\(aq + uninstaller: \(aq%ProgramFiles(x86)%/Mozilla Firefox/uninstall/helper.exe\(aq + uninstall_flags: \(aq/S\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The first line is the short name of the software which is \fBfirefox_x64\fP\&. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 -The package name must be unique to all other packages in the software +The short name must be unique across all other short names in the software repository. The \fBfull_name\fP combined with the version must also be unique. -They must also match exactly what is shown in Add/Remove Programs -(\fBappwiz.cpl\fP). +.UNINDENT +.UNINDENT +.sp +The second line is the \fBsoftware version\fP and is indented two spaces. +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +The version number must be enclosed in quotes or the YAML parser removes the +trailing zeros. For example, if the version number \fB74.0\fP is not enclosed +within quotes, then the version number is rendered as \fB74\fP\&. +.UNINDENT +.UNINDENT +.sp +The lines following the \fBversion\fP are indented two more spaces and contain all +the information needed to install the Firefox package. +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +You can specify multiple versions of software by specifying multiple version +numbers at the same indentation level as the first with its software +definition below it. .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 -The version number must be enclosed in quotes, otherwise the YAML parser -will remove trailing zeros. For example, \fI74.0\fP will just become \fI74\fP\&. +The \fBfull_name\fP must match exactly what is shown in Add/Remove Programs +(\fBappwiz.cpl\fP) .UNINDENT .UNINDENT +.SS Example: JINJA templated package definition file .sp -As you can see in the example above, a software definition file can define -multiple versions for the same piece of software. These are denoted by putting -the next version number at the same indentation level as the first with its -software definition information indented below it. -.SS Example: Jinja +JINJA is the default templating language used in package definition files. You +can use JINJA to add variables and expressions to package definition files that +get replaced with values when the \fB\&.sls\fP go through the Salt renderer. .sp -When there are tens or hundreds of versions available for a piece of software -definition file can become quite large. This is a scenario where Jinja can be -helpful. Consider the following software definition file for Firefox using -Jinja: +When there are tens or hundreds of versions available for a piece of software, +the definition file can become large and cumbersome to maintain. In this +scenario, JINJA can be used to add logic, variables, and expressions to +automatically create the package definition file for software with multiple +versions. +.sp +Here is a an example of a package definition file for Firefox that uses JINJA: .INDENT 0.0 .INDENT 3.5 .sp @@ -465776,28 +459023,26 @@ firefox_x64: .UNINDENT .UNINDENT .sp -In this example we are able to generate a software definition file that defines -how to install 12 versions of Firefox. We use Jinja to create a list of -available versions. That list is in a \fBfor loop\fP where each version is placed -in the \fBversion\fP variable. The version is inserted everywhere there is a -\fB{{ version }}\fP marker inside the \fBfor loop\fP\&. +In this example, JINJA is used to generate a package definition file that +defines how to install 12 versions of Firefox. Jinja is used to create a list of +available versions. The list is iterated through a \fBfor loop\fP where each +version is placed in the \fBversion\fP variable. The version is inserted +everywhere there is a \fB{{ version }}\fP marker inside the \fBfor loop\fP\&. .sp -You\(aqll notice that there is a single variable (\fBlang\fP) defined at the top of -the software definition. Because these files are going through the Salt renderer -many Salt modules are exposed via the \fBsalt\fP keyword. In this case it is -calling the \fBconfig.get\fP function to get a language setting that can be placed -in the minion config. If it is not there, it defaults to \fBen\-US\fP\&. -.SS Example: Latest +The single variable (\fBlang\fP) defined at the top of the package definition +identifies the language of the package. You can access the Salt modules using +the \fBsalt\fP keyword. In this case, the \fBconfig.get\fP function is invoked to +retrieve the language setting. If the \fBlang\fP variable is not defined then the +default value is \fBen\-US\fP\&. +.SS Example: Package definition file to install the latest version .sp -There are some software vendors that do not provide access to all versions of -their software. Instead they provide a single URL to what is always the latest -version. In some cases the software keeps itself up to date. One example of this -is the Google Chrome web browser. -.sp -\fI\%Chrome\fP +Some software vendors do not provide access to all versions of their software. +Instead, they provide a single URL to what is always the latest version. In some +cases, the software keeps itself up to date. One example of this is the \fI\%Google +Chrome web browser\fP\&. .sp To handle situations such as these, set the version to \fIlatest\fP\&. Here\(aqs an -example: +example of a package definition file to install the latest version of Chrome. .INDENT 0.0 .INDENT 3.5 .sp @@ -465816,23 +459061,22 @@ chrome: .UNINDENT .UNINDENT .sp -The above example shows us two things. First it demonstrates the usage of -\fBlatest\fP as the version. In this case Salt will install the version of Chrome -at the URL and report that version. +In the above example: +.INDENT 0.0 +.IP \(bu 2 +\fBVersion\fP is set to \fBlatest\fP\&. Salt then installs the latest version of +Chrome at the URL and displays that version. +.IP \(bu 2 +\fBmsiexec\fP is set to \fBTrue\fP, hence the software is installed using an MSI. +.UNINDENT +.SS Example: Package definition file to install an MSI patch .sp -The second thing to note is that this is installing software using an MSI. You -can see that \fBmsiexec\fP is set to \fBTrue\fP\&. -.SS Example: MSI Patch +For MSI installers, when the \fBmsiexec\fP parameter is set to true, the \fB/i\fP +option is used for installation, and the \fB/x\fP option is used for +uninstallation. However, when installing an MSI patch, the \fB/i\fP and \fB/x\fP +options cannot be combined. .sp -When the \fBmsiexec\fP parameter is set to \fBTrue\fP it uses the \fB/i\fP option for -installs and the \fB/x\fP option for uninstalls. This is problematic when trying -to install an MSI patch which requires the \fB/p\fP option. You can\(aqt combine the -\fB/i\fP and \fB/p\fP options. So how do you apply a patch to installed software in -winrepo using an \fB\&.msp\fP file? -.sp -One wiley contributor came up with the following solution to this problem by -using the \fB%cd%\fP environment variable. Consider the following software -definition file: +Here is an example of a package definition file to install an MSI patch: .INDENT 0.0 .INDENT 3.5 .sp @@ -465853,46 +459097,52 @@ MyApp: uninstaller: \(aq{B5B5868F\-23BA\-297A\-917D\-0DF345TF5764}\(aq uninstall_flags: \(aq/qn /norestart\(aq msiexec: True - cache_file: salt://win/repo/MyApp/MyApp.1.1.msp + cache_file: salt://win/repo\-ng/MyApp/MyApp.1.1.msp .ft P .fi .UNINDENT .UNINDENT .sp -There are a few things to note about this software definition file. First, is -the solution we are trying to solve, that of applying a patch. Version \fB1.0\fP -just installs the application using the \fB1.0\fP MSI defined in the \fBinstaller\fP -parameter. There is nothing special in the \fBinstall_flags\fP and nothing is -cached. +In the above example: +.INDENT 0.0 +.IP \(bu 2 +Version \fB1.0\fP of the software installs the application using the \fB1.0\fP +MSI defined in the \fBinstaller\fP parameter. +.IP \(bu 2 +There is no file to be cached and the \fBinstall_flags\fP parameter does not +include any special values. +.UNINDENT .sp -Version \fB1.1\fP uses the same installer, but uses the \fBcache_file\fP option to -specify a single file to cache. In order for this to work the MSP file needs to -be in the same directory as the MSI file on the \fBfile_roots\fP\&. +Version \fB1.1\fP of the software uses the same installer file as Version +\fB1.0\fP\&. Now, to apply a patch to Version 1.0, make the following changes in +the package definition file: +.INDENT 0.0 +.IP \(bu 2 +Place the patch file (MSP file) in the same directory as the installer file +(MSI file) on the \fBfile_roots\fP +.IP \(bu 2 +In the \fBcache_file\fP parameter, specify the path to the single patch file. +.IP \(bu 2 +In the \fBinstall_flags\fP parameter, add the \fB/update\fP flag and include the +path to the MSP file using the \fB%cd%\fP environment variable. \fB%cd%\fP +resolves to the current working directory, which is the location in the minion +cache where the installer file is cached. +.UNINDENT .sp -The final step to getting this to work is to add the additional \fB/update\fP flag -to the \fBinstall_flags\fP parameter. Add the path to the MSP file using the -\fB%cd%\fP environment variable. \fB%cd%\fP resolves to the current working -directory which is the location in the minion cache where the installer file is -cached. +For more information, see issue \fI\%#32780\fP\&. .sp -See issue \fI\%#32780\fP for more -details. -.sp -This same approach could be used for applying MST files for MSIs and answer -files for other types of .exe based installers. +The same approach could be used for applying MST files for MSIs and answer files +for other types of .exe\-based installers. .SS Parameters .sp -These are the parameters that can be used to generate a software definition -file. These parameters are all placed under the \fBversion\fP in the software -definition file: -.sp -Example usage can be found on the \fI\%github repo\fP +This section describes the parameters placed under the \fBversion\fP in the +package definition file. Examples can be found on the \fI\%Salt winrepo repository\fP\&. .SS full_name (str) .sp -This is the full name for the software as shown in \(dqPrograms and Features\(dq in -the control panel. You can also get this information by installing the package -manually and then running \fBpkg.list_pkgs\fP\&. Here\(aqs an example of the output -from \fBpkg.list_pkgs\fP: +The full name of the software as shown in \(dqAdd/Remove Programs\(dq. You can also +retrieve the full name of the package by installing the package manually and +then running \fBpkg.list_pkgs\fP\&. Here\(aqs an example of the output from +\fBpkg.list_pkgs\fP: .INDENT 0.0 .INDENT 3.5 .sp @@ -465914,14 +459164,11 @@ test\-2008 .UNINDENT .UNINDENT .sp -Notice the Full Name for Firefox: \fBMozilla Firefox 74.0 (x64 en\-US)\fP\&. That\(aqs -exactly what should be in the \fBfull_name\fP parameter in the software definition -file. +Notice the full Name for Firefox: \fBMozilla Firefox 74.0 (x64 en\-US)\fP\&. The +\fBfull_name\fP parameter in the package definition file must match this name. .sp -If any of the software installed on the machine matches the full name defined in -one of the software definition files in the repository the package name will be -returned. The example below shows the \fBpkg.list_pkgs\fP for a machine that has -Mozilla Firefox 74.0 installed and a software definition for that version of +The example below shows the \fBpkg.list_pkgs\fP for a machine that has Mozilla +Firefox 74.0 installed with a package definition file for that version of Firefox. .INDENT 0.0 .INDENT 3.5 @@ -465943,24 +459190,27 @@ test\-2008: .UNINDENT .UNINDENT .sp +On running \fBpkg.list_pkgs\fP, if any of the software installed on the machine +matches the full name defined in any one of the software definition files in the +repository, then the package name is displayed in the output. +.sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 -The version number and \fBfull_name\fP need to match the output from -\fBpkg.list_pkgs\fP exactly so that the installation status can be verified -by the state system. +The version number and \fBfull_name\fP must match the output of +\fBpkg.list_pkgs\fP so that the installation status can be verified by the +state system. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -It is still possible to successfully install packages using \fBpkg.install\fP, -even if the \fBfull_name\fP or the version number don\(aqt match exactly. The -module will complete successfully, but continue to display the full name -in \fBpkg.list_pkgs\fP\&. If this is happening, verify that the \fBfull_name\fP -and the \fBversion\fP match exactly what is displayed in Add/Remove -Programs. +You can successfully install packages using \fBpkg.install\fP, even if the +\fBfull_name\fP or the version number doesn\(aqt match. The module will complete +successfully, but continue to display the full name in \fBpkg.list_pkgs\fP\&. +If this is happening, verify that the \fBfull_name\fP and the \fBversion\fP +match exactly what is displayed in Add/Remove Programs. .UNINDENT .UNINDENT .sp @@ -465983,50 +459233,57 @@ minion you\(aqre testing new definitions on. .UNINDENT .SS installer (str) .sp -This is the path to the binary (\fB\&.exe\fP, \fB\&.msi\fP) that will install the -package. This can be a local path or a URL. If it is a URL or a Salt path -(\fBsalt://\fP), the package will be cached locally and then executed. If it is a -path to a file on disk or a file share, it will be executed directly. +The path to the binary (\fB\&.exe\fP, \fB\&.msi\fP) that installs the package. +.sp +This can be a local path or a URL. If it is a URL or a Salt path (\fBsalt://\fP), +then the package is cached locally and then executed. If it is a path to a file +on disk or a file share, then it is executed directly. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -When storing software in the same location as the winrepo it is usually best -practice to place each installer in its own directory rather than in the -root of winrepo. +When storing software in the same location as the winrepo: +.INDENT 0.0 +.IP \(bu 2 +Create a sub folder named after the package. +.IP \(bu 2 +Store the package definition file named \fBinit.sls\fP and the binary +installer in the same sub folder if you are hosting those files on the +\fBfile_roots\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT .sp -Best practice is to create a sub folder named after the package. That folder -will contain the software definition file named \fBinit.sls\fP\&. The binary -installer should be stored in that directory as well if you\(aqre hosting those -files on the file_roots. -.sp -\fBpkg.refresh_db\fP will process all \fB\&.sls\fP files in all sub directories -in the \fBwinrepo_dir_ng\fP directory. +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBpkg.refresh_db\fP command processes all \fB\&.sls\fP files in all sub +directories in the \fBwinrepo_dir_ng\fP directory. .UNINDENT .UNINDENT .SS install_flags (str) .sp -This setting contains any flags that need to be passed to the installer to make -it perform a silent install. These can often be found by adding \fB/?\fP or \fB/h\fP -when running the installer from the command\-line. A great resource for finding -these silent install flags is the WPKG project \fI\%wiki\fP: +The flags passed to the installer for silent installation. +.sp +You may be able to find these flags by adding \fB/?\fP or \fB/h\fP when running the +installer from the command line. See \fI\%WPKG project wiki\fP for information on silent install flags. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -Salt will appear to hang if the installer is expecting user input. So it is -imperative that the software have the ability to install silently. +Always ensure that the installer has the ability to install silently, +otherwise Salt appears to hang while the installer waits for user input. .UNINDENT .UNINDENT .SS uninstaller (str) .sp -This is the path to the program used to uninstall this software. This can be the -path to the same \fBexe\fP or \fBmsi\fP used to install the software. Exe -uninstallers are pretty straight forward. MSIs, on the other hand, can be -handled a couple different ways. You can use the GUID for the software to -uninstall or you can use the same MSI used to install the software. +The path to the program to uninstall the software. .sp -You can usually find uninstall information in the registry: +This can be the path to the same \fB\&.exe\fP or \fB\&.msi\fP used to install the +software. If you use a \fB\&.msi\fP to install the software, then you can either +use the GUID of the software or the same \fB\&.msi\fP to uninstall the software. +.sp +You can find the uninstall information in the registry: .INDENT 0.0 .IP \(bu 2 Software\eMicrosoft\eWindows\eCurrentVersion\eUninstall @@ -466034,7 +459291,7 @@ Software\eMicrosoft\eWindows\eCurrentVersion\eUninstall Software\eWOW6432Node\eMicrosoft\eWindows\eCurrentVersion\eUninstall .UNINDENT .sp -Here\(aqs an example using the GUID to uninstall software. +Here\(aqs an example that uses the GUID to uninstall software: .INDENT 0.0 .INDENT 3.5 .sp @@ -466053,7 +459310,7 @@ Here\(aqs an example using the GUID to uninstall software. .UNINDENT .UNINDENT .sp -Here\(aqs an example using the same MSI used to install the software: +Here\(aqs an example that uses the MSI installer to uninstall software: .INDENT 0.0 .INDENT 3.5 .sp @@ -466073,22 +459330,22 @@ Here\(aqs an example using the same MSI used to install the software: .UNINDENT .SS uninstall_flags (str) .sp -This setting contains any flags that need to be passed to the uninstaller to -make it perform a silent uninstall. These can often be found by adding \fB/?\fP or -\fB/h\fP when running the uninstaller from the command\-line. A great resource for -finding these silent install flags the WPKG project \fI\%wiki\fP: +The flags passed to the uninstaller for silent uninstallation. +.sp +You may be able to find these flags by adding \fB/?\fP or \fB/h\fP when running the +uninstaller from the command\-line. See \fI\%WPKG project wiki\fP for information on silent uninstall flags. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -Salt will appear to hang if the uninstaller is expecting user input. So it -is imperative that the software have the ability to uninstall silently. +Always ensure that the installer has the ability to uninstall silently, +otherwise Salt appears to hang while the uninstaller waits for user input. .UNINDENT .UNINDENT .SS msiexec (bool, str) .sp -This tells Salt to use \fBmsiexec /i\fP to install the package and \fBmsiexec /x\fP -to uninstall. This is for \fB\&.msi\fP installations only. +This setting informs Salt to use \fBmsiexec /i\fP to install the package and \fBmsiexec /x\fP +to uninstall. This setting only applies to \fB\&.msi\fP installations. .sp Possible options are: .INDENT 0.0 @@ -466123,19 +459380,21 @@ install the software for all users. The default is \fBTrue\fP\&. .SS cache_dir (bool) .sp This setting requires the software to be stored on the \fBfile_roots\fP and only -applies to URLs that begin with \fBsalt://\fP\&. If \fBTrue\fP the entire directory -where the installer resides will be recursively cached. This is useful for -installers that depend on other files in the same directory for installation. +applies to URLs that begin with \fBsalt://\fP\&. If set to \fBTrue\fP, then the +entire directory where the installer resides is recursively cached. This is +useful for installers that depend on other files in the same directory for +installation. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -Be aware that all files and directories in the same location as the -installer file will be copied down to the minion. If you place your -software definition file in the root of winrepo (\fB/srv/salt/win/repo\-ng\fP) -and it contains \fBcache_dir: True\fP the entire contents of winrepo will be -cached to the minion. Therefore, it is best practice to place your installer -files in a subdirectory if they are to be stored in winrepo. +If set to \fBTrue\fP, then all files and directories in the same location as +the installer file are copied down to the minion. For example, if you place +your package definition file with \fBcache_dir: True\fP in the root of winrepo +(\fB/srv/salt/win/repo\-ng\fP) then the entire contents of winrepo is cached to +the minion. Therefore, it is best practice to place your package definition +file along with its installer files in a subdirectory if they are stored in +winrepo. .UNINDENT .UNINDENT .sp @@ -466158,33 +459417,33 @@ sqlexpress: .SS cache_file (str) .sp This setting requires the file to be stored on the \fBfile_roots\fP and only -applies to URLs that begin with \fBsalt://\fP\&. It indicates a single file to copy -down for use with the installer. It is copied to the same location as the -installer. Use this over \fBcache_dir\fP if there are many files in the directory -and you only need a specific file and don\(aqt want to cache additional files that -may reside in the installer directory. +applies to URLs that begin with \fBsalt://\fP\&. It indicates that the single file +specified is copied down for use with the installer. It is copied to the same +location as the installer. Use this setting instead of \fBcache_dir\fP when you +only need to cache a single file. .SS use_scheduler (bool) .sp -If set to \fBTrue\fP, Windows will use the task scheduler to run the installation. -A one\-time task will be created in the task scheduler and launched. The return -to the minion will be that the task was launched successfully, not that the -software was installed successfully. +If set to \fBTrue\fP, Windows uses the task scheduler to run the installation. A +one\-time task is created in the task scheduler and launched. The return to the +minion is that the task was launched successfully, not that the software was +installed successfully. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -This is used by the software definition for Salt itself. The first thing the +This is used in the package definition for Salt itself. The first thing the Salt installer does is kill the Salt service, which then kills all child processes. If the Salt installer is launched via Salt, then the installer -itself is killed leaving Salt on the machine but not running. Use of the -task scheduler allows an external process to launch the Salt installation so -its processes aren\(aqt killed when the Salt service is stopped. +is killed with the salt\-minion service, leaving Salt on the machine but not +running. Using the task scheduler allows an external process to launch the +Salt installer so its processes aren\(aqt killed when the Salt service is +stopped. .UNINDENT .UNINDENT .SS source_hash (str) .sp -This tells Salt to compare a hash sum of the installer to the provided hash sum -before execution. The value can be formatted as \fB=\fP, +This setting informs Salt to compare a hash sum of the installer to the provided +hash sum before execution. The value can be formatted as \fB=\fP, or it can be a URI to a file containing the hash sum. .sp For a list of supported algorithms, see the \fI\%hashlib documentation\fP\&. @@ -466211,7 +459470,7 @@ messageanalyzer: .SS Not Implemented .sp The following parameters are often seen in the software definition files hosted -on the Git repo. However, they are not implemented and have no effect on the +on the Git repo. However, they are not implemented and do not affect the installation process. .INDENT 0.0 .TP @@ -466226,11 +459485,10 @@ Not implemented The Windows Software Repository functions similarly in a standalone environment, with a few differences in the configuration. .sp -To replace the winrepo runner that is used on the Salt master, an -\fBexecution module\fP exists to provide the same -functionality to standalone minions. The functions are named the same as the -ones in the runner, and are used in the same way; the only difference is that -\fBsalt\-call\fP is used instead of \fBsalt\-run\fP: +To replace the winrepo runner used on the Salt master, an \fBexecution module\fP exists to provide the same functionality to standalone +minions. The functions for the module share the same names with functions in the +runner and are used in the same way; the only difference is that \fBsalt\-call\fP +is used instead of \fBsalt\-run\fP to run those functions: .INDENT 0.0 .INDENT 3.5 .sp @@ -466243,25 +459501,31 @@ salt\-call pkg.refresh_db .UNINDENT .UNINDENT .sp -After executing the previous commands the repository on the standalone system is -ready for use. +After executing the previous commands, the repository on the standalone system +is ready for use. .SS Troubleshooting -.SS My software installs correctly but pkg.installed says it failed +.SS My software installs correctly but \fBpkg.installed\fP says it failed .sp -If you have a package that seems to install properly, but Salt reports a failure +If you have a package that seems to install properly but Salt reports a failure then it is likely you have a \fBversion\fP or \fBfull_name\fP mismatch. -.sp -Check the exact \fBfull_name\fP and \fBversion\fP as shown in Add/Remove Programs -(\fBappwiz.cpl\fP). Use \fBpkg.list_pkgs\fP to check that the \fBfull_name\fP and -\fBversion\fP exactly match what is installed. Make sure the software definition -file has the exact value for \fBfull_name\fP and that the version matches exactly. -.sp -Also, make sure the version is wrapped in single quotes in the software +.INDENT 0.0 +.IP \(bu 2 +Check the \fBfull_name\fP and \fBversion\fP of the package as shown in Add/Remove +Programs (\fBappwiz.cpl\fP). +.IP \(bu 2 +Use \fBpkg.list_pkgs\fP to check that the \fBfull_name\fP and \fBversion\fP exactly +match what is installed. +.IP \(bu 2 +Verify that the \fBfull_name\fP and \fBversion\fP in the package definition file +match the full name and version in Add/Remove programs. +.IP \(bu 2 +Ensure that the \fBversion\fP is wrapped in single quotes in the package definition file. -.SS Changes to sls files not being picked up +.UNINDENT +.SS Changes to package definition files not being picked up .sp -You may have recently updated some of the software definition files on the repo. -Ensure you have refreshed the database on the minion. +Make sure you refresh the database on the minion (\fBpkg.refresh_db\fP) after +updating package definition files in the repo. .INDENT 0.0 .INDENT 3.5 .sp @@ -466272,75 +459536,33 @@ salt winminion pkg.refresh_db .fi .UNINDENT .UNINDENT -.SS How Success and Failure are Reported by pkg.installed -.sp -The install state/module function of the Windows package manager works roughly -as follows: -.INDENT 0.0 -.IP 1. 3 -Execute \fBpkg.list_pkgs\fP to get a list of software currently on the machine -.IP 2. 3 -Compare the requested version with the installed version -.IP 3. 3 -If versions are the same, report no changes needed -.IP 4. 3 -Install the software as described in the software definition file -.IP 5. 3 -Execute \fBpkg.list_pkgs\fP to get a new list of software currently on the -machine -.IP 6. 3 -Compare the requested version with the new installed version -.IP 7. 3 -If versions are the same, report success -.IP 8. 3 -If versions are different, report failure -.UNINDENT -.SS Winrepo Upgrade Issues +.SS Winrepo upgrade issues .sp To minimize potential issues, it is a good idea to remove any winrepo git repositories that were checked out by the legacy (pre\-2015.8.0) winrepo code -when upgrading the master to 2015.8.0 or later. Run -\fI\%winrepo.update_git_repos\fP to -clone them anew after the master is started. -.SS \fI\%pygit2\fP/\fI\%GitPython\fP Support for Maintaining Git Repos +when upgrading the master to 2015.8.0 or later. Run \fI\%winrepo.update_git_repos\fP to clone them anew after the master is +started. +.SS pygit2 / GitPython Support for Maintaining Git Repos .sp -The \fI\%winrepo.update_git_repos\fP -runner now makes use of the same underlying code used by the \fI\%Git Fileserver Backend\fP -and \fI\%Git External Pillar\fP to maintain and update -its local clones of git repositories. If a compatible version of either \fI\%pygit2\fP -(0.20.3 and later) or \fI\%GitPython\fP (0.3.0 or later) is installed, Salt will use it -instead of the old method (which invokes the \fI\%git.latest\fP -state). +pygit2 and GitPython are the supported python interfaces to Git. The runner +\fI\%winrepo.update_git_repos\fP uses the +same underlying code as \fI\%Git Fileserver Backend\fP and +\fI\%Git External Pillar\fP to maintain and update its +local clones of git repositories. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -If compatible versions of both \fI\%pygit2\fP and \fI\%GitPython\fP are installed, then -Salt will prefer \fI\%pygit2\fP\&. To override this behavior use the -\fI\%winrepo_provider\fP configuration parameter: -.INDENT 0.0 -.INDENT 3.5 +If compatible versions of both pygit2 and GitPython are installed, then +Salt will prefer pygit2. To override this behavior use the +\fI\%winrepo_provider\fP configuration parameter, ie: +\fBwinrepo_provider: gitpython\fP +.UNINDENT +.UNINDENT +.SS Accessing authenticated Git repos (pygit2) .sp -.nf -.ft C -winrepo_provider: gitpython -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The \fBwinrepo execution module\fP (discussed -above in the \fI\%Managing Windows Software on a Standalone Windows Minion\fP section) does not yet officially support the new -\fI\%pygit2\fP/\fI\%GitPython\fP functionality, but if either \fI\%pygit2\fP or \fI\%GitPython\fP is -installed into Salt\(aqs bundled Python then it \fIshould\fP work. However, it -should be considered experimental at this time. -.UNINDENT -.UNINDENT -.SS Accessing Authenticated Git Repos (pygit2) -.sp -Support for pygit2 added the ability to access authenticated git repositories -and to set per\-remote config settings. An example of this would be the -following: +pygit2 enables you to access authenticated git repositories and set per\-remote +config settings. An example of this is: .INDENT 0.0 .INDENT 3.5 .sp @@ -466363,26 +459585,25 @@ winrepo_remotes: \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Per\-remote configuration settings work in the same fashion as they do in +The per\-remote configuration settings work in the same manner as they do in gitfs, with global parameters being overridden by their per\-remote -counterparts. For instance, setting \fI\%winrepo_passphrase\fP would -set a global passphrase for winrepo that would apply to all SSH\-based +counterparts. For instance, setting \fI\%winrepo_passphrase\fP +sets a global passphrase for winrepo that applies to all SSH\-based remotes, unless overridden by a \fBpassphrase\fP per\-remote parameter. .sp -See \fI\%here\fP for more a more in\-depth +See \fI\%here\fP for a detailed explanation of how per\-remote configuration works in gitfs. The same principles apply to winrepo. .UNINDENT .UNINDENT -.SS Maintaining Git Repos +.SS Maintaining Git repos .sp -A \fBclean\fP argument has been added to the +A \fBclean\fP argument is added to the \fI\%winrepo.update_git_repos\fP -runner. When \fBclean\fP is \fBTrue\fP it will tell the runner to dispose of +runner to maintain the Git repos. When \fBclean=True\fP the runner removes directories under the \fI\%winrepo_dir_ng\fP/\fI\%winrepo_dir_ng\fP -which are not explicitly configured. This prevents the need to manually remove -these directories when a repo is removed from the config file. To clean these -old directories, just pass \fBclean=True\fP: +that are not explicitly configured. This eliminates the need to manually remove +these directories when a repo is removed from the config file. .INDENT 0.0 .INDENT 3.5 .sp @@ -466394,15 +459615,15 @@ salt\-run winrepo.update_git_repos clean=True .UNINDENT .UNINDENT .sp -If a mix of git and non\-git Windows Repo definition files are being used, then -this should \fInot\fP be used, as it will remove the directories containing non\-git +If a mix of git and non\-git Windows Repo definition files are used, then +do not pass \fBclean=True\fP, as it removes the directories containing non\-git definitions. -.SS Name Collisions Between Repos +.SS Name collisions between repos .sp -Collisions between repo names are now detected. The +Salt detects collisions between repository names. The \fI\%winrepo.update_git_repos\fP -runner will not proceed if any are detected. Consider the following -configuration: +runner does not execute successfully if any collisions between repository names +are detected. Consider the following configuration: .INDENT 0.0 .INDENT 3.5 .sp @@ -466411,16 +459632,16 @@ configuration: winrepo_remotes: \- https://foo.com/bar/baz.git \- https://mydomain.tld/baz.git - \- https://github.com/foobar/baz + \- https://github.com/foobar/baz.git .ft P .fi .UNINDENT .UNINDENT .sp -The \fI\%winrepo.update_git_repos\fP -runner will refuse to update repos here, as all three of these repos would be -checked out to the same directory. To work around this, a per\-remote parameter -called \fBname\fP can be used to resolve these conflicts: +With the above configuration, the \fI\%winrepo.update_git_repos\fP +runner fails to execute as all three repos would be checked out to the same +directory. To resolve this conflict, use the per\-remote parameter called +\fBname\fP\&. .INDENT 0.0 .INDENT 3.5 .sp @@ -466430,297 +459651,22 @@ winrepo_remotes: \- https://foo.com/bar/baz.git \- https://mydomain.tld/baz.git: \- name: baz_junior - \- https://github.com/foobar/baz: + \- https://github.com/foobar/baz.git: \- name: baz_the_third .ft P .fi .UNINDENT .UNINDENT -.SS Legacy Minions .sp -The Windows Package Manager was upgraded with breaking changes starting with -Salt 2015.8.0. To maintain backwards compatibility Salt continues to support -older minions. -.sp -The breaking change was to generate the winrepo database on the minion instead -of the master. This allowed for the use of Jinja in the software definition -files. It enabled the use of pillar, grains, execution modules, etc. during -compile time. To support this new functionality, a next\-generation (ng) repo was -created. -.sp -See the \fI\%Changes in Version 2015.8.0\fP for -details. -.sp -On prior versions of Salt, or legacy minions, the winrepo database was -generated on the master and pushed down to the minions. Any grains exposed at -compile time would have been those of the master and not the minion. -.sp -The repository for legacy minions is named \fBsalt\-winrepo\fP and is located at: +Now on running the \fI\%winrepo.update_git_repos\fP: .INDENT 0.0 .IP \(bu 2 -\fI\%https://github.com/saltstack/salt\-winrepo\fP -.UNINDENT -.SS Legacy Configuration -.sp -Winrepo settings were changed with the introduction of the Next Generation (ng) -of winrepo. -.SS Legacy Master Config Options -.sp -There were three options available for a legacy master to configure winrepo. -Unless you\(aqre running a legacy master as well, you shouldn\(aqt need to configure -any of these. -.INDENT 0.0 +\fI\%https://foo.com/bar/baz.git\fP repo is initialized and cloned under the \fBwin_repo_dir_ng\fP directory. .IP \(bu 2 -\fBwin_gitrepos\fP +\fI\%https://mydomain.tld/baz.git\fP repo is initialized and cloned under the \fBwin_repo_dir_ng\ebaz_junior\fP directory. .IP \(bu 2 -\fBwin_repo\fP -.IP \(bu 2 -\fBwin_repo_mastercachefile\fP +\fI\%https://github.com/foobar/baz.git\fP repo is initialized and cloned under the \fBwin_repo_dir_ng\ebaz_the_third\fP directory. .UNINDENT -.sp -\fBwin_gitrepos\fP: (list) -.sp -A list of URLs to github repos. Default is a list with a single URL: -.INDENT 0.0 -.IP \(bu 2 -\(aq\fI\%https://github.com/saltstack/salt\-winrepo.git\fP\(aq -.UNINDENT -.sp -\fBwin_repo\fP: (str) -.sp -The location on the master to store the winrepo. The default is -\fB/srv/salt/win/repo\fP\&. -.sp -\fBwin_repo_mastercachefile\fP: (str) -The location on the master to generate the winrepo database file. The default is -\fB/srv/salt/win/repo/winrep.p\fP -.SS Legacy Minion Config Options -.sp -There is only one option available to configure a legacy minion for winrepo. -.INDENT 0.0 -.IP \(bu 2 -\fBwin_repo_cachefile\fP -.UNINDENT -.sp -\fBwin_repo_cachefile\fP: (str) -.sp -The location on the Salt file server to obtain the winrepo database file. The -default is \fBsalt://win/repo/winrepo.p\fP -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -If the location of the \fBwinrepo.p\fP file is not in the default location on -the master, the \fI\%win_repo_cachefile\fP setting will need to be -updated to reflect the proper location on each minion. -.UNINDENT -.UNINDENT -.SS Legacy Quick Start -.sp -You can get up and running with winrepo pretty quickly just using the defaults. -Assuming no changes to the default configuration (ie, \fBfile_roots\fP) run the -following commands on the master: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-run winrepo.update_git_repos -salt\-run winrepo.genrepo -salt * pkg.refresh_db -salt * pkg.install firefox -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -These commands clone the default winrepo from github, generate the metadata -file, push the metadata file down to the legacy minion, and install the latest -version of Firefox. -.SS Legacy Initialization -.sp -Initializing the winrepo for a legacy minion is similar to that for a newer -minion. There is an added step in that the metadata file needs to be generated -on the master prior to refreshing the database on the minion. -.SS Populate the Local Repository -.sp -The SLS files used to install Windows packages are not distributed by default -with Salt. So, the first step is to clone the repo to the master. Use the -\fI\%winrepo.update_git_repos\fP -runner initialize the repository in the location specified by \fBwinrepo_dir\fP -in the master config. This will pull the software definition files down from the -git repository. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-run winrepo.update_git_repos -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Generate the Metadata File -.sp -The next step is to create the metadata file for the repo (\fBwinrepo.p\fP). -The metadata file is generated on the master using the -\fI\%winrepo.genrepo\fP runner. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -salt\-run winrepo.genrepo -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -You only need to do this if you need to support legacy minions. -.UNINDENT -.UNINDENT -.SS Update the Minion Database -.sp -Run \fI\%pkg.refresh_db\fP on each of your -Windows minions to copy the metadata file down to the minion. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -# From the master -salt \-G \(aqos:windows\(aq pkg.refresh_db -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Changes in Version 2015.8.0+ -.sp -Git repository management for the Windows Software Repository changed in version -2015.8.0, and several master/minion config parameters were renamed for -consistency. -.sp -For a complete list of the new winrepo config options, see -\fI\%here\fP for master config options, and -\fI\%here\fP for configuration options for masterless Windows -minions. -.SS \fI\%pygit2\fP/\fI\%GitPython\fP Support -.sp -On the master, the -\fI\%winrepo.update_git_repos\fP -runner was updated to use either \fI\%pygit2\fP or \fI\%GitPython\fP to checkout the git -repositories containing repo data. If \fI\%pygit2\fP or \fI\%GitPython\fP is installed, -existing winrepo git checkouts should be removed after upgrading to 2015.8.0. -Then they should be cloned again by running -\fI\%winrepo.update_git_repos\fP\&. -.sp -If neither \fI\%GitPython\fP nor \fI\%pygit2\fP are installed, Salt will fall back to -pre\-existing behavior for -\fI\%winrepo.update_git_repos\fP, and a -warning will be logged in the master log. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -Standalone Windows minions do not support the new \fI\%GitPython\fP/\fI\%pygit2\fP -functionality, and will instead use the -\fI\%git.latest\fP state to keep repositories -up\-to\-date. More information on how to use the Windows Software Repo on a -standalone minion can be found \fI\%here\fP\&. -.UNINDENT -.UNINDENT -.SS Config Parameters Renamed -.sp -Many of the legacy winrepo configuration parameters changed in version 2015.8.0 -to make them more consistent. Below are the parameters which changed for -version 2015.8.0: -.sp -Master Config -.TS -center; -|l|l|. -_ -T{ -Old Name -T} T{ -New Name -T} -_ -T{ -win_repo -T} T{ -\fI\%winrepo_dir\fP -T} -_ -T{ -win_repo_mastercachefile -T} T{ -No longer used on master -T} -_ -T{ -win_gitrepos -T} T{ -\fI\%winrepo_remotes\fP -T} -_ -.TE -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fBwinrepo_dir_ng\fP and \fBwinrepo_remotes_ng\fP settings were introduced -in 2015.8.0 for working with the next generation repo. -.UNINDENT -.UNINDENT -.sp -See \fI\%here\fP for detailed information on all -master config options for the Windows Repo. -.sp -Minion Config -.TS -center; -|l|l|. -_ -T{ -Old Name -T} T{ -New Name -T} -_ -T{ -win_repo -T} T{ -\fI\%winrepo_dir\fP -T} -_ -T{ -win_repo_cachefile -T} T{ -\fI\%winrepo_cachefile\fP -T} -_ -T{ -win_gitrepos -T} T{ -\fI\%winrepo_remotes\fP -T} -_ -.TE -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -The \fBwinrepo_dir_ng\fP and \fBwinrepo_remotes_ng\fP settings were introduced -in 2015.8.0 for working with the next generation repo. -.UNINDENT -.UNINDENT -.sp -See \fI\%here\fP for detailed information on all -minion config options for the Windows Repo. .SS Windows\-specific Behaviour .sp Salt is capable of managing Windows systems, however due to various differences @@ -468188,6 +461134,10 @@ Development begins on \fBAluminium\fP, or \fBv3003\fP, after the \fBv3002\fP tag applied to the \fBmaster\fP branch. Once this occurs, all uses of the \fBwarn_until\fP function targeting \fBAluminium\fP, along with the code they are warning about should be removed from the code. +.SS Silence Deprecation Warnings +.sp +If you set the \fIPYTHONWARNINGS\fP environment variable to \fIignore\fP Salt will +not print the deprecation warnings. .SS Python 2 Deprecation FAQ .SS FAQ .INDENT 0.0 @@ -469810,6 +462760,92 @@ Please be certain to scrub any logs or SLS files for sensitive data! .UNINDENT .UNINDENT .UNINDENT +.SS Salt Extensions +.sp +Salt modules can be distributed as Salt Extensions. +.sp +The existing Salt modules will be carved up into one of three categories. Each category will be +implemented in the following way: +.sp +## Core Modules +.sp +Core Modules will be kept inside the main Salt codebase, and development will be tied to the +Salt release cycle. +.sp +## Supported Modules +.sp +Supported modules will be moved to their own repositories within the SaltStack Github +organization where they can be maintained separately from the Salt codebase. +.sp +## Community Modules +.sp +Remaining modules will be deprecated from the Salt Core codebase and community members +will be able to continue independent maintainership if they are interested. Some plugins are +almost exclusively maintained by external corporations – if these corporations wish for formal +documentation outlining transfer of ownership it can be handled on a case\-by\-case basis. The +community modules can be hosted either in individual or corporate source control systems, +alternatively they can also be hosted in the community run Salt Extensions Github organization, +that will operate like the the Salt Formulas Github organization. +The criteria to determine which category to place modules in will follow these rules: +.sp +## Core Modules +.INDENT 0.0 +.IP 1. 3 +Required Salt Functionality +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP a. 3 +Modules such as state, sys, peer, grains, pillar, etc. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.IP 2. 3 +Modules critical to Salt’s Multi OS support +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP a. 3 +Modules that function across multiple operating systems like cmd and file. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +## Supported Modules +.sp +1. Modules to support specific operating systems traditionally maintained by the core team +– such as RedHat, MacOS, Windows, Solaris, etc. +.INDENT 0.0 +.IP 2. 3 +Modules to support specific but critical applications, such as Apache, MySQL, etc. +.UNINDENT +.sp +3. Modules created and maintained as part of VMware backed support agreements and +contracts. +.sp +## Community Extension Modules +.sp +1. Modules to support specific operating systems traditionally maintained by the OS vendor +– such as SUSE, openBSD, NetBSD, etc. +.INDENT 0.0 +.IP 2. 3 +Modules to support cloud interfaces, such as AWS, Azure, etc. +.UNINDENT +.sp +3. Modules no longer maintained, or which we suspect are also no longer used or +maintained, such as moosefs, qemu_img, etc. +.SS How do I deprecate a Salt module to a Salt extension +.sp +To indicate that a Salt module is being deprecated in favor of a Salt extension, +for each Salt module include \fB__deprecated__\fP tuple in the module. The tuple +should include the version of Salt that the module will be removed, the name of the +collection of modules that are being deprecated, and the URL where the source for +the new extension can be found. The version should be 2 major versions from the +next major release. For example, if the next major release of Salt is 3100, the +deprecation version should be set to 3102. .SS Salt Topology .sp Salt is based on a powerful, asynchronous, network topology using ZeroMQ. Many @@ -470530,7 +463566,7 @@ dynamic modules when states are run. To disable this behavior set \fI\%autoload_dynamic_modules\fP to \fBFalse\fP in the minion config. .sp When dynamic modules are autoloaded via states, only the modules defined in the -same saltenvs as the states currently being run. +same saltenv as the states currently being run are synced. .SS Sync Via the saltutil Module .sp The saltutil module has a number of functions that can be used to sync all @@ -470538,6 +463574,8 @@ or specific dynamic modules. The \fBsaltutil.sync_*\fP \fI\%execution functions\fP and \fI\%runner functions\fP can be used to sync modules to minions and the master, respectively. +.sp +If saltenv environments are used (through the \fI\%top file\fP, the \fI\%environment\fP option of the minion configuration file, or as an argument on the command line) modules will be synced from the applied environments. .SS The extmods Directory .sp Any files places in the directory set by \fBextension_modules\fP settings @@ -470680,7 +463718,7 @@ _ T{ Log Handler T} T{ -\fBsalt.log.handlers\fP (\fI\%index\fP) +\fBsalt.log_handlers\fP (\fI\%index\fP) T} T{ \fBlog_handlers\fP T} T{ @@ -470842,7 +463880,7 @@ SSH Wrapper T} T{ \fBsalt.client.ssh.wrapper\fP T} T{ -\fBwrapper\fP [1] +\fBwrapper\fP T} T{ \fBwrapper_dirs\fP T} @@ -477108,6 +470146,405 @@ See the \fI\%version numbers\fP page for more information about the version numbering scheme. .UNINDENT .SS Upcoming release +(release\-3007.0)= +.SS Salt 3007.0 release notes +.SS Salt\(aqs \fBsetup.py\fP customizations +.INDENT 0.0 +.INDENT 3.5 +:warning: \fBDeprecation Notice\fP: +In Salt 3009, the \fBsetup.py\fP file will be stripped of it\(aqs custom additions and migrated to a plain \fBpyproject.toml\fP python package +or whatever is found best during the process of removing the customizations. +\fBIf you\(aqre relying on these customizations please stop as your workflow will break in the future\fP\&. +.UNINDENT +.UNINDENT +.SS Python 3.7 Support Dropped +.sp +Support for python 3.7 has been dropped since it reached end\-of\-line in 27 Jun 2023. +.SS Azure Salt Extension +.sp +Starting from Salt version 3007.0, the Azure functionality previously available in the Salt code base is fully removed. To continue using Salt\(aqs features for interacting with Azure resources, users are required to utilize the Azure Salt extension. For more information, refer to the \fI\%Azure Salt Extension GitHub repository\fP\&. +.SS New Package Grain +.sp +A new \fBpackage\fP grain was added in 3007.0 This detects how Salt was installed using the \fB_pkg.txt\fP in the root of +the directory. If you are building packages of Salt you need to ensure this file is set to the correct package type +that you are building. The options are \fBpip\fP, \fBonedir\fP, or \fBsystem\fP\&. By default this file is already set to \fBpip\fP\&. +.SS Improved Vault integration +.sp +This release features a much deeper integration with HashiCorp Vault, for which +many parts of the implementation core were improved. Among other things, the Salt +daemons now attempt to renew/revoke their access tokens and can manage long\-lived leases, +while the Salt master now distributes authentication secrets using response wrapping. +An important new feature concerns the way Vault policies can be managed. +.sp +In versions before 3006, the Salt master only issued tokens to minions, whose policies +could be templated with the minion ID and (insecure) grain values. +3006 introduced secure templating of those policies with pillar values, as well as +templating of Vault external pillar paths with pillar values. These improvements reduced the +overhead of managing Vault policies securely. +.sp +In addition, the Salt master can now be configured to issue AppRoles +to minions and manage their metadata using a similar templating approach. +Since this metadata can be taken advantage of in templated policies on the Vault side, +the need for many boilerplate policies is reduced even further: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + path \(dqsalt/data/minions/{{identity.entity.metadata.minion\-id}}\(dq { + capabilities = [\(dqcreate\(dq, \(dqread\(dq, \(dqwrite\(dq, \(dqdelete\(dq, \(dqpatch\(dq] + } + + path \(dqsalt/data/roles/{{identity.entity.metadata.role}}\(dq { + capabilities = [\(dqread\(dq] + } + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Although existing configurations will keep working without intervention after upgrading +the Salt master, it is strongly recommended to adjust the \fBpeer_run\fP configuration to +include the new issuance endpoints in order to avoid unnecessary overhead: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +peer_run: + .*: + \- vault.get_config + \- vault.generate_new_token + +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Please see the \fI\%Vault execution module docs\fP for +details and setup instructions regarding AppRole issuance. +.sp +Note: The Vault modules are being moved to a \fI\%Salt extension\fP, +but this improvement has still been merged into core for a smoother transition. +.SS Changelog +.SS Removed +.INDENT 0.0 +.IP \(bu 2 +Removed RHEL 5 support since long since end\-of\-lifed \fI\%#62520\fP +.IP \(bu 2 +Removing Azure\-Cloud modules from the code base. \fI\%#64322\fP +.IP \(bu 2 +Dropped Python 3.7 support since it\(aqs EOL in 27 Jun 2023 \fI\%#64417\fP +.IP \(bu 2 +Remove salt.payload.Serial \fI\%#64459\fP +.IP \(bu 2 +Remove netmiko_conn and pyeapi_conn from salt.modules.napalm_mod \fI\%#64460\fP +.IP \(bu 2 +Removed \(aqtransport\(aq arg from salt.utils.event.get_event \fI\%#64461\fP +.IP \(bu 2 +Removed the usage of retired Linode API v3 from Salt Cloud \fI\%#64517\fP +.UNINDENT +.SS Deprecated +.INDENT 0.0 +.IP \(bu 2 +Deprecate all Proxmox cloud modules \fI\%#64224\fP +.IP \(bu 2 +Deprecate all the Vault modules in favor of the Vault Salt Extension \fI\%https://github.com/salt\-extensions/saltext\-vault\fP\&. The Vault modules will be removed in Salt core in 3009.0. \fI\%#64893\fP +.IP \(bu 2 +Deprecate all the Docker modules in favor of the Docker Salt Extension \fI\%https://github.com/saltstack/saltext\-docker\fP\&. The Docker modules will be removed in Salt core in 3009.0. \fI\%#64894\fP +.IP \(bu 2 +Deprecate all the Zabbix modules in favor of the Zabbix Salt Extension \fI\%https://github.com/salt\-extensions/saltext\-zabbix\fP\&. The Zabbix modules will be removed in Salt core in 3009.0. \fI\%#64896\fP +.IP \(bu 2 +Deprecate all the Apache modules in favor of the Apache Salt Extension \fI\%https://github.com/salt\-extensions/saltext\-apache\fP\&. The Apache modules will be removed in Salt core in 3009.0. \fI\%#64909\fP +.IP \(bu 2 +Deprecation warning for Salt\(aqs backport of \fBOrderedDict\fP class which will be removed in 3009 \fI\%#65542\fP +.IP \(bu 2 +Deprecate Kubernetes modules for move to saltext\-kubernetes in version 3009 \fI\%#65565\fP +.IP \(bu 2 +Deprecated all Pushover modules in favor of the Salt Extension at \fI\%https://github.com/salt\-extensions/saltext\-pushover\fP\&. The Pushover modules will be removed from Salt core in 3009.0 \fI\%#65567\fP +.IP \(bu 2 +Removed deprecated code: +.INDENT 2.0 +.IP \(bu 2 +All of \fBsalt/log/\fP which has been on a deprecation path for a long time. +.IP \(bu 2 +Some of the logging handlers found in \fBsalt/_logging/handlers\fP have been removed since the standard library provides +them. +.IP \(bu 2 +Removed the deprecated \fBsalt/modules/cassandra_mod.py\fP module and any tests for it. +.IP \(bu 2 +Removed the deprecated \fBsalt/returners/cassandra_return.py\fP module and any tests for it. +.IP \(bu 2 +Removed the deprecated \fBsalt/returners/django_return.py\fP module and any tests for it. \fI\%#65986\fP +.UNINDENT +.UNINDENT +.SS Changed +.INDENT 0.0 +.IP \(bu 2 +Masquerade property will not default to false turning off masquerade if not specified. \fI\%#53120\fP +.IP \(bu 2 +Addressed Python 3.11 deprecations: +.INDENT 2.0 +.IP \(bu 2 +Switch to \fBFullArgSpec\fP since Py 3.11 no longer has \fBArgSpec\fP, deprecated since Py 3.0 +.IP \(bu 2 +Stopped using the deprecated \fBcgi\fP module. +.IP \(bu 2 +Stopped using the deprecated \fBpipes\fP module +.IP \(bu 2 +Stopped using the deprecated \fBimp\fP module \fI\%#64457\fP +.UNINDENT +.IP \(bu 2 +changed \(aqgpg_decrypt_must_succeed\(aq default from False to True \fI\%#64462\fP +.UNINDENT +.SS Fixed +.INDENT 0.0 +.IP \(bu 2 +When an NFS or FUSE mount fails to unmount when mount options have changed, try again with a lazy umount before mounting again. \fI\%#18907\fP +.IP \(bu 2 +fix autoaccept gpg keys by supporting it in refresh_db module \fI\%#42039\fP +.IP \(bu 2 +Made cmd.script work with files from the fileserver via salt\-ssh \fI\%#48067\fP +.IP \(bu 2 +Made slsutil.renderer work with salt\-ssh \fI\%#50196\fP +.IP \(bu 2 +Fixed defaults.merge is not available when using salt\-ssh \fI\%#51605\fP +.IP \(bu 2 +Fix extfs.mkfs missing parameter handling for \-C, \-d, and \-e \fI\%#51858\fP +.IP \(bu 2 +Fixed Salt master does not renew token \fI\%#51986\fP +.IP \(bu 2 +Fixed salt\-ssh continues state/pillar rendering with incorrect data when an exception is raised by a module on the target \fI\%#52452\fP +.IP \(bu 2 +Fix extfs.tune has \(aqreserved\(aq documented twice and is missing the \(aqreserved_percentage\(aq keyword argument \fI\%#54426\fP +.IP \(bu 2 +Fix the ability of the \(aqselinux.port_policy_present\(aq state to modify. \fI\%#55687\fP +.IP \(bu 2 +Fixed config.get does not support merge option with salt\-ssh \fI\%#56441\fP +.IP \(bu 2 +Removed an unused assignment in file.patch \fI\%#57204\fP +.IP \(bu 2 +Fixed vault module fetching more than one secret in one run with single\-use tokens \fI\%#57561\fP +.IP \(bu 2 +Use brew path from which in mac_brew_pkg module and rely on _homebrew_bin() everytime \fI\%#57946\fP +.IP \(bu 2 +Fixed Vault verify option to work on minions when only specified in master config \fI\%#58174\fP +.IP \(bu 2 +Fixed vault command errors configured locally \fI\%#58580\fP +.IP \(bu 2 +Fixed issue with basic auth causing invalid header error and 401 Bad Request, by using HTTPBasicAuthHandler instead of header. \fI\%#58936\fP +.IP \(bu 2 +Make the LXD module work with pyLXD > 2.10 \fI\%#59514\fP +.IP \(bu 2 +Return error if patch file passed to state file.patch is malformed. \fI\%#59806\fP +.IP \(bu 2 +Handle failure and error information from tuned module/state \fI\%#60500\fP +.IP \(bu 2 +Fixed sdb.get_or_set_hash with Vault single\-use tokens \fI\%#60779\fP +.IP \(bu 2 +Fixed state.test does not work with salt\-ssh \fI\%#61100\fP +.IP \(bu 2 +Made slsutil.findup work with salt\-ssh \fI\%#61143\fP +.IP \(bu 2 +Allow all primitive grain types for autosign_grains \fI\%#61416\fP, \fI\%#63708\fP +.IP \(bu 2 +\fBipset.new_set\fP no longer fails when creating a set type that uses the \fBfamily\fP create option \fI\%#61620\fP +.IP \(bu 2 +Fixed Vault session storage to allow unlimited use tokens \fI\%#62380\fP +.IP \(bu 2 +fix the efi grain on FreeBSD \fI\%#63052\fP +.IP \(bu 2 +Fixed gpg.receive_keys returns success on failed import \fI\%#63144\fP +.IP \(bu 2 +Fixed GPG state module always reports success without changes \fI\%#63153\fP +.IP \(bu 2 +Fixed GPG state module does not respect test mode \fI\%#63156\fP +.IP \(bu 2 +Fixed gpg.absent with gnupghome/user, fixed gpg.delete_key with gnupghome \fI\%#63159\fP +.IP \(bu 2 +Fixed service module does not handle enable/disable if systemd service is an alias \fI\%#63214\fP +.IP \(bu 2 +Made x509_v2 compound match detection use new runner instead of peer publishing \fI\%#63278\fP +.IP \(bu 2 +Need to make sure we update \fBpillar\fP during a pillar refresh to ensure that process_beacons has the updated beacons loaded from pillar. \fI\%#63583\fP +.IP \(bu 2 +This implements the vpc_uuid parameter when creating a droplet. This parameter selects the correct virtual private cloud (private network interface). \fI\%#63714\fP +.IP \(bu 2 +pkg.installed no longer reports failure when installing packages that are installed via the task manager \fI\%#63767\fP +.IP \(bu 2 +mac_xattr.list and mac_xattr.read will replace undecode\-able bytes to avoid raising CommandExecutionError. \fI\%#63779\fP \fI\%#63779\fP +.IP \(bu 2 +Fix aptpkg.latest_version performance, reducing number of times to \(aqshell out\(aq \fI\%#63982\fP +.IP \(bu 2 +Added option to use a fresh connection for mysql cache \fI\%#63991\fP +.IP \(bu 2 +[lxd] Fixed a bug in \fBcontainer_create\fP which prevented devices which are not of type \fBdisk\fP to be correctly created and added to the container when passed via the \fBdevices\fP parameter. \fI\%#63996\fP +.IP \(bu 2 +Skipped the \fBisfile\fP check to greatly increase speed of reading minion keys for systems with a large number of minions on slow file storage \fI\%#64260\fP +.IP \(bu 2 +Fix utf8 handling in \(aqpass\(aq renderer \fI\%#64300\fP +.IP \(bu 2 +Upgade tornado to 6.3.2 \fI\%#64305\fP +.IP \(bu 2 +Prevent errors due missing \(aqtransactional_update.apply\(aq on SLE Micro and MicroOS. \fI\%#64369\fP +.IP \(bu 2 +Fix \(aqunable to unmount\(aq failure to return False result instead of None \fI\%#64420\fP +.IP \(bu 2 +Fixed issue uninstalling duplicate packages in \fBwin_appx\fP execution module \fI\%#64450\fP +.IP \(bu 2 +Clean up tech debt, IPC now uses tcp transport. \fI\%#64488\fP +.IP \(bu 2 +Made salt\-ssh more strict when handling unexpected situations and state.* wrappers treat a remote exception as failure, excluded salt\-ssh error returns from mine \fI\%#64531\fP +.IP \(bu 2 +Fix flaky test for LazyLoader with isolated mocking of threading.RLock \fI\%#64567\fP +.IP \(bu 2 +Fix possible \fBKeyError\fP exceptions in \fBsalt.utils.user.get_group_dict\fP +while reading improper duplicated GID assigned for the user. \fI\%#64599\fP +.IP \(bu 2 +changed vm_config() to deep\-merge vm_overrides of specific VM, instead of simple\-merging the whole vm_overrides \fI\%#64610\fP +.IP \(bu 2 +Fix the way Salt tries to get the Homebrew\(aqs prefix +.sp +The first attempt to get the Homebrew\(aqs prefix is to look for +the \fBHOMEBREW_PREFIX\fP environment variable. If it\(aqs not set, then +Salt tries to get the prefix from the \fBbrew\fP command. However, the +\fBbrew\fP command can fail. So a last attempt is made to get the +prefix by guessing the installation path. \fI\%#64924\fP +.IP \(bu 2 +Add missing MySQL Grant SERVICE_CONNECTION_ADMIN to mysql module. \fI\%#64934\fP +.IP \(bu 2 +Fixed slsutil.update with salt\-ssh during template rendering \fI\%#65067\fP +.IP \(bu 2 +Keep track when an included file only includes sls files but is a requisite. \fI\%#65080\fP +.IP \(bu 2 +Fixed \fBgpg.present\fP succeeds when the keyserver is unreachable \fI\%#65169\fP +.IP \(bu 2 +Fix typo in nftables module to ensure unique nft family values \fI\%#65295\fP +.IP \(bu 2 +Dereference symlinks to set proper __cli opt \fI\%#65435\fP +.IP \(bu 2 +Made salt\-ssh merge master top returns for the same environment \fI\%#65480\fP +.IP \(bu 2 +Account for situation where the metadata grain fails because the AWS environment requires an authentication token to query the metadata URL. \fI\%#65513\fP +.IP \(bu 2 +Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. \fI\%#65562\fP +.IP \(bu 2 +Added SSH wrapper for logmod \fI\%#65630\fP +.IP \(bu 2 +Include changes in the results when schedule.present state is run with test=True. \fI\%#65652\fP +.IP \(bu 2 +Fix extfs.tune doesn\(aqt pass retcode to module.run \fI\%#65686\fP +.IP \(bu 2 +Return an error message when the DNS plugin is not supported \fI\%#65739\fP +.IP \(bu 2 +Execution modules have access to regular fileclient durring pillar rendering. \fI\%#66124\fP +.IP \(bu 2 +Fixed a issue with server channel where a minion\(aqs public key +would be rejected if it contained a final newline character. \fI\%#66126\fP +.UNINDENT +.SS Added +.INDENT 0.0 +.IP \(bu 2 +Allowed publishing to regular minions from the SSH wrapper \fI\%#40943\fP +.IP \(bu 2 +Added syncing of custom salt\-ssh wrappers \fI\%#45450\fP +.IP \(bu 2 +Made salt\-ssh sync custom utils \fI\%#53666\fP +.IP \(bu 2 +Add ability to use file.managed style check_cmd in file.serialize \fI\%#53982\fP +.IP \(bu 2 +Revised use of deprecated net\-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 \fI\%#57541\fP +.IP \(bu 2 +Added password support to Redis returner. \fI\%#58044\fP +.IP \(bu 2 +Added a state (win_task) for managing scheduled tasks on Windows \fI\%#59037\fP +.IP \(bu 2 +Added keyring param to gpg modules \fI\%#59783\fP +.IP \(bu 2 +Added new grain to detect the Salt package type: onedir, pip or system \fI\%#62589\fP +.IP \(bu 2 +Added Vault AppRole and identity issuance to minions \fI\%#62823\fP +.IP \(bu 2 +Added Vault AppRole auth mount path configuration option \fI\%#62825\fP +.IP \(bu 2 +Added distribution of Vault authentication details via response wrapping \fI\%#62828\fP +.IP \(bu 2 +Add salt package type information. Either onedir, pip or system. \fI\%#62961\fP +.IP \(bu 2 +Added signature verification to file.managed/archive.extracted \fI\%#63143\fP +.IP \(bu 2 +Added signed_by_any/signed_by_all parameters to gpg.verify \fI\%#63166\fP +.IP \(bu 2 +Added match runner \fI\%#63278\fP +.IP \(bu 2 +Added Vault token lifecycle management \fI\%#63406\fP +.IP \(bu 2 +adding new call for openscap xccdf eval supporting new parameters \fI\%#63416\fP +.IP \(bu 2 +Added Vault lease management utility \fI\%#63440\fP +.IP \(bu 2 +implement removal of ptf packages in zypper pkg module \fI\%#63442\fP +.IP \(bu 2 +add JUnit output for saltcheck \fI\%#63463\fP +.IP \(bu 2 +Add ability for file.keyvalue to create a file if it doesn\(aqt exist \fI\%#63545\fP +.IP \(bu 2 +added cleanup of temporary mountpoint dir for macpackage installed state \fI\%#63905\fP +.IP \(bu 2 +Add pkg.installed show installable version in test mode \fI\%#63985\fP +.IP \(bu 2 +Added patch option to Vault SDB driver \fI\%#64096\fP +.IP \(bu 2 +Added flags to create local users and groups \fI\%#64256\fP +.IP \(bu 2 +Added inline specification of trusted CA root certificate for Vault \fI\%#64379\fP +.IP \(bu 2 +Add ability to return False result in test mode of configurable_test_state \fI\%#64418\fP +.IP \(bu 2 +Switched Salt\(aqs onedir Python version to 3.11 \fI\%#64457\fP +.IP \(bu 2 +Added support for dnf5 and its new command syntax \fI\%#64532\fP +.IP \(bu 2 +Adding a new decorator to indicate when a module is deprecated in favor of a Salt extension. \fI\%#64569\fP +.IP \(bu 2 +Add jq\-esque to_entries and from_entries functions \fI\%#64600\fP +.IP \(bu 2 +Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. \fI\%#64660\fP +.IP \(bu 2 +Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False \fI\%#64665\fP +.IP \(bu 2 +Strenghten Salt\(aqs HA capabilities with master clustering. \fI\%#64939\fP +.IP \(bu 2 +Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems \fI\%#64978\fP +.IP \(bu 2 +Add support for show_jid to salt\-run +.sp +Adds support for show_jid master config option to salt\-run, so its behaviour matches the salt cli command. \fI\%#65008\fP +.IP \(bu 2 +Add ability to remove packages by wildcard via apt execution module \fI\%#65220\fP +.IP \(bu 2 +Added support for master top modules on masterless minions \fI\%#65479\fP +.IP \(bu 2 +Allowed accessing the regular mine from the SSH wrapper \fI\%#65645\fP +.IP \(bu 2 +Allow enabling backup for Linode in Salt Cloud \fI\%#65697\fP +.IP \(bu 2 +Add a backup schedule setter fFunction for Linode VMs \fI\%#65713\fP +.IP \(bu 2 +Add acme support for manual plugin hooks \fI\%#65744\fP +.UNINDENT +.SS Security +.INDENT 0.0 +.IP \(bu 2 +Upgrade to \fBtornado>=6.3.3\fP due to \fI\%https://github.com/advisories/GHSA\-qppv\-j76h\-2rpx\fP \fI\%#64989\fP +.IP \(bu 2 +Update to \fBgitpython>=3.1.35\fP due to \fI\%https://github.com/advisories/GHSA\-wfm5\-v35h\-vwf4\fP and \fI\%https://github.com/advisories/GHSA\-cwvm\-v4w8\-q58c\fP \fI\%#65137\fP +.UNINDENT +.sp +See \fI\%Install a release candidate\fP +for more information about installing an RC when one is available. +.SS Previous releases (release\-3006.0)= .SS Salt 3006.0 release notes .SS Onedir packaging @@ -478467,10 +471904,6 @@ In the process, we were also required to update to \fBpyOpenSSL==24.0.0\fP \fI\% .IP \(bu 2 Bump to \fBcryptography==42.0.3\fP due to \fI\%https://github.com/advisories/GHSA\-3ww4\-gg4f\-jr7f\fP \fI\%#66090\fP .UNINDENT -.sp -See \fI\%Install a release candidate\fP -for more information about installing an RC when one is available. -.SS Previous releases .SS Salt 3005 release notes \- Codename Phosphorus .SS Python 3.5 and 3.6 deprecation .sp @@ -493359,7 +486792,7 @@ backends: .IP \(bu 2 \fI\%roots_update_interval\fP .IP \(bu 2 -\fI\%azurefs_update_interval\fP +\fBazurefs_update_interval\fP .IP \(bu 2 \fI\%gitfs_update_interval\fP .IP \(bu 2 @@ -531637,7 +525070,7 @@ newer Azure Portal website. .SS Clouds .INDENT 0.0 .IP \(bu 2 -\fI\%salt.cloud.clouds.azurearm\fP +\fBsalt.cloud.clouds.azurearm\fP .UNINDENT .SS Engines .INDENT 0.0 @@ -536520,7 +529953,7 @@ salt\-cloud will check for the presence of the master configuration parameter will be performed on the userdata_file. .sp In addition, the other cloud drivers which support setting a \fBuserdata_file\fP -(\fI\%azurearm\fP, \fBnova\fP, and \fI\%openstack\fP) +(\fBazurearm\fP, \fBnova\fP, and \fI\%openstack\fP) have had templating support added to bring them to feature parity with the ec2 driver\(aqs implementation of the \fBuserdata_file\fP option. .SS Changelog for v2016.11.3..v2016.11.4 @@ -559340,8 +552773,7 @@ later minions. When using this new repository, the repo cache is compiled on the Salt Minion, which enables pillar, grains and other things to be available during compilation time. .sp -See the \fI\%Windows Software Repository\fP -documentation for more information. +See the Windows Software Repository documentation for more information. .SS Changes to legacy Windows repository .sp If you have pre 2015.8 Windows minions connecting to your 2015.8 Salt master, you @@ -559351,8 +552783,7 @@ If you were previously using this repository and have customized settings, be aware that several config options have been renamed to make their naming more consistent. .sp -See the \fI\%Windows Software Repository\fP -documentation for more information. +See the Windows Software Repository documentation for more information. .SS Win System Module .sp The unit of the \fBtimeout\fP parameter in the \fBsystem.halt\fP, @@ -602075,7 +595506,7 @@ The mysql_user state enables mysql user management. The virtualenv state can manage the state of Python virtual environments. Thanks to Whitinge for the virtualenv state .SS New Returners -.SS \fI\%cassandra_returner\fP +.SS \fBcassandra_returner\fP .sp A returner allowing Salt to send data to a cassandra server. Thanks to Byron Clark for contributing this returner diff --git a/doc/man/spm.1 b/doc/man/spm.1 index f9be92b6be5..155053d433e 100644 --- a/doc/man/spm.1 +++ b/doc/man/spm.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "SPM" "1" "Generated on February 20, 2024 at 09:55:17 PM UTC." "3006.7" "Salt" +.TH "SPM" "1" "Generated on March 03, 2024 at 06:52:04 AM UTC." "3007.0" "Salt" .SH NAME spm \- Salt Package Manager Command .sp diff --git a/doc/topics/releases/3007.0.md b/doc/topics/releases/3007.0.md index 73d955875c7..4f8e70e7419 100644 --- a/doc/topics/releases/3007.0.md +++ b/doc/topics/releases/3007.0.md @@ -102,6 +102,14 @@ This is auto generated - Deprecation warning for Salt's backport of ``OrderedDict`` class which will be removed in 3009 [#65542](https://github.com/saltstack/salt/issues/65542) - Deprecate Kubernetes modules for move to saltext-kubernetes in version 3009 [#65565](https://github.com/saltstack/salt/issues/65565) - Deprecated all Pushover modules in favor of the Salt Extension at https://github.com/salt-extensions/saltext-pushover. The Pushover modules will be removed from Salt core in 3009.0 [#65567](https://github.com/saltstack/salt/issues/65567) +- Removed deprecated code: + + * All of ``salt/log/`` which has been on a deprecation path for a long time. + * Some of the logging handlers found in ``salt/_logging/handlers`` have been removed since the standard library provides + them. + * Removed the deprecated ``salt/modules/cassandra_mod.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/cassandra_return.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/django_return.py`` module and any tests for it. [#65986](https://github.com/saltstack/salt/issues/65986) ### Changed @@ -181,8 +189,6 @@ This is auto generated - Fixed slsutil.update with salt-ssh during template rendering [#65067](https://github.com/saltstack/salt/issues/65067) - Keep track when an included file only includes sls files but is a requisite. [#65080](https://github.com/saltstack/salt/issues/65080) - Fixed `gpg.present` succeeds when the keyserver is unreachable [#65169](https://github.com/saltstack/salt/issues/65169) -- Fix issue with openscap when the error was outside the expected scope. It now - returns failed with the error code and the error [#65193](https://github.com/saltstack/salt/issues/65193) - Fix typo in nftables module to ensure unique nft family values [#65295](https://github.com/saltstack/salt/issues/65295) - Dereference symlinks to set proper __cli opt [#65435](https://github.com/saltstack/salt/issues/65435) - Made salt-ssh merge master top returns for the same environment [#65480](https://github.com/saltstack/salt/issues/65480) @@ -190,11 +196,11 @@ This is auto generated - Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. [#65562](https://github.com/saltstack/salt/issues/65562) - Added SSH wrapper for logmod [#65630](https://github.com/saltstack/salt/issues/65630) - Include changes in the results when schedule.present state is run with test=True. [#65652](https://github.com/saltstack/salt/issues/65652) -- Fixed Salt-SSH pillar rendering and state rendering with nested SSH calls when called via saltutil.cmd or in an orchestration [#65670](https://github.com/saltstack/salt/issues/65670) - Fix extfs.tune doesn't pass retcode to module.run [#65686](https://github.com/saltstack/salt/issues/65686) -- Fix boto execution module loading [#65691](https://github.com/saltstack/salt/issues/65691) -- Removed PR 65185 changes since incomplete solution [#65692](https://github.com/saltstack/salt/issues/65692) - Return an error message when the DNS plugin is not supported [#65739](https://github.com/saltstack/salt/issues/65739) +- Execution modules have access to regular fileclient durring pillar rendering. [#66124](https://github.com/saltstack/salt/issues/66124) +- Fixed a issue with server channel where a minion's public key + would be rejected if it contained a final newline character. [#66126](https://github.com/saltstack/salt/issues/66126) ### Added @@ -205,6 +211,7 @@ This is auto generated - Add ability to use file.managed style check_cmd in file.serialize [#53982](https://github.com/saltstack/salt/issues/53982) - Revised use of deprecated net-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 [#57541](https://github.com/saltstack/salt/issues/57541) - Added password support to Redis returner. [#58044](https://github.com/saltstack/salt/issues/58044) +- Added a state (win_task) for managing scheduled tasks on Windows [#59037](https://github.com/saltstack/salt/issues/59037) - Added keyring param to gpg modules [#59783](https://github.com/saltstack/salt/issues/59783) - Added new grain to detect the Salt package type: onedir, pip or system [#62589](https://github.com/saltstack/salt/issues/62589) - Added Vault AppRole and identity issuance to minions [#62823](https://github.com/saltstack/salt/issues/62823) @@ -232,6 +239,7 @@ This is auto generated - Add jq-esque to_entries and from_entries functions [#64600](https://github.com/saltstack/salt/issues/64600) - Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. [#64660](https://github.com/saltstack/salt/issues/64660) - Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False [#64665](https://github.com/saltstack/salt/issues/64665) +- Strenghten Salt's HA capabilities with master clustering. [#64939](https://github.com/saltstack/salt/issues/64939) - Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems [#64978](https://github.com/saltstack/salt/issues/64978) - Add support for show_jid to salt-run diff --git a/pkg/debian/changelog b/pkg/debian/changelog index c615e70d78a..680ff3a2683 100644 --- a/pkg/debian/changelog +++ b/pkg/debian/changelog @@ -1,3 +1,180 @@ +salt (3007.0) stable; urgency=medium + + + # Removed + + * Removed RHEL 5 support since long since end-of-lifed [#62520](https://github.com/saltstack/salt/issues/62520) + * Removing Azure-Cloud modules from the code base. [#64322](https://github.com/saltstack/salt/issues/64322) + * Dropped Python 3.7 support since it's EOL in 27 Jun 2023 [#64417](https://github.com/saltstack/salt/issues/64417) + * Remove salt.payload.Serial [#64459](https://github.com/saltstack/salt/issues/64459) + * Remove netmiko_conn and pyeapi_conn from salt.modules.napalm_mod [#64460](https://github.com/saltstack/salt/issues/64460) + * Removed 'transport' arg from salt.utils.event.get_event [#64461](https://github.com/saltstack/salt/issues/64461) + * Removed the usage of retired Linode API v3 from Salt Cloud [#64517](https://github.com/saltstack/salt/issues/64517) + + # Deprecated + + * Deprecate all Proxmox cloud modules [#64224](https://github.com/saltstack/salt/issues/64224) + * Deprecate all the Vault modules in favor of the Vault Salt Extension https://github.com/salt-extensions/saltext-vault. The Vault modules will be removed in Salt core in 3009.0. [#64893](https://github.com/saltstack/salt/issues/64893) + * Deprecate all the Docker modules in favor of the Docker Salt Extension https://github.com/saltstack/saltext-docker. The Docker modules will be removed in Salt core in 3009.0. [#64894](https://github.com/saltstack/salt/issues/64894) + * Deprecate all the Zabbix modules in favor of the Zabbix Salt Extension https://github.com/salt-extensions/saltext-zabbix. The Zabbix modules will be removed in Salt core in 3009.0. [#64896](https://github.com/saltstack/salt/issues/64896) + * Deprecate all the Apache modules in favor of the Apache Salt Extension https://github.com/salt-extensions/saltext-apache. The Apache modules will be removed in Salt core in 3009.0. [#64909](https://github.com/saltstack/salt/issues/64909) + * Deprecation warning for Salt's backport of ``OrderedDict`` class which will be removed in 3009 [#65542](https://github.com/saltstack/salt/issues/65542) + * Deprecate Kubernetes modules for move to saltext-kubernetes in version 3009 [#65565](https://github.com/saltstack/salt/issues/65565) + * Deprecated all Pushover modules in favor of the Salt Extension at https://github.com/salt-extensions/saltext-pushover. The Pushover modules will be removed from Salt core in 3009.0 [#65567](https://github.com/saltstack/salt/issues/65567) + * Removed deprecated code: + + * All of ``salt/log/`` which has been on a deprecation path for a long time. + * Some of the logging handlers found in ``salt/_logging/handlers`` have been removed since the standard library provides + them. + * Removed the deprecated ``salt/modules/cassandra_mod.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/cassandra_return.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/django_return.py`` module and any tests for it. [#65986](https://github.com/saltstack/salt/issues/65986) + + # Changed + + * Masquerade property will not default to false turning off masquerade if not specified. [#53120](https://github.com/saltstack/salt/issues/53120) + * Addressed Python 3.11 deprecations: + + * Switch to `FullArgSpec` since Py 3.11 no longer has `ArgSpec`, deprecated since Py 3.0 + * Stopped using the deprecated `cgi` module. + * Stopped using the deprecated `pipes` module + * Stopped using the deprecated `imp` module [#64457](https://github.com/saltstack/salt/issues/64457) + * changed 'gpg_decrypt_must_succeed' default from False to True [#64462](https://github.com/saltstack/salt/issues/64462) + + # Fixed + + * When an NFS or FUSE mount fails to unmount when mount options have changed, try again with a lazy umount before mounting again. [#18907](https://github.com/saltstack/salt/issues/18907) + * fix autoaccept gpg keys by supporting it in refresh_db module [#42039](https://github.com/saltstack/salt/issues/42039) + * Made cmd.script work with files from the fileserver via salt-ssh [#48067](https://github.com/saltstack/salt/issues/48067) + * Made slsutil.renderer work with salt-ssh [#50196](https://github.com/saltstack/salt/issues/50196) + * Fixed defaults.merge is not available when using salt-ssh [#51605](https://github.com/saltstack/salt/issues/51605) + * Fix extfs.mkfs missing parameter handling for -C, -d, and -e [#51858](https://github.com/saltstack/salt/issues/51858) + * Fixed Salt master does not renew token [#51986](https://github.com/saltstack/salt/issues/51986) + * Fixed salt-ssh continues state/pillar rendering with incorrect data when an exception is raised by a module on the target [#52452](https://github.com/saltstack/salt/issues/52452) + * Fix extfs.tune has 'reserved' documented twice and is missing the 'reserved_percentage' keyword argument [#54426](https://github.com/saltstack/salt/issues/54426) + * Fix the ability of the 'selinux.port_policy_present' state to modify. [#55687](https://github.com/saltstack/salt/issues/55687) + * Fixed config.get does not support merge option with salt-ssh [#56441](https://github.com/saltstack/salt/issues/56441) + * Removed an unused assignment in file.patch [#57204](https://github.com/saltstack/salt/issues/57204) + * Fixed vault module fetching more than one secret in one run with single-use tokens [#57561](https://github.com/saltstack/salt/issues/57561) + * Use brew path from which in mac_brew_pkg module and rely on _homebrew_bin() everytime [#57946](https://github.com/saltstack/salt/issues/57946) + * Fixed Vault verify option to work on minions when only specified in master config [#58174](https://github.com/saltstack/salt/issues/58174) + * Fixed vault command errors configured locally [#58580](https://github.com/saltstack/salt/issues/58580) + * Fixed issue with basic auth causing invalid header error and 401 Bad Request, by using HTTPBasicAuthHandler instead of header. [#58936](https://github.com/saltstack/salt/issues/58936) + * Make the LXD module work with pyLXD > 2.10 [#59514](https://github.com/saltstack/salt/issues/59514) + * Return error if patch file passed to state file.patch is malformed. [#59806](https://github.com/saltstack/salt/issues/59806) + * Handle failure and error information from tuned module/state [#60500](https://github.com/saltstack/salt/issues/60500) + * Fixed sdb.get_or_set_hash with Vault single-use tokens [#60779](https://github.com/saltstack/salt/issues/60779) + * Fixed state.test does not work with salt-ssh [#61100](https://github.com/saltstack/salt/issues/61100) + * Made slsutil.findup work with salt-ssh [#61143](https://github.com/saltstack/salt/issues/61143) + * Allow all primitive grain types for autosign_grains [#61416](https://github.com/saltstack/salt/issues/61416), [#63708](https://github.com/saltstack/salt/issues/63708) + * `ipset.new_set` no longer fails when creating a set type that uses the `family` create option [#61620](https://github.com/saltstack/salt/issues/61620) + * Fixed Vault session storage to allow unlimited use tokens [#62380](https://github.com/saltstack/salt/issues/62380) + * fix the efi grain on FreeBSD [#63052](https://github.com/saltstack/salt/issues/63052) + * Fixed gpg.receive_keys returns success on failed import [#63144](https://github.com/saltstack/salt/issues/63144) + * Fixed GPG state module always reports success without changes [#63153](https://github.com/saltstack/salt/issues/63153) + * Fixed GPG state module does not respect test mode [#63156](https://github.com/saltstack/salt/issues/63156) + * Fixed gpg.absent with gnupghome/user, fixed gpg.delete_key with gnupghome [#63159](https://github.com/saltstack/salt/issues/63159) + * Fixed service module does not handle enable/disable if systemd service is an alias [#63214](https://github.com/saltstack/salt/issues/63214) + * Made x509_v2 compound match detection use new runner instead of peer publishing [#63278](https://github.com/saltstack/salt/issues/63278) + * Need to make sure we update __pillar__ during a pillar refresh to ensure that process_beacons has the updated beacons loaded from pillar. [#63583](https://github.com/saltstack/salt/issues/63583) + * This implements the vpc_uuid parameter when creating a droplet. This parameter selects the correct virtual private cloud (private network interface). [#63714](https://github.com/saltstack/salt/issues/63714) + * pkg.installed no longer reports failure when installing packages that are installed via the task manager [#63767](https://github.com/saltstack/salt/issues/63767) + * mac_xattr.list and mac_xattr.read will replace undecode-able bytes to avoid raising CommandExecutionError. [#63779](https://github.com/saltstack/salt/issues/63779) [#63779](https://github.com/saltstack/salt/issues/63779) + * Fix aptpkg.latest_version performance, reducing number of times to 'shell out' [#63982](https://github.com/saltstack/salt/issues/63982) + * Added option to use a fresh connection for mysql cache [#63991](https://github.com/saltstack/salt/issues/63991) + * [lxd] Fixed a bug in `container_create` which prevented devices which are not of type `disk` to be correctly created and added to the container when passed via the `devices` parameter. [#63996](https://github.com/saltstack/salt/issues/63996) + * Skipped the `isfile` check to greatly increase speed of reading minion keys for systems with a large number of minions on slow file storage [#64260](https://github.com/saltstack/salt/issues/64260) + * Fix utf8 handling in 'pass' renderer [#64300](https://github.com/saltstack/salt/issues/64300) + * Upgade tornado to 6.3.2 [#64305](https://github.com/saltstack/salt/issues/64305) + * Prevent errors due missing 'transactional_update.apply' on SLE Micro and MicroOS. [#64369](https://github.com/saltstack/salt/issues/64369) + * Fix 'unable to unmount' failure to return False result instead of None [#64420](https://github.com/saltstack/salt/issues/64420) + * Fixed issue uninstalling duplicate packages in ``win_appx`` execution module [#64450](https://github.com/saltstack/salt/issues/64450) + * Clean up tech debt, IPC now uses tcp transport. [#64488](https://github.com/saltstack/salt/issues/64488) + * Made salt-ssh more strict when handling unexpected situations and state.* wrappers treat a remote exception as failure, excluded salt-ssh error returns from mine [#64531](https://github.com/saltstack/salt/issues/64531) + * Fix flaky test for LazyLoader with isolated mocking of threading.RLock [#64567](https://github.com/saltstack/salt/issues/64567) + * Fix possible `KeyError` exceptions in `salt.utils.user.get_group_dict` + while reading improper duplicated GID assigned for the user. [#64599](https://github.com/saltstack/salt/issues/64599) + * changed vm_config() to deep-merge vm_overrides of specific VM, instead of simple-merging the whole vm_overrides [#64610](https://github.com/saltstack/salt/issues/64610) + * Fix the way Salt tries to get the Homebrew's prefix + + The first attempt to get the Homebrew's prefix is to look for + the `HOMEBREW_PREFIX` environment variable. If it's not set, then + Salt tries to get the prefix from the `brew` command. However, the + `brew` command can fail. So a last attempt is made to get the + prefix by guessing the installation path. [#64924](https://github.com/saltstack/salt/issues/64924) + * Add missing MySQL Grant SERVICE_CONNECTION_ADMIN to mysql module. [#64934](https://github.com/saltstack/salt/issues/64934) + * Fixed slsutil.update with salt-ssh during template rendering [#65067](https://github.com/saltstack/salt/issues/65067) + * Keep track when an included file only includes sls files but is a requisite. [#65080](https://github.com/saltstack/salt/issues/65080) + * Fixed `gpg.present` succeeds when the keyserver is unreachable [#65169](https://github.com/saltstack/salt/issues/65169) + * Fix typo in nftables module to ensure unique nft family values [#65295](https://github.com/saltstack/salt/issues/65295) + * Dereference symlinks to set proper __cli opt [#65435](https://github.com/saltstack/salt/issues/65435) + * Made salt-ssh merge master top returns for the same environment [#65480](https://github.com/saltstack/salt/issues/65480) + * Account for situation where the metadata grain fails because the AWS environment requires an authentication token to query the metadata URL. [#65513](https://github.com/saltstack/salt/issues/65513) + * Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. [#65562](https://github.com/saltstack/salt/issues/65562) + * Added SSH wrapper for logmod [#65630](https://github.com/saltstack/salt/issues/65630) + * Include changes in the results when schedule.present state is run with test=True. [#65652](https://github.com/saltstack/salt/issues/65652) + * Fix extfs.tune doesn't pass retcode to module.run [#65686](https://github.com/saltstack/salt/issues/65686) + * Return an error message when the DNS plugin is not supported [#65739](https://github.com/saltstack/salt/issues/65739) + * Execution modules have access to regular fileclient durring pillar rendering. [#66124](https://github.com/saltstack/salt/issues/66124) + * Fixed a issue with server channel where a minion's public key + would be rejected if it contained a final newline character. [#66126](https://github.com/saltstack/salt/issues/66126) + + # Added + + * Allowed publishing to regular minions from the SSH wrapper [#40943](https://github.com/saltstack/salt/issues/40943) + * Added syncing of custom salt-ssh wrappers [#45450](https://github.com/saltstack/salt/issues/45450) + * Made salt-ssh sync custom utils [#53666](https://github.com/saltstack/salt/issues/53666) + * Add ability to use file.managed style check_cmd in file.serialize [#53982](https://github.com/saltstack/salt/issues/53982) + * Revised use of deprecated net-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 [#57541](https://github.com/saltstack/salt/issues/57541) + * Added password support to Redis returner. [#58044](https://github.com/saltstack/salt/issues/58044) + * Added a state (win_task) for managing scheduled tasks on Windows [#59037](https://github.com/saltstack/salt/issues/59037) + * Added keyring param to gpg modules [#59783](https://github.com/saltstack/salt/issues/59783) + * Added new grain to detect the Salt package type: onedir, pip or system [#62589](https://github.com/saltstack/salt/issues/62589) + * Added Vault AppRole and identity issuance to minions [#62823](https://github.com/saltstack/salt/issues/62823) + * Added Vault AppRole auth mount path configuration option [#62825](https://github.com/saltstack/salt/issues/62825) + * Added distribution of Vault authentication details via response wrapping [#62828](https://github.com/saltstack/salt/issues/62828) + * Add salt package type information. Either onedir, pip or system. [#62961](https://github.com/saltstack/salt/issues/62961) + * Added signature verification to file.managed/archive.extracted [#63143](https://github.com/saltstack/salt/issues/63143) + * Added signed_by_any/signed_by_all parameters to gpg.verify [#63166](https://github.com/saltstack/salt/issues/63166) + * Added match runner [#63278](https://github.com/saltstack/salt/issues/63278) + * Added Vault token lifecycle management [#63406](https://github.com/saltstack/salt/issues/63406) + * adding new call for openscap xccdf eval supporting new parameters [#63416](https://github.com/saltstack/salt/issues/63416) + * Added Vault lease management utility [#63440](https://github.com/saltstack/salt/issues/63440) + * implement removal of ptf packages in zypper pkg module [#63442](https://github.com/saltstack/salt/issues/63442) + * add JUnit output for saltcheck [#63463](https://github.com/saltstack/salt/issues/63463) + * Add ability for file.keyvalue to create a file if it doesn't exist [#63545](https://github.com/saltstack/salt/issues/63545) + * added cleanup of temporary mountpoint dir for macpackage installed state [#63905](https://github.com/saltstack/salt/issues/63905) + * Add pkg.installed show installable version in test mode [#63985](https://github.com/saltstack/salt/issues/63985) + * Added patch option to Vault SDB driver [#64096](https://github.com/saltstack/salt/issues/64096) + * Added flags to create local users and groups [#64256](https://github.com/saltstack/salt/issues/64256) + * Added inline specification of trusted CA root certificate for Vault [#64379](https://github.com/saltstack/salt/issues/64379) + * Add ability to return False result in test mode of configurable_test_state [#64418](https://github.com/saltstack/salt/issues/64418) + * Switched Salt's onedir Python version to 3.11 [#64457](https://github.com/saltstack/salt/issues/64457) + * Added support for dnf5 and its new command syntax [#64532](https://github.com/saltstack/salt/issues/64532) + * Adding a new decorator to indicate when a module is deprecated in favor of a Salt extension. [#64569](https://github.com/saltstack/salt/issues/64569) + * Add jq-esque to_entries and from_entries functions [#64600](https://github.com/saltstack/salt/issues/64600) + * Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. [#64660](https://github.com/saltstack/salt/issues/64660) + * Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False [#64665](https://github.com/saltstack/salt/issues/64665) + * Strenghten Salt's HA capabilities with master clustering. [#64939](https://github.com/saltstack/salt/issues/64939) + * Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems [#64978](https://github.com/saltstack/salt/issues/64978) + * Add support for show_jid to salt-run + + Adds support for show_jid master config option to salt*run, so its behaviour matches the salt cli command. [#65008](https://github.com/saltstack/salt/issues/65008) + * Add ability to remove packages by wildcard via apt execution module [#65220](https://github.com/saltstack/salt/issues/65220) + * Added support for master top modules on masterless minions [#65479](https://github.com/saltstack/salt/issues/65479) + * Allowed accessing the regular mine from the SSH wrapper [#65645](https://github.com/saltstack/salt/issues/65645) + * Allow enabling backup for Linode in Salt Cloud [#65697](https://github.com/saltstack/salt/issues/65697) + * Add a backup schedule setter fFunction for Linode VMs [#65713](https://github.com/saltstack/salt/issues/65713) + * Add acme support for manual plugin hooks [#65744](https://github.com/saltstack/salt/issues/65744) + + # Security + + * Upgrade to `tornado>=6.3.3` due to https://github.com/advisories/GHSA-qppv-j76h-2rpx [#64989](https://github.com/saltstack/salt/issues/64989) + * Update to `gitpython>=3.1.35` due to https://github.com/advisories/GHSA-wfm5-v35h-vwf4 and https://github.com/advisories/GHSA-cwvm-v4w8-q58c [#65137](https://github.com/saltstack/salt/issues/65137) + + + -- Salt Project Packaging Sun, 03 Mar 2024 06:51:04 +0000 + salt (3006.7) stable; urgency=medium diff --git a/pkg/rpm/salt.spec b/pkg/rpm/salt.spec index 289c204ab24..04cf63b5c57 100644 --- a/pkg/rpm/salt.spec +++ b/pkg/rpm/salt.spec @@ -31,7 +31,7 @@ %define fish_dir %{_datadir}/fish/vendor_functions.d Name: salt -Version: 3007.0~rc1 +Version: 3007.0 Release: 0 Summary: A parallel remote execution system Group: System Environment/Daemons @@ -646,6 +646,180 @@ if [ $1 -ge 1 ] ; then fi %changelog +* Sun Mar 03 2024 Salt Project Packaging - 3007.0 + +# Removed + +- Removed RHEL 5 support since long since end-of-lifed [#62520](https://github.com/saltstack/salt/issues/62520) +- Removing Azure-Cloud modules from the code base. [#64322](https://github.com/saltstack/salt/issues/64322) +- Dropped Python 3.7 support since it's EOL in 27 Jun 2023 [#64417](https://github.com/saltstack/salt/issues/64417) +- Remove salt.payload.Serial [#64459](https://github.com/saltstack/salt/issues/64459) +- Remove netmiko_conn and pyeapi_conn from salt.modules.napalm_mod [#64460](https://github.com/saltstack/salt/issues/64460) +- Removed 'transport' arg from salt.utils.event.get_event [#64461](https://github.com/saltstack/salt/issues/64461) +- Removed the usage of retired Linode API v3 from Salt Cloud [#64517](https://github.com/saltstack/salt/issues/64517) + +# Deprecated + +- Deprecate all Proxmox cloud modules [#64224](https://github.com/saltstack/salt/issues/64224) +- Deprecate all the Vault modules in favor of the Vault Salt Extension https://github.com/salt-extensions/saltext-vault. The Vault modules will be removed in Salt core in 3009.0. [#64893](https://github.com/saltstack/salt/issues/64893) +- Deprecate all the Docker modules in favor of the Docker Salt Extension https://github.com/saltstack/saltext-docker. The Docker modules will be removed in Salt core in 3009.0. [#64894](https://github.com/saltstack/salt/issues/64894) +- Deprecate all the Zabbix modules in favor of the Zabbix Salt Extension https://github.com/salt-extensions/saltext-zabbix. The Zabbix modules will be removed in Salt core in 3009.0. [#64896](https://github.com/saltstack/salt/issues/64896) +- Deprecate all the Apache modules in favor of the Apache Salt Extension https://github.com/salt-extensions/saltext-apache. The Apache modules will be removed in Salt core in 3009.0. [#64909](https://github.com/saltstack/salt/issues/64909) +- Deprecation warning for Salt's backport of ``OrderedDict`` class which will be removed in 3009 [#65542](https://github.com/saltstack/salt/issues/65542) +- Deprecate Kubernetes modules for move to saltext-kubernetes in version 3009 [#65565](https://github.com/saltstack/salt/issues/65565) +- Deprecated all Pushover modules in favor of the Salt Extension at https://github.com/salt-extensions/saltext-pushover. The Pushover modules will be removed from Salt core in 3009.0 [#65567](https://github.com/saltstack/salt/issues/65567) +- Removed deprecated code: + + * All of ``salt/log/`` which has been on a deprecation path for a long time. + * Some of the logging handlers found in ``salt/_logging/handlers`` have been removed since the standard library provides + them. + * Removed the deprecated ``salt/modules/cassandra_mod.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/cassandra_return.py`` module and any tests for it. + * Removed the deprecated ``salt/returners/django_return.py`` module and any tests for it. [#65986](https://github.com/saltstack/salt/issues/65986) + +# Changed + +- Masquerade property will not default to false turning off masquerade if not specified. [#53120](https://github.com/saltstack/salt/issues/53120) +- Addressed Python 3.11 deprecations: + + * Switch to `FullArgSpec` since Py 3.11 no longer has `ArgSpec`, deprecated since Py 3.0 + * Stopped using the deprecated `cgi` module. + * Stopped using the deprecated `pipes` module + * Stopped using the deprecated `imp` module [#64457](https://github.com/saltstack/salt/issues/64457) +- changed 'gpg_decrypt_must_succeed' default from False to True [#64462](https://github.com/saltstack/salt/issues/64462) + +# Fixed + +- When an NFS or FUSE mount fails to unmount when mount options have changed, try again with a lazy umount before mounting again. [#18907](https://github.com/saltstack/salt/issues/18907) +- fix autoaccept gpg keys by supporting it in refresh_db module [#42039](https://github.com/saltstack/salt/issues/42039) +- Made cmd.script work with files from the fileserver via salt-ssh [#48067](https://github.com/saltstack/salt/issues/48067) +- Made slsutil.renderer work with salt-ssh [#50196](https://github.com/saltstack/salt/issues/50196) +- Fixed defaults.merge is not available when using salt-ssh [#51605](https://github.com/saltstack/salt/issues/51605) +- Fix extfs.mkfs missing parameter handling for -C, -d, and -e [#51858](https://github.com/saltstack/salt/issues/51858) +- Fixed Salt master does not renew token [#51986](https://github.com/saltstack/salt/issues/51986) +- Fixed salt-ssh continues state/pillar rendering with incorrect data when an exception is raised by a module on the target [#52452](https://github.com/saltstack/salt/issues/52452) +- Fix extfs.tune has 'reserved' documented twice and is missing the 'reserved_percentage' keyword argument [#54426](https://github.com/saltstack/salt/issues/54426) +- Fix the ability of the 'selinux.port_policy_present' state to modify. [#55687](https://github.com/saltstack/salt/issues/55687) +- Fixed config.get does not support merge option with salt-ssh [#56441](https://github.com/saltstack/salt/issues/56441) +- Removed an unused assignment in file.patch [#57204](https://github.com/saltstack/salt/issues/57204) +- Fixed vault module fetching more than one secret in one run with single-use tokens [#57561](https://github.com/saltstack/salt/issues/57561) +- Use brew path from which in mac_brew_pkg module and rely on _homebrew_bin() everytime [#57946](https://github.com/saltstack/salt/issues/57946) +- Fixed Vault verify option to work on minions when only specified in master config [#58174](https://github.com/saltstack/salt/issues/58174) +- Fixed vault command errors configured locally [#58580](https://github.com/saltstack/salt/issues/58580) +- Fixed issue with basic auth causing invalid header error and 401 Bad Request, by using HTTPBasicAuthHandler instead of header. [#58936](https://github.com/saltstack/salt/issues/58936) +- Make the LXD module work with pyLXD > 2.10 [#59514](https://github.com/saltstack/salt/issues/59514) +- Return error if patch file passed to state file.patch is malformed. [#59806](https://github.com/saltstack/salt/issues/59806) +- Handle failure and error information from tuned module/state [#60500](https://github.com/saltstack/salt/issues/60500) +- Fixed sdb.get_or_set_hash with Vault single-use tokens [#60779](https://github.com/saltstack/salt/issues/60779) +- Fixed state.test does not work with salt-ssh [#61100](https://github.com/saltstack/salt/issues/61100) +- Made slsutil.findup work with salt-ssh [#61143](https://github.com/saltstack/salt/issues/61143) +- Allow all primitive grain types for autosign_grains [#61416](https://github.com/saltstack/salt/issues/61416), [#63708](https://github.com/saltstack/salt/issues/63708) +- `ipset.new_set` no longer fails when creating a set type that uses the `family` create option [#61620](https://github.com/saltstack/salt/issues/61620) +- Fixed Vault session storage to allow unlimited use tokens [#62380](https://github.com/saltstack/salt/issues/62380) +- fix the efi grain on FreeBSD [#63052](https://github.com/saltstack/salt/issues/63052) +- Fixed gpg.receive_keys returns success on failed import [#63144](https://github.com/saltstack/salt/issues/63144) +- Fixed GPG state module always reports success without changes [#63153](https://github.com/saltstack/salt/issues/63153) +- Fixed GPG state module does not respect test mode [#63156](https://github.com/saltstack/salt/issues/63156) +- Fixed gpg.absent with gnupghome/user, fixed gpg.delete_key with gnupghome [#63159](https://github.com/saltstack/salt/issues/63159) +- Fixed service module does not handle enable/disable if systemd service is an alias [#63214](https://github.com/saltstack/salt/issues/63214) +- Made x509_v2 compound match detection use new runner instead of peer publishing [#63278](https://github.com/saltstack/salt/issues/63278) +- Need to make sure we update __pillar__ during a pillar refresh to ensure that process_beacons has the updated beacons loaded from pillar. [#63583](https://github.com/saltstack/salt/issues/63583) +- This implements the vpc_uuid parameter when creating a droplet. This parameter selects the correct virtual private cloud (private network interface). [#63714](https://github.com/saltstack/salt/issues/63714) +- pkg.installed no longer reports failure when installing packages that are installed via the task manager [#63767](https://github.com/saltstack/salt/issues/63767) +- mac_xattr.list and mac_xattr.read will replace undecode-able bytes to avoid raising CommandExecutionError. [#63779](https://github.com/saltstack/salt/issues/63779) [#63779](https://github.com/saltstack/salt/issues/63779) +- Fix aptpkg.latest_version performance, reducing number of times to 'shell out' [#63982](https://github.com/saltstack/salt/issues/63982) +- Added option to use a fresh connection for mysql cache [#63991](https://github.com/saltstack/salt/issues/63991) +- [lxd] Fixed a bug in `container_create` which prevented devices which are not of type `disk` to be correctly created and added to the container when passed via the `devices` parameter. [#63996](https://github.com/saltstack/salt/issues/63996) +- Skipped the `isfile` check to greatly increase speed of reading minion keys for systems with a large number of minions on slow file storage [#64260](https://github.com/saltstack/salt/issues/64260) +- Fix utf8 handling in 'pass' renderer [#64300](https://github.com/saltstack/salt/issues/64300) +- Upgade tornado to 6.3.2 [#64305](https://github.com/saltstack/salt/issues/64305) +- Prevent errors due missing 'transactional_update.apply' on SLE Micro and MicroOS. [#64369](https://github.com/saltstack/salt/issues/64369) +- Fix 'unable to unmount' failure to return False result instead of None [#64420](https://github.com/saltstack/salt/issues/64420) +- Fixed issue uninstalling duplicate packages in ``win_appx`` execution module [#64450](https://github.com/saltstack/salt/issues/64450) +- Clean up tech debt, IPC now uses tcp transport. [#64488](https://github.com/saltstack/salt/issues/64488) +- Made salt-ssh more strict when handling unexpected situations and state.* wrappers treat a remote exception as failure, excluded salt-ssh error returns from mine [#64531](https://github.com/saltstack/salt/issues/64531) +- Fix flaky test for LazyLoader with isolated mocking of threading.RLock [#64567](https://github.com/saltstack/salt/issues/64567) +- Fix possible `KeyError` exceptions in `salt.utils.user.get_group_dict` + while reading improper duplicated GID assigned for the user. [#64599](https://github.com/saltstack/salt/issues/64599) +- changed vm_config() to deep-merge vm_overrides of specific VM, instead of simple-merging the whole vm_overrides [#64610](https://github.com/saltstack/salt/issues/64610) +- Fix the way Salt tries to get the Homebrew's prefix + + The first attempt to get the Homebrew's prefix is to look for + the `HOMEBREW_PREFIX` environment variable. If it's not set, then + Salt tries to get the prefix from the `brew` command. However, the + `brew` command can fail. So a last attempt is made to get the + prefix by guessing the installation path. [#64924](https://github.com/saltstack/salt/issues/64924) +- Add missing MySQL Grant SERVICE_CONNECTION_ADMIN to mysql module. [#64934](https://github.com/saltstack/salt/issues/64934) +- Fixed slsutil.update with salt-ssh during template rendering [#65067](https://github.com/saltstack/salt/issues/65067) +- Keep track when an included file only includes sls files but is a requisite. [#65080](https://github.com/saltstack/salt/issues/65080) +- Fixed `gpg.present` succeeds when the keyserver is unreachable [#65169](https://github.com/saltstack/salt/issues/65169) +- Fix typo in nftables module to ensure unique nft family values [#65295](https://github.com/saltstack/salt/issues/65295) +- Dereference symlinks to set proper __cli opt [#65435](https://github.com/saltstack/salt/issues/65435) +- Made salt-ssh merge master top returns for the same environment [#65480](https://github.com/saltstack/salt/issues/65480) +- Account for situation where the metadata grain fails because the AWS environment requires an authentication token to query the metadata URL. [#65513](https://github.com/saltstack/salt/issues/65513) +- Improve the condition of overriding target for pip with VENV_PIP_TARGET environment variable. [#65562](https://github.com/saltstack/salt/issues/65562) +- Added SSH wrapper for logmod [#65630](https://github.com/saltstack/salt/issues/65630) +- Include changes in the results when schedule.present state is run with test=True. [#65652](https://github.com/saltstack/salt/issues/65652) +- Fix extfs.tune doesn't pass retcode to module.run [#65686](https://github.com/saltstack/salt/issues/65686) +- Return an error message when the DNS plugin is not supported [#65739](https://github.com/saltstack/salt/issues/65739) +- Execution modules have access to regular fileclient durring pillar rendering. [#66124](https://github.com/saltstack/salt/issues/66124) +- Fixed a issue with server channel where a minion's public key + would be rejected if it contained a final newline character. [#66126](https://github.com/saltstack/salt/issues/66126) + +# Added + +- Allowed publishing to regular minions from the SSH wrapper [#40943](https://github.com/saltstack/salt/issues/40943) +- Added syncing of custom salt-ssh wrappers [#45450](https://github.com/saltstack/salt/issues/45450) +- Made salt-ssh sync custom utils [#53666](https://github.com/saltstack/salt/issues/53666) +- Add ability to use file.managed style check_cmd in file.serialize [#53982](https://github.com/saltstack/salt/issues/53982) +- Revised use of deprecated net-tools and added support for ip neighbour with IPv4 ip_neighs, IPv6 ip_neighs6 [#57541](https://github.com/saltstack/salt/issues/57541) +- Added password support to Redis returner. [#58044](https://github.com/saltstack/salt/issues/58044) +- Added a state (win_task) for managing scheduled tasks on Windows [#59037](https://github.com/saltstack/salt/issues/59037) +- Added keyring param to gpg modules [#59783](https://github.com/saltstack/salt/issues/59783) +- Added new grain to detect the Salt package type: onedir, pip or system [#62589](https://github.com/saltstack/salt/issues/62589) +- Added Vault AppRole and identity issuance to minions [#62823](https://github.com/saltstack/salt/issues/62823) +- Added Vault AppRole auth mount path configuration option [#62825](https://github.com/saltstack/salt/issues/62825) +- Added distribution of Vault authentication details via response wrapping [#62828](https://github.com/saltstack/salt/issues/62828) +- Add salt package type information. Either onedir, pip or system. [#62961](https://github.com/saltstack/salt/issues/62961) +- Added signature verification to file.managed/archive.extracted [#63143](https://github.com/saltstack/salt/issues/63143) +- Added signed_by_any/signed_by_all parameters to gpg.verify [#63166](https://github.com/saltstack/salt/issues/63166) +- Added match runner [#63278](https://github.com/saltstack/salt/issues/63278) +- Added Vault token lifecycle management [#63406](https://github.com/saltstack/salt/issues/63406) +- adding new call for openscap xccdf eval supporting new parameters [#63416](https://github.com/saltstack/salt/issues/63416) +- Added Vault lease management utility [#63440](https://github.com/saltstack/salt/issues/63440) +- implement removal of ptf packages in zypper pkg module [#63442](https://github.com/saltstack/salt/issues/63442) +- add JUnit output for saltcheck [#63463](https://github.com/saltstack/salt/issues/63463) +- Add ability for file.keyvalue to create a file if it doesn't exist [#63545](https://github.com/saltstack/salt/issues/63545) +- added cleanup of temporary mountpoint dir for macpackage installed state [#63905](https://github.com/saltstack/salt/issues/63905) +- Add pkg.installed show installable version in test mode [#63985](https://github.com/saltstack/salt/issues/63985) +- Added patch option to Vault SDB driver [#64096](https://github.com/saltstack/salt/issues/64096) +- Added flags to create local users and groups [#64256](https://github.com/saltstack/salt/issues/64256) +- Added inline specification of trusted CA root certificate for Vault [#64379](https://github.com/saltstack/salt/issues/64379) +- Add ability to return False result in test mode of configurable_test_state [#64418](https://github.com/saltstack/salt/issues/64418) +- Switched Salt's onedir Python version to 3.11 [#64457](https://github.com/saltstack/salt/issues/64457) +- Added support for dnf5 and its new command syntax [#64532](https://github.com/saltstack/salt/issues/64532) +- Adding a new decorator to indicate when a module is deprecated in favor of a Salt extension. [#64569](https://github.com/saltstack/salt/issues/64569) +- Add jq-esque to_entries and from_entries functions [#64600](https://github.com/saltstack/salt/issues/64600) +- Added ability to use PYTHONWARNINGS=ignore to silence deprecation warnings. [#64660](https://github.com/saltstack/salt/issues/64660) +- Add follow_symlinks to file.symlink exec module to switch to os.path.lexists when False [#64665](https://github.com/saltstack/salt/issues/64665) +- Strenghten Salt's HA capabilities with master clustering. [#64939](https://github.com/saltstack/salt/issues/64939) +- Added win_appx state and execution modules for managing Microsoft Store apps and deprovisioning them from systems [#64978](https://github.com/saltstack/salt/issues/64978) +- Add support for show_jid to salt-run + + Adds support for show_jid master config option to salt-run, so its behaviour matches the salt cli command. [#65008](https://github.com/saltstack/salt/issues/65008) +- Add ability to remove packages by wildcard via apt execution module [#65220](https://github.com/saltstack/salt/issues/65220) +- Added support for master top modules on masterless minions [#65479](https://github.com/saltstack/salt/issues/65479) +- Allowed accessing the regular mine from the SSH wrapper [#65645](https://github.com/saltstack/salt/issues/65645) +- Allow enabling backup for Linode in Salt Cloud [#65697](https://github.com/saltstack/salt/issues/65697) +- Add a backup schedule setter fFunction for Linode VMs [#65713](https://github.com/saltstack/salt/issues/65713) +- Add acme support for manual plugin hooks [#65744](https://github.com/saltstack/salt/issues/65744) + +# Security + +- Upgrade to `tornado>=6.3.3` due to https://github.com/advisories/GHSA-qppv-j76h-2rpx [#64989](https://github.com/saltstack/salt/issues/64989) +- Update to `gitpython>=3.1.35` due to https://github.com/advisories/GHSA-wfm5-v35h-vwf4 and https://github.com/advisories/GHSA-cwvm-v4w8-q58c [#65137](https://github.com/saltstack/salt/issues/65137) + + * Tue Feb 20 2024 Salt Project Packaging - 3006.7 # Deprecated