neulab/tldr huggingface dataset:
keep_symlinks Keep symlinks when copying from the source. This option will cause the copy operation to terminate at the symlink. If desire behavior similar to rsync, then set this to True.
force_symlinks Force symlink creation. This option will force the symlink creation.  If a file or directory is obstructing symlink creation it will be recursively removed so that symlink creation can proceed. This option is usually not needed except in special circumstances.
win_owner The owner of the symlink and directories if makedirs is True. If this is not passed, user will be used. If user is not passed, the account under which Salt is running will be used.
New in version 2017.7.7.
win_perms A dictionary containing permissions to grant
win_deny_perms A dictionary containing permissions to deny
win_inheritance True to inherit permissions from parent, otherwise False
salt.states.file.rename(name, source, force=False, makedirs=False, **kwargs) If the source file exists on the system, rename it to the named file. The named file will not be overwritten if it already exists unless the force option is set to True.
name   The location of the file to rename to
source The location of the file to move to the location specified with name
salt.states.file.replace(name, pattern, repl, count=0, flags=8, bufsize=1, append_if_not_found=False, prepend_if_not_found=False, not_found_content=None, backup='.bak', show_changes=True, ignore_if_missing=False, backslash_literal=False) Maintain an edit in a file.
name   Filesystem path to the file to be edited. If a symlink is specified, it will be resolved to its target.
pattern A regular expression, to be matched using Python's re.search().
NOTE: If you need to match a literal string that contains regex special characters, you may want to use salt's custom Jinja filter, regex_escape.
{{ 'http://example.com?foo=bar%20baz' | regex_escape }}
count  Maximum number of pattern occurrences to be replaced. Defaults to 0.  If count is a positive integer n, no more than n occurrences will be replaced, otherwise all occurrences will be replaced.
flags  A list of flags defined in the re module documentation from the Python standard library. Each list item should be a string that will correlate to the human-friendly flag name. E.g., ['IGNORECASE', 'MULTILINE'].  Optionally, flags may be an int, with a value corresponding to the XOR (|) of all the desired flags. Defaults to 8 (which equates to ['MULTILINE']).
NOTE: file.replace reads the entire file as a string to support multiline regex patterns. Therefore, when using anchors such as ^ or $ in the pattern, those anchors may be relative to the line OR relative to the file. The default for file.replace is to treat anchors as relative to the line, which is implemented by setting the default value of flags to ['MULTILINE'].  When overriding the default value for flags, if 'MULTILINE' is not present then anchors will be relative to the file. If the desired behavior is for anchors to be relative to the line, then simply add 'MULTILINE' to the list of flags.
bufsize How much of the file to buffer into memory at once. The default value 1 processes one line at a time. The special value file may be specified which will read the entire file into memory before processing.
append_if_not_found If set to True, and pattern is not found, then the content will be appended to the file.
prepend_if_not_found If set to True and pattern is not found, then the content will be prepended to the file.
backup The file extension to use for a backup of the file before editing. Set to False to skip making a backup.
show_changes Output a unified diff of the old file and the new file. If False return a boolean if any changes were made. Returns a boolean or a string.
ignore_if_missing New in version 2016.3.4.
Controls what to do if the file is missing. If set to False, the state will display an error raised by the execution module. If set to True, the state will simply report no changes.
backslash_literal New in version 2016.11.7.
For complex regex patterns, it can be useful to avoid the need for complex quoting and escape sequences by making use of YAML's multiline string syntax.
complex_search_and_replace: file.replace: # <...snip...> - pattern: | CentOS \(2.6.32[^\\n]+\\n\s+root[^\\n]+\\n\)+
NOTE: When using YAML multiline string syntax in pattern:, make sure to also use that syntax in the repl: part, or you might loose line feeds.
When regex capture groups are used in pattern:, their captured value is available for reuse in the repl: part as a backreference (ex. \1).
add_login_group_to_winbind_ssh_access_list: file.replace: - name: '/etc/security/pam_winbind.conf' - pattern: '^(require_membership_of = )(.*)$' - repl: '\1\2,append-new-group-to-line'
NOTE: The file.replace state uses Python's re module.  For more advanced options, see https://docs.python.org/2/library/re.html
salt.states.file.retention_schedule(name, retain, strptime_format=None, timezone=None) Apply retention scheduling to backup storage directory.
• name -- The filesystem path to the directory containing backups to be managed.
• retain --
Delete the backups, except for the ones we want to keep. The N below should be an integer but may also be the special value of all, which keeps all files matching the criteria.  All of the retain options default to None, which means to not keep files based on this criteria.
most_recent N Keep the most recent N files.
first_of_hour N For the last N hours from now, keep the first file after the hour.
first_of_day N For the last N days from now, keep the first file after midnight.  See also timezone.
first_of_week N For the last N weeks from now, keep the first file after Sunday midnight.
first_of_month N For the last N months from now, keep the first file after the start of the month.
first_of_year N For the last N years from now, keep the first file after the start of the year.
• strptime_format -- A python strptime format string used to first match the filenames of backups and then parse the filename to determine the datetime of the file. https://docs.python.org/2/library/datetime.html#datetime.datetime.strptime Defaults to None, which considers all files in the directory to be backups eligible for deletion and uses os.path.getmtime() to determine the datetime.
• timezone -- The timezone to use when determining midnight.  This is only used when datetime is pulled from os.path.getmtime().  Defaults to None which uses the timezone from the locale.
/var/backups/example_directory: file.retention_schedule: - retain: most_recent: 5 first_of_hour: 4 first_of_day: 7 first_of_week: 6    # NotImplemented yet. first_of_month: 6 first_of_year: all - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2 - timezone: None
salt.states.file.serialize(name, dataset=None, dataset_pillar=None, user=None, group=None, mode=None, backup='', makedirs=False, show_changes=True, create=True, merge_if_exists=False, encoding=None, encoding_errors='strict', serializer=None, serializer_opts=None, deserializer_opts=None, **kwargs) Serializes dataset and store it into managed file. Useful for sharing simple configuration files.
name   The location of the file to create
dataset The dataset that will be serialized
dataset_pillar Operates like dataset, but draws from a value stored in pillar, using the pillar path syntax used in pillar.get. This is useful when the pillar value contains newlines, as referencing a pillar variable using a jinja/mako template can result in YAML formatting issues due to the newlines causing indentation mismatches.
serializer (or formatter) Write the data as this format. See the list of all-salt.serializers for supported output formats.
Changed in version 3002: serializer argument added as an alternative to formatter.  Both are accepted, but using both will result in an error.
user   The user to own the directory, this defaults to the user salt is running as on the minion
group  The group ownership set for the directory, this defaults to the group salt is running as on the minion
backup Overrides the default backup mode for this specific file.
makedirs Create parent directories for destination file.
create Default is True, if create is set to False then the file will only be managed if the file already exists on the system.
merge_if_exists Default is False, if merge_if_exists is True then the existing file will be parsed and the dataset passed in will be merged with the existing content
serializer_opts Pass through options to serializer. For example:
/etc/dummy/package.yaml file.serialize: - serializer: yaml - serializer_opts: - explicit_start: True - default_flow_style: True - indent: 4
The valid opts are the additional opts (i.e. not the data being serialized) for the function used to serialize the data. Documentation for the these functions can be found in the list below:
• For yaml: yaml.dump()
• For json: json.dumps()
• For python: pprint.pformat()
• For msgpack: Run python -c 'import msgpack; help(msgpack.Packer)' to see the available options (encoding, unicode_errors, etc.)
deserializer_opts Like serializer_opts above, but only used when merging with an existing file (i.e. when merge_if_exists is set to True).
The options specified here will be passed to the deserializer to load the existing data, before merging with the specified data and re-serializing.
/etc/dummy/package.yaml file.serialize: - serializer: yaml - serializer_opts: - explicit_start: True - default_flow_style: True - indent: 4 - deserializer_opts: - encoding: latin-1 - merge_if_exists: True
The valid opts are the additional opts (i.e. not the data being deserialized) for the function used to deserialize the data.  Documentation for the these functions can be found in the list below:
• For yaml: yaml.load()
• For json: json.loads()
However, note that not all arguments are supported. For example, when deserializing JSON, arguments like parse_float and parse_int which accept a callable object cannot be handled in an SLS file.
For example, this state:
/etc/dummy/package.json: file.serialize: - dataset: name: naive description: A package using naive versioning author: A confused individual <iam@confused.com> dependencies: express: '>= 1.2.0' optimist: '>= 0.1.0' engine: node 0.4.1 - serializer: json
will manage the file /etc/dummy/package.json:
{ "author": "A confused individual <iam@confused.com>", "dependencies": { "express": ">= 1.2.0", "optimist": ">= 0.1.0" }, "description": "A package using naive versioning", "engine": "node 0.4.1", "name": "naive" }
salt.states.file.shortcut(name, target, arguments=None, working_dir=None, description=None, icon_location=None, force=False, backupname=None, makedirs=False, user=None, **kwargs) Create a Windows shortcut
If the file already exists and is a shortcut pointing to any location other than the specified target, the shortcut will be replaced. If it is a regular file or directory then the state will return False. If the regular file or directory is desired to be replaced with a shortcut pass force: True, if it is to be renamed, pass a backupname.
name   The location of the shortcut to create. Must end with either ".lnk" or ".url"
target The location that the shortcut points to
arguments Any arguments to pass in the shortcut
working_dir Working directory in which to execute target
description Description to set on shortcut
icon_location Location of shortcut's icon
force  If the name of the shortcut exists and is not a file and force is set to False, the state will fail. If force is set to True, the link or directory in the way of the shortcut file will be deleted to make room for the shortcut, unless backupname is set, when it will be renamed
backupname If the name of the shortcut exists and is not a file, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first.
makedirs If the location of the shortcut does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory. Setting this to True will also create the parent for backupname if necessary.
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, **kwargs) Create a symbolic link (symlink, soft link)
If the file already exists and is a symlink pointing to any location other than the specified target, the symlink will be replaced. If an entry with the same name exists then the state will return False. If the existing entry is desired to be replaced with a symlink pass force: True, if it is to be renamed, pass a backupname.
name   The location of the symlink to create
target The location that the symlink points to
force  If the name of the symlink exists and is not a symlink and force is set to False, the state will fail. If force is set to True, the existing entry in the way of the symlink file will be deleted to make room for the symlink, unless backupname is set, when it will be renamed
Changed in version 3000: Force will now remove all types of existing file system entries, not just files, directories and symlinks.
backupname If the name of the symlink exists and is not a symlink, it will be renamed to the backupname. If the backupname already exists and force is False, the state will fail. Otherwise, the backupname will be removed first.  An absolute path OR a basename file/directory name must be provided.  The latter will be placed relative to the symlink destination's parent directory.
makedirs If the location of the symlink does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory
mode   The permissions to set on this file, aka 644, 0775, 4664. Not supported on Windows.
salt.states.file.tidied(name, age=0, matches=None, rmdirs=False, size=0, **kwargs) Remove unwanted files based on specific criteria. Multiple criteria are OR’d together, so a file that is too large but is not old enough will still get tidied.
If neither age nor size is given all files which match a pattern in matches will be removed.
name   The directory tree that should be tidied
age    Maximum age in days after which files are considered for removal
matches List of regular expressions to restrict what gets removed. Default: ['.*']
rmdirs Whether or not it's allowed to remove directories
size   Maximum allowed file size. Files greater or equal to this size are removed. Doesn't apply to directories or symbolic links
cleanup: file.tidied: - name: /tmp/salt_test - rmdirs: True - matches: - foo - b.*r
salt.states.file.touch(name, atime=None, mtime=None, makedirs=False) Replicate the 'nix "touch" command to create a new empty file or update the atime and mtime of an existing file.
Note that if you just want to create a file and don't care about atime or mtime, you should use file.managed instead, as it is more feature-complete.  (Just leave out the source/template/contents arguments, and it will just create the file and/or check its permissions, without messing with contents)
atime  atime of the file
mtime  mtime of the file
makedirs whether we should create the parent directory/directories in order to touch the file
/var/log/httpd/logrotate.empty: file.touch
salt.states.file.uncomment(name, regex, char='#', backup='.bak') Uncomment specified commented lines in a file
regex  A regular expression used to find the lines that are to be uncommented.  This regex should not include the comment character. A leading ^ character will be stripped for convenience (for easily switching between comment() and uncomment()).  The regex will be searched for from the beginning of the line, ignoring leading spaces (we prepend '^[ t]*')
char   The character to remove in order to uncomment a line
backup The file will be backed up before edit with this file extension;
/etc/adduser.conf: file.uncomment: - regex: EXTRA_GROUPS
salt.states.firewall State to check firewall configurations
salt.states.firewall.check(name, port=None, **kwargs) Checks if there is an open connection from the minion to the defined host on a specific port.
name   host name or ip address to test connection to
port   The port to test the connection on
Additional parameters, parameters allowed are: proto (tcp or udp) family (ipv4 or ipv6) timeout
testgoogle: firewall.check: - name: 'google.com' - port: 80 - proto: 'tcp'
salt.states.firewalld Management of firewalld
The following example applies changes to the public zone, blocks echo-reply and echo-request packets, does not set the zone to be the default, enables masquerading, and allows ports 22/tcp and 25/tcp.  It will be applied permanently and directly before restart/reload.
public: firewalld.present: - name: public - block_icmp: - echo-reply - echo-request - default: False - masquerade: True - ports: - 22/tcp - 25/tcp
The following example applies changes to the public zone, enables masquerading and configures port forwarding TCP traffic from port 22 to 2222, and forwards TCP traffic from port 80 to 443 at 192.168.0.1.
my_zone: firewalld.present: - name: public - masquerade: True - port_fwd: - 22:2222:tcp - 80:443:tcp:192.168.0.1
The following example binds the public zone to interface eth0 and to all packets coming from the 192.168.1.0/24 subnet. It also removes the zone from all other interfaces or sources.
public: firewalld.present: - name: public - interfaces: - eth0 - sources: - 192.168.1.0/24
Here, we define a new service that encompasses TCP ports 4505 4506:
saltmaster: firewalld.service: - name: saltmaster - ports: - 4505/tcp - 4506/tcp
To make this new service available in a zone, the following can be used, which would allow access to the salt master from the 10.0.0.0/8 subnet:
saltzone: firewalld.present: - name: saltzone - services: - saltmaster - sources: - 10.0.0.0/8
Another way of implementing the same rule above using rich rules is demonstrated here:
saltzone: firewalld.present: - name: saltzone - rich_rules: - rule service name="saltmaster" accept - sources: - 10.0.0.0/8
The format of rich rules is the same as:
firewall-cmd --list-rich-rules
with an example output of:
rule protocol value="icmp" accept rule protocol value="ipv6-icmp" accept rule service name="snmp" accept
class salt.states.firewalld.ForwardingMapping(srcport, destport, protocol, destaddr) Represents a port forwarding statement mapping a local port to a remote port for a specific protocol (TCP or UDP)
todict() Returns a pretty dictionary meant for command line output.
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) Ensure a zone has specific attributes.
name   The zone to modify.
default None Set this zone as the default zone if True.
masquerade False Enable or disable masquerade for a zone.
block_icmp None List of ICMP types to block in the zone.
prune_block_icmp False If True, remove all but the specified block_icmp from the zone.
ports  None List of ports to add to the zone.
prune_ports False If True, remove all but the specified ports from the zone.
port_fwd None List of port forwards to add to the zone.
prune_port_fwd False If True, remove all but the specified port_fwd from the zone.
services None List of services to add to the zone.
prune_services False If True, remove all but the specified services from the zone.  .. note:: Currently defaults to True for compatibility, but will be changed to False in a future release.
interfaces None List of interfaces to add to the zone.
prune_interfaces False If True, remove all but the specified interfaces from the zone.
sources None List of sources to add to the zone.
prune_sources False If True, remove all but the specified sources from the zone.
rich_rules None List of rich rules to add to the zone.
prune_rich_rules False If True, remove all but the specified rich rules from the zone.
salt.states.firewalld.service(name, ports=None, protocols=None) Ensure the service exists and encompasses the specified ports and protocols.
salt.states.gem Installation of Ruby modules packaged as gems A state module to manage rubygems. Gems can be set up to be installed or removed. This module will use RVM or rbenv if they are installed. In that case, you can specify what ruby version and gemset to target.
addressable: gem.installed: - user: rvm - ruby: jruby@jgemset
salt.states.gem.installed(name, ruby=None, gem_bin=None, user=None, version=None, rdoc=False, ri=False, pre_releases=False, proxy=None, source=None) Make sure that a gem is installed.
name   The name of the gem to install
ruby: None Only for RVM or rbenv installations: the ruby version and gemset to target.
gem_bin: None Custom gem command to run instead of the default.  Use this to install gems to a non-default ruby install. If you are using rvm or rbenv use the ruby argument instead.
user: None The user under which to run the gem command
version None Specify the version to install for the gem.  Doesn't play nice with multiple gems at once
rdoc   False Generate RDoc documentation for the gem(s).
ri     False Generate RI documentation for the gem(s).
pre_releases False Install pre-release version of gem(s) if available.
proxy  None Use the specified HTTP proxy server for all outgoing traffic.  Format: http://hostname[:port]
salt.states.gem.removed(name, ruby=None, user=None, gem_bin=None) Make sure that a gem is not installed.
name   The name of the gem to uninstall
salt.states.gem.sources_add(name, ruby=None, user=None) Make sure that a gem source is added.
name   The URL of the gem source to be added
ruby: None For RVM or rbenv installations: the ruby version and gemset to target.
salt.states.gem.sources_remove(name, ruby=None, user=None) Make sure that a gem source is removed.
name   The URL of the gem source to be removed
salt.states.git States to manage git repositories and git configuration
IMPORTANT: Before using git over ssh, make sure your remote host fingerprint exists in your ~/.ssh/known_hosts file.
Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or newer.
salt.states.git.cloned(name, target, branch=None, user=None, password=None, identity=None, https_user=None, https_pass=None, output_encoding=None) New in version 2018.3.3,2019.2.0.
Ensure that a repository has been cloned to the specified target directory.  If not, clone that repository. No fetches will be performed once cloned.
name   Address of the remote repository
target Name of the target directory where repository should be cloned
branch Remote branch to check out. If unspecified, the default branch (i.e.  the one to the remote HEAD points) will be checked out.
NOTE: The local branch name will match the remote branch name. If the branch name is changed, then that branch will be checked out locally, but keep in mind that remote repository will not be fetched. If your use case requires that you keep the clone up to date with the remote repository, then consider using git.latest.
user   User under which to run git commands. By default, commands are run by the user under which the minion is running.
identity Path to a private key to use for ssh URLs. Works the same way as in git.latest, see that state's documentation for more information.
https_user HTTP Basic Auth username for HTTPS (only) clones
https_pass HTTP Basic Auth password for HTTPS (only) clones
salt.states.git.config_set(name, value=None, multivar=None, repo=None, user=None, password=None, output_encoding=None, **kwargs) New in version 2014.7.0.
Changed in version 2015.8.0: Renamed from git.config to git.config_set. For earlier versions, use git.config.
Ensure that a config value is set to the desired value(s)
name   Name of the git config value to set
value  Set a single value for the config item
multivar Set multiple values for the config item
NOTE: The order matters here, if the same parameters are set but in a different order, they will be removed and replaced in the order specified.
repo   Location of the git repository for which the config value should be set. Required unless global is set to True.
user   User under which to run git commands. By default, the commands are run by the user under which the minion is running.
global False If True, this will set a global git config option
Local Config Example:
# Single value mylocalrepo: git.config_set: - name: user.email - value: foo@bar.net - repo: /path/to/repo
# Multiple values mylocalrepo: git.config_set: - name: mysection.myattribute - multivar: - foo - bar - baz - repo: /path/to/repo
Global Config Example (User ``foo``):
mylocalrepo: git.config_set: - name: user.name - value: Foo Bar - user: foo - global: True
salt.states.git.config_unset(name, value_regex=None, repo=None, user=None, password=None, output_encoding=None, **kwargs) New in version 2015.8.0.
Ensure that the named config key is not present
name   The name of the configuration key to unset. This value can be a regex, but the regex must match the entire key name. For example, foo\.  would not match all keys in the foo section, it would be necessary to use foo\..+ to do so.
value_regex Regex indicating the values to unset for the matching key(s)
NOTE: This option behaves differently depending on whether or not all is set to True. If it is, then all values matching the regex will be deleted (this is the only way to delete multiple values from a multivar). If all is set to False, then this state will fail if the regex matches more than one value in a multivar.
all    False If True, unset all matches
# Value matching 'baz' mylocalrepo: git.config_unset: - name: foo.bar - value_regex: 'baz' - repo: /path/to/repo
# Ensure entire multivar is unset mylocalrepo: git.config_unset: - name: foo.bar - all: True
# Ensure all variables in 'foo' section are unset, including multivars mylocalrepo: git.config_unset: - name: 'foo\..+' - all: True
# Ensure that global config value is unset mylocalrepo: git.config_unset: - name: foo.bar - global: True
salt.states.git.detached(name, rev, target, remote='origin', user=None, password=None, force_clone=False, force_checkout=False, fetch_remote=True, hard_reset=False, submodules=False, identity=None, https_user=None, https_pass=None, output_encoding=None, **kwargs) New in version 2016.3.0.
Make sure a repository is cloned to the given target directory and is a detached HEAD checkout of the commit ID resolved from rev.
name   Address of the remote repository.
rev    The branch, tag, or commit ID to checkout after clone.  If a branch or tag is specified it will be resolved to a commit ID and checked out.
target Name of the target directory where repository is about to be cloned.
remote origin Git remote to use. If this state needs to clone the repo, it will clone it using this value as the initial remote name. If the repository already exists, and a remote by this name is not present, one will be added.
force_clone False If the target directory exists and is not a git repository, then this state will fail. Set this argument to True to remove the contents of the target directory and clone the repo into it.
force_checkout False When checking out the revision ID, the state will fail if there are unwritten changes. Set this argument to True to discard unwritten changes when checking out.
fetch_remote True If False a fetch will not be performed and only local refs will be reachable.
hard_reset False If True a hard reset will be performed before the checkout and any uncommitted modifications to the working directory will be discarded.  Untracked files will remain in place.
NOTE: Changes resulting from a hard reset will not trigger requisites.
submodules False Update submodules
identity A path on the minion (or a SaltStack fileserver URL, e.g. salt://path/to/identity_file) to a private key to use for SSH authentication.
salt.states.git.latest(name, target, rev='HEAD', branch=None, user=None, password=None, update_head=True, force_checkout=False, force_clone=False, force_fetch=False, force_reset=False, submodules=False, bare=False, mirror=False, remote='origin', fetch_tags=True, sync_tags=True, depth=None, identity=None, https_user=None, https_pass=None, refspec_branch='*', refspec_tag='*', output_encoding=None, **kwargs) Make sure the repository is cloned to the given directory and is up-to-date.
name   Address of the remote repository, as passed to git clone
NOTE: From the Git documentation, there are two URL formats supported for SSH authentication. The below two examples are equivalent:
# ssh:// URL ssh://user@server/project.git
# SCP-like syntax user@server:project.git
A common mistake is to use an ssh:// URL, but with a colon after the domain instead of a slash. This is invalid syntax in Git, and will therefore not work in Salt. When in doubt, confirm that a git clone works for the URL before using it in Salt.
It has been reported by some users that SCP-like syntax is incompatible with git repos hosted on Atlassian Stash/BitBucket Server. In these cases, it may be necessary to use ssh:// URLs for SSH authentication.
rev    HEAD The remote branch, tag, or revision ID to checkout after clone / before update. If specified, then Salt will also ensure that the tracking branch is set to <remote>/<rev>, unless rev refers to a tag or SHA1, in which case Salt will ensure that the tracking branch is unset.
If rev is not specified, it will be assumed to be HEAD, and Salt will not manage the tracking branch at all.
Changed in version 2015.8.0: If not specified, rev now defaults to the remote repository's HEAD.
target Name of the target directory where repository is about to be cloned
branch Name of the local branch into which to checkout the specified rev. If not specified, then Salt will not care what branch is being used locally and will just use whatever branch is currently there.
NOTE: If this argument is not specified, this means that Salt will not change the local branch if the repository is reset to another branch/tag/SHA1. For example, assume that the following state was run initially:
foo_app: git.latest: - name: https://mydomain.tld/apps/foo.git - target: /var/www/foo - user: www
This would have cloned the HEAD of that repo (since a rev wasn't specified), and because branch is not specified, the branch in the local clone at /var/www/foo would be whatever the default branch is on the remote repository (usually master, but not always). Now, assume that it becomes necessary to switch this checkout to the dev branch. This would require rev to be set, and probably would also require force_reset to be enabled:
foo_app: git.latest: - name: https://mydomain.tld/apps/foo.git - target: /var/www/foo - user: www - rev: dev - force_reset: True
The result of this state would be to perform a hard-reset to origin/dev. Since branch was not specified though, while /var/www/foo would reflect the contents of the remote repo's dev branch, the local branch would still remain whatever it was when it was cloned. To make the local branch match the remote one, set branch as well, like so:
foo_app: git.latest: - name: https://mydomain.tld/apps/foo.git - target: /var/www/foo - user: www - rev: dev - branch: dev - force_reset: True
This may seem redundant, but Salt tries to support a wide variety of use cases, and doing it this way allows for the use case where the local branch doesn't need to be strictly managed.
user   Local system user under which to run git commands. By default, commands are run by the user under which the minion is running.
NOTE: This is not to be confused with the username for http(s)/SSH authentication.
update_head True If set to False, then the remote repository will be fetched (if necessary) to ensure that the commit to which rev points exists in the local checkout, but no changes will be made to the local HEAD.
force_checkout False When checking out the local branch, the state will fail if there are unwritten changes. Set this argument to True to discard unwritten changes when checking out.
force_fetch False If a fetch needs to be performed, non-fast-forward fetches will cause this state to fail. Set this argument to True to force the fetch even if it is a non-fast-forward update.
force_reset False If the update is not a fast-forward, this state will fail. Set this argument to True to force a hard-reset to the remote revision in these cases.
Changed in version 2019.2.0: This option can now be set to remote-changes, which will instruct Salt not to discard local changes if the repo is up-to-date with the remote repository.
submodules False Update submodules on clone or branch change
bare   False Set to True if the repository is to be a bare clone of the remote repository.
mirror Set to True if the repository is to be a mirror of the remote repository. This implies that bare set to True, and thus is incompatible with rev.
fetch_tags True If True, then when a fetch is performed all tags will be fetched, even those which are not reachable by any branch on the remote.
sync_tags True If True, then Salt will delete tags which exist in the local clone but are not found on the remote repository.
depth  Defines depth in history when git a clone is needed in order to ensure latest. E.g. depth: 1 is useful when deploying from a repository with a long history. Use rev to specify branch or tag. This is not compatible with revision IDs.
Changed in version 2019.2.0: This option now supports tags as well as branches, on Git 1.8.0 and newer.
identity Path to a private key to use for ssh URLs. This can be either a single string, or a list of strings. For example:
# Single key git@github.com:user/repo.git: git.latest: - user: deployer - identity: /home/deployer/.ssh/id_rsa
# Two keys git@github.com:user/repo.git: git.latest: - user: deployer - identity: - /home/deployer/.ssh/id_rsa - /home/deployer/.ssh/id_rsa_alternate
If multiple keys are specified, they will be tried one-by-one in order for each git command which needs to authenticate.
Changed in version 2016.3.0: Key can now be specified as a SaltStack fileserver URL (e.g. salt://path/to/identity_file).
refspec_branch * A glob expression defining which branches to retrieve when fetching.  See git-fetch(1) for more information on how refspecs work.
refspec_tag * A glob expression defining which tags to retrieve when fetching. See git-fetch(1) for more information on how refspecs work.
NOTE: Clashing ID declarations can be avoided when including different branches from the same git repository in the same SLS file by using the name argument. The example below checks out the gh-pages and gh-pages-prod branches from the same repository into separate directories. The example also sets up the ssh_known_hosts ssh key required to perform the git checkout.
Also, it has been reported that the SCP-like syntax for
gitlab.example.com: ssh_known_hosts: - present - user: root - enc: ecdsa - fingerprint: 4e:94:b0:54:c1:5b:29:a2:70:0e:e1:a3:51:ee:ee:e3
git-website-staging: git.latest: - name: git@gitlab.example.com:user/website.git - rev: gh-pages - target: /usr/share/nginx/staging - identity: /root/.ssh/website_id_rsa - require: - pkg: git - ssh_known_hosts: gitlab.example.com
git-website-staging: git.latest: - name: git@gitlab.example.com:user/website.git - rev: gh-pages - target: /usr/share/nginx/staging - identity: salt://website/id_rsa - require: - pkg: git - ssh_known_hosts: gitlab.example.com
git-website-prod: git.latest: - name: git@gitlab.example.com:user/website.git - rev: gh-pages-prod - target: /usr/share/nginx/prod - identity: /root/.ssh/website_id_rsa - require: - pkg: git - ssh_known_hosts: gitlab.example.com
salt.states.git.present(name, force=False, bare=True, template=None, separate_git_dir=None, shared=None, user=None, password=None, output_encoding=None) Ensure that a repository exists in the given directory
WARNING: If the minion has Git 2.5 or later installed, name points to a worktree, and force is set to True, then the worktree will be deleted. This has been corrected in Salt 2015.8.0.
name   Path to the directory
Changed in version 2015.8.0: This path must now be absolute
force  False If True, and if name points to an existing directory which does not contain a git repository, then the contents of that directory will be recursively removed and a new repository will be initialized in its place.
bare   True If True, and a repository must be initialized, then the repository will be a bare repository.
NOTE: This differs from the default behavior of git.init, make sure to set this value to False if a bare repo is not desired.
template If a new repository is initialized, this argument will specify an alternate template directory.
separate_git_dir If a new repository is initialized, this argument will specify an alternate $GIT_DIR
salt.states.github Github User State Module
This state is used to ensure presence of users in the Organization.
ensure user test is present in github: github.present: - name: 'Example TestUser1' - email: example@domain.com - username: 'gitexample'
salt.states.github.absent(name, profile='github', **kwargs) Ensure a github user is absent
ensure user test is absent in github: github.absent: - name: 'Example TestUser1' - email: example@domain.com - username: 'gitexample'
name   Github handle of the user in organization
salt.states.github.present(name, profile='github', **kwargs) Ensure a user is present
ensure user test is present in github: github.present: - name: 'gitexample'
name   This is the github handle of the user in the organization
salt.states.github.repo_absent(name, profile='github', **kwargs) Ensure a repo is absent.
ensure repo test is absent in github: github.repo_absent: - name: 'test'
name   This is the name of the repository in the organization.
salt.states.github.repo_present(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=False, gitignore_template=None, license_template=None, teams=None, profile='github', **kwargs) Ensure a repository is present
name   This is the name of the repository.
teams  The teams for which this repo should belong to, specified as a dict of team name to permission ('pull', 'push' or 'admin').
Ensure repo my-repo is present in github: github.repo_present: - name: 'my-repo' - description: 'My very important repository'
salt.states.github.team_absent(name, profile='github', **kwargs) Ensure a team is absent.
ensure team test is present in github: github.team_absent: - name: 'test'
name   This is the name of the team in the organization.
salt.states.github.team_present(name, description=None, repo_names=None, privacy='secret', permission='pull', members=None, enforce_mfa=False, no_mfa_grace_seconds=0, profile='github', **kwargs) Ensure a team is present
privacy The level of privacy for the team, can be 'secret' or 'closed'. Defaults to secret.
permission The default permission for new repositories added to the team, can be 'pull', 'push' or 'admin'. Defaults to pull.
members The members belonging to the team, specified as a dict of member name to optional configuration. Options include 'enforce_mfa_from' and 'mfa_exempt'.
enforce_mfa Whether to enforce MFA requirements on members of the team. If True then all members without mfa_exempt: True configured will be removed from the team. Note that no_mfa_grace_seconds may be set to allow members a grace period.
no_mfa_grace_seconds The number of seconds of grace time that a member will have to enable MFA before being removed from the team. The grace period will begin from enforce_mfa_from on the member configuration, which defaults to 1970/01/01.
Ensure team test is present in github: github.team_present: - name: 'test' - members: user1: {} user2: {}
Ensure team test_mfa is present in github: github.team_present: - name: 'test_mfa' - members: user1: enforce_mfa_from: 2016/06/15 - enforce_mfa: True
salt.states.glance_image Management of OpenStack Glance Images New in version 2018.3.0.
depends shade
configuration see salt.modules.glanceng for setup instructions
Example States
create image: glance_image.present: - name: cirros - filename: cirros.raw - image_format: raw
delete image: glance_image.absent: - name: cirros
salt.states.glance_image.absent(name, auth=None) Ensure image does not exist
name   Name of the image
salt.states.glance_image.present(name, auth=None, **kwargs) Ensure image exists and is up-to-date
enabled Boolean to control if image is enabled
description An arbitrary description of the image
salt.states.glassfish Manage Glassfish/Payara server .. versionadded:: 2016.11.0
Management of glassfish using its RESTful API You can setup connection parameters like this
- server: - ssl: true - url: localhost - port: 4848 - user: admin - password: changeit
salt.states.glassfish.connection_factory_absent(name, both=True, server=None) Ensures the transaction factory is absent.
name   Name of the connection factory
both   Delete both the pool and the resource, defaults to true
salt.states.glassfish.connection_factory_present(name, restype='connection_factory', description='', enabled=True, min_size=1, max_size=250, resize_quantity=2, idle_timeout=300, wait_timeout=60, reconnect_on_failure=False, transaction_support='', connection_validation=False, server=None) Ensures that the Connection Factory is present
restype Type of the connection factory, can be either connection_factory, queue_connection_factory` or ``topic_connection_factory, defaults to connection_factory
description Description of the connection factory
enabled Is the connection factory enabled? defaults to true
min_size Minimum and initial number of connections in the pool, defaults to 1
max_size Maximum number of connections that can be created in the pool, defaults to 250
resize_quantity Number of connections to be removed when idle_timeout expires, defaults to 2
idle_timeout Maximum time a connection can remain idle in the pool, in seconds, defaults to 300
wait_timeout Maximum time a caller can wait before timeout, in seconds, defaults to 60
reconnect_on_failure Close all connections and reconnect on failure (or reconnect only when used), defaults to false
transaction_support Level of transaction support, can be either XATransaction, LocalTransaction or NoTransaction
connection_validation Connection validation is required, defaults to false
salt.states.glassfish.destination_absent(name, server=None) Ensures that the JMS Destination doesn't exists
name   Name of the JMS Destination
salt.states.glassfish.destination_present(name, physical, restype='queue', description='', enabled=True, server=None) Ensures that the JMS Destination Resource (queue or topic) is present
name   The JMS Queue/Topic name
physical The Physical destination name
restype The JMS Destination resource type, either queue or topic, defaults is queue
description A description of the resource
enabled Defaults to True
salt.states.glassfish.jdbc_datasource_absent(name, both=True, server=None) Ensures the JDBC Datasource doesn't exists
name   Name of the datasource
salt.states.glassfish.jdbc_datasource_present(name, description='', enabled=True, restype='datasource', vendor='mysql', sql_url='', sql_user='', sql_password='', min_size=8, max_size=32, resize_quantity=2, idle_timeout=300, wait_timeout=60, non_transactional=False, transaction_isolation='', isolation_guaranteed=True, server=None) Ensures that the JDBC Datasource exists
description Description of the datasource
enabled Is the datasource enabled? defaults to true
restype Resource type, can be datasource, xa_datasource, connection_pool_datasource or driver, defaults to datasource
vendor SQL Server type, currently supports mysql, postgresql and mssql, defaults to mysql
sql_url URL of the server in jdbc form
sql_user Username for the server
sql_password Password for that username
min_size Minimum and initial number of connections in the pool, defaults to 8
max_size Maximum number of connections that can be created in the pool, defaults to 32
non_transactional Return non-transactional connections
transaction_isolation Defaults to the JDBC driver default
isolation_guaranteed All connections use the same isolation level
salt.states.glassfish.system_properties_absent(name, server=None) Ensures that the system property doesn't exists
name   Name of the system property
salt.states.glassfish.system_properties_present(server=None, **kwargs) Ensures that the system properties are present
properties The system properties
salt.states.glusterfs Manage GlusterFS pool.
salt.states.glusterfs.add_volume_bricks(name, bricks) Add brick(s) to an existing volume
myvolume: glusterfs.add_volume_bricks: - bricks: - host1:/srv/gluster/drive1 - host2:/srv/gluster/drive2
Replicated Volume: glusterfs.add_volume_bricks: - name: volume2 - bricks: - host1:/srv/gluster/drive2 - host2:/srv/gluster/drive3
salt.states.glusterfs.max_op_version(name) New in version 2019.2.0.
Add brick(s) to an existing volume
myvolume: glusterfs.max_op_version: - name: volume1 - version: 30707
salt.states.glusterfs.op_version(name, version) New in version 2019.2.0.
version Version to which the cluster.op-version should be set
myvolume: glusterfs.op_version: - name: volume1 - version: 30707
salt.states.glusterfs.peered(name) Check if node is peered.
name   The remote host with which to peer.
peer-cluster: glusterfs.peered: - name: two
peer-clusters: glusterfs.peered: - names: - one - two - three - four
salt.states.glusterfs.started(name) Check if volume has been started
name   name of the volume
mycluster: glusterfs.started: []
salt.states.glusterfs.volume_present(name, bricks, stripe=False, replica=False, device_vg=False, transport='tcp', start=False, force=False, arbiter=False) Ensure that the volume exists
bricks list of brick paths
replica replica count for volume
arbiter use every third brick as arbiter (metadata only)
start  ensure that the volume is also started
myvolume: glusterfs.volume_present: - bricks: - host1:/srv/gluster/drive1 - host2:/srv/gluster/drive2
Replicated Volume: glusterfs.volume_present: - name: volume2 - bricks: - host1:/srv/gluster/drive2 - host2:/srv/gluster/drive3 - replica: 2 - start: True
Replicated Volume with arbiter brick: glusterfs.volume_present: - name: volume3 - bricks: - host1:/srv/gluster/drive2 - host2:/srv/gluster/drive3 - host3:/srv/gluster/drive4 - replica: 3 - arbiter: True - start: True
salt.states.gnomedesktop Configuration of the GNOME desktop Control the GNOME settings
localdesktop_wm_prefs: gnomedesktop.wm_preferences: - user: username - audible_bell: false - action_double_click_titlebar: 'toggle-maximize' - visual_bell: true - num_workspaces: 6 localdesktop_lockdown: gnomedesktop.desktop_lockdown: - user: username - disable_user_switching: true localdesktop_interface: gnomedesktop.desktop_interface: - user: username - clock_show_date: true - clock_format: 12h
salt.states.gnomedesktop.desktop_interface(name, user=None, automatic_mnemonics=None, buttons_have_icons=None, can_change_accels=None, clock_format=None, clock_show_date=None, clock_show_seconds=None, cursor_blink=None, cursor_blink_time=None, cursor_blink_timeout=None, cursor_size=None, cursor_theme=None, document_font_name=None, enable_animations=None, font_name=None, gtk_color_palette=None, gtk_color_scheme=None, gtk_im_module=None, gtk_im_preedit_style=None, gtk_im_status_style=None, gtk_key_theme=None, gtk_theme=None, gtk_timeout_initial=None, gtk_timeout_repeat=None, icon_theme=None, menubar_accel=None, menubar_detachable=None, menus_have_icons=None, menus_have_tearoff=None, monospace_font_name=None, show_input_method_menu=None, show_unicode_menu=None, text_scaling_factor=None, toolbar_detachable=None, toolbar_icons_size=None, toolbar_style=None, toolkit_accessibility=None, **kwargs) desktop_interface: sets values in the org.gnome.desktop.interface schema
salt.states.gnomedesktop.desktop_lockdown(name, user=None, disable_application_handlers=None, disable_command_line=None, disable_lock_screen=None, disable_log_out=None, disable_print_setup=None, disable_printing=None, disable_save_to_disk=None, disable_user_switching=None, user_administration_disabled=None, **kwargs) desktop_lockdown: sets values in the org.gnome.desktop.lockdown schema