salt.modules.cp#

Minion side functions for salt-cp

salt.modules.cp.cache_dest(url, saltenv=None)#

New in version 3000.

Changed in version 3005: saltenv will use value from config if not explicitly set

Returns the expected cache path for the file, if cached using cp.cache_file.

Note

This only returns the _expected_ path, it does not tell you if the URL is really cached. To check if the URL is cached, use cp.is_cached instead.

CLI Examples:

salt '*' cp.cache_dest https://foo.com/bar.rpm
salt '*' cp.cache_dest salt://my/file
salt '*' cp.cache_dest salt://my/file saltenv=dev
salt.modules.cp.cache_dir(path, saltenv=None, include_empty=False, include_pat=None, exclude_pat=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Download and cache everything under a directory from the master

include_patNone

Glob or regex to narrow down the files cached from the given path. If matching with a regex, the regex must be prefixed with E@, otherwise the expression will be interpreted as a glob.

New in version 2014.7.0.

exclude_patNone

Glob or regex to exclude certain files from being cached from the given path. If matching with a regex, the regex must be prefixed with E@, otherwise the expression will be interpreted as a glob.

Note

If used with include_pat, files matching this pattern will be excluded from the subset of files defined by include_pat.

New in version 2014.7.0.

CLI Examples:

salt '*' cp.cache_dir salt://path/to/dir
salt '*' cp.cache_dir salt://path/to/dir include_pat='E@*.py$'
salt.modules.cp.cache_file(path, saltenv=None, source_hash=None, verify_ssl=True, use_etag=False)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Used to cache a single file on the Minion

Returns the location of the new cached file on the Minion

source_hash

If name is an http(s) or ftp URL and the file exists in the minion's file cache, this option can be passed to keep the minion from re-downloading the file if the cached copy matches the specified hash.

New in version 2018.3.0.

verify_ssl

If False, remote https file sources (https://) and source_hash will not attempt to validate the servers certificate. Default is True.

New in version 3002.

use_etag

If True, 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 source_hash parameter.

New in version 3005.

CLI Example:

salt '*' cp.cache_file salt://path/to/file

There are two ways of defining the fileserver environment (a.k.a. saltenv) from which to cache the file. One is to use the saltenv parameter, and the other is to use a querystring syntax in the salt:// URL. The below two examples are equivalent:

salt '*' cp.cache_file salt://foo/bar.conf saltenv=config
salt '*' cp.cache_file salt://foo/bar.conf?saltenv=config

If the path being cached is a salt:// URI, and the path does not exist, then False will be returned.

Note

It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command.

salt.modules.cp.cache_file_ssh(path, saltenv=None, source_hash=None, verify_ssl=True, use_etag=False)#

This function is an alias of cache_file.

Changed in version 3005: saltenv will use value from config if not explicitly set

Used to cache a single file on the Minion

Returns the location of the new cached file on the Minion

source_hash

If name is an http(s) or ftp URL and the file exists in the minion's file cache, this option can be passed to keep the minion from re-downloading the file if the cached copy matches the specified hash.

New in version 2018.3.0.

verify_ssl

If False, remote https file sources (https://) and source_hash will not attempt to validate the servers certificate. Default is True.

New in version 3002.

use_etag

If True, 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 source_hash parameter.

New in version 3005.

CLI Example:

salt '*' cp.cache_file salt://path/to/file

There are two ways of defining the fileserver environment (a.k.a. saltenv) from which to cache the file. One is to use the saltenv parameter, and the other is to use a querystring syntax in the salt:// URL. The below two examples are equivalent:

salt '*' cp.cache_file salt://foo/bar.conf saltenv=config
salt '*' cp.cache_file salt://foo/bar.conf?saltenv=config

If the path being cached is a salt:// URI, and the path does not exist, then False will be returned.

Note

It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command.

salt.modules.cp.cache_files(paths, saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Used to gather many files from the Master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the Master

CLI Example:

salt '*' cp.cache_files salt://pathto/file1,salt://pathto/file1

There are two ways of defining the fileserver environment (a.k.a. saltenv) from which to cache the files. One is to use the saltenv parameter, and the other is to use a querystring syntax in the salt:// URL. The below two examples are equivalent:

salt '*' cp.cache_files salt://foo/bar.conf,salt://foo/baz.conf saltenv=config
salt '*' cp.cache_files salt://foo/bar.conf?saltenv=config,salt://foo/baz.conf?saltenv=config

The querystring method is less useful when all files are being cached from the same environment, but is a good way of caching files from multiple different environments in the same command. For example, the below command will cache the first file from the config1 environment, and the second one from the config2 environment.

salt '*' cp.cache_files salt://foo/bar.conf?saltenv=config1,salt://foo/bar.conf?saltenv=config2

Note

It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command.

salt.modules.cp.cache_local_file(path)#

Cache a local file on the minion in the localfiles cache

CLI Example:

salt '*' cp.cache_local_file /etc/hosts
salt.modules.cp.cache_master(saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Retrieve all of the files on the master and cache them locally

CLI Example:

salt '*' cp.cache_master
salt.modules.cp.envs()#

List available environments for fileserver

CLI Example:

salt '*' cp.envs
salt.modules.cp.get_dir(path, dest, saltenv=None, template=None, gzip=None, **kwargs)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Used to recursively copy a directory from the salt master

CLI Example:

salt '*' cp.get_dir salt://path/to/dir/ /minion/dest

get_dir supports the same template and gzip arguments as get_file.

salt.modules.cp.get_file(path, dest, saltenv=None, makedirs=False, template=None, gzip=None, **kwargs)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Changed in version 2018.3.0: dest can now be a directory

Used to get a single file from the salt master

CLI Example:

salt '*' cp.get_file salt://path/to/file /minion/dest

Template rendering can be enabled on both the source and destination file names like so:

salt '*' cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja

This example would instruct all Salt minions to download the vimrc from a directory with the same name as their os grain and copy it to /etc/vimrc

For larger files, the cp.get_file module also supports gzip compression. Because gzip is CPU-intensive, this should only be used in scenarios where the compression ratio is very high (e.g. pretty-printed JSON or YAML files).

Use the gzip named argument to enable it. Valid values are 1..9, where 1 is the lightest compression and 9 the heaviest. 1 uses the least CPU on the master (and minion), 9 uses the most.

There are two ways of defining the fileserver environment (a.k.a. saltenv) from which to retrieve the file. One is to use the saltenv parameter, and the other is to use a querystring syntax in the salt:// URL. The below two examples are equivalent:

salt '*' cp.get_file salt://foo/bar.conf /etc/foo/bar.conf saltenv=config
salt '*' cp.get_file salt://foo/bar.conf?saltenv=config /etc/foo/bar.conf

Note

It may be necessary to quote the URL when using the querystring method, depending on the shell being used to run the command.

salt.modules.cp.get_file_str(path, saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Download a file from a URL to the Minion cache directory and return the contents of that file

Returns False if Salt was unable to cache a file from a URL.

CLI Example:

salt '*' cp.get_file_str salt://my/file
salt.modules.cp.get_template(path, dest, template='jinja', saltenv=None, makedirs=False, **kwargs)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Render a file as a template before setting it down. Warning, order is not the same as in fileclient.cp for non breaking old API.

CLI Example:

salt '*' cp.get_template salt://path/to/template /minion/dest
salt.modules.cp.get_url(path, dest='', saltenv=None, makedirs=False, source_hash=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Changed in version 2018.3.0: dest can now be a directory

Used to get a single file from a URL.

path

A URL to download a file from. Supported URL schemes are: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). If no scheme was specified, this is equivalent of using file://. If a file:// URL is given, the function just returns absolute path to that file on a local filesystem. The function returns False if Salt was unable to fetch a file from a salt:// URL.

dest

The default behaviour is to write the fetched file to the given destination path. If this parameter is omitted or set as empty string (''), the function places the remote file on the local filesystem inside the Minion cache directory and returns the path to that file.

Note

To simply return the file contents instead, set destination to None. This works with salt://, http://, https:// and file:// URLs. The files fetched by http:// and https:// will not be cached.

saltenv

Salt fileserver environment from which to retrieve the file. Ignored if path is not a salt:// URL.

source_hash

If path is an http(s) or ftp URL and the file exists in the minion's file cache, this option can be passed to keep the minion from re-downloading the file if the cached copy matches the specified hash.

New in version 2018.3.0.

CLI Example:

salt '*' cp.get_url salt://my/file /tmp/this_file_is_mine
salt '*' cp.get_url http://www.slashdot.org /tmp/index.html
salt.modules.cp.hash_file(path, saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file.

CLI Example:

salt '*' cp.hash_file salt://path/to/file
salt.modules.cp.hash_file_ssh(path, saltenv=None)#

This function is an alias of hash_file.

Changed in version 3005: saltenv will use value from config if not explicitly set

Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file.

CLI Example:

salt '*' cp.hash_file salt://path/to/file
salt.modules.cp.is_cached(path, saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Returns the full path to a file if it is cached locally on the minion otherwise returns a blank string

CLI Example:

salt '*' cp.is_cached salt://path/to/file
salt.modules.cp.list_master(saltenv=None, prefix='')#

Changed in version 3005: saltenv will use value from config if not explicitly set

List all of the files stored on the master

CLI Example:

salt '*' cp.list_master
salt.modules.cp.list_master_dirs(saltenv=None, prefix='')#

Changed in version 3005: saltenv will use value from config if not explicitly set

List all of the directories stored on the master

CLI Example:

salt '*' cp.list_master_dirs

Changed in version 3005: saltenv will use value from config if not explicitly set

List all of the symlinks stored on the master

CLI Example:

salt '*' cp.list_master_symlinks
salt.modules.cp.list_minion(saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

List all of the files cached on the minion

CLI Example:

salt '*' cp.list_minion
salt.modules.cp.list_states(saltenv=None)#

Changed in version 3005: saltenv will use value from config if not explicitly set

List all of the available state files in an environment

CLI Example:

salt '*' cp.list_states
salt.modules.cp.push(path, keep_symlinks=False, upload_path=None, remove_source=False)#

WARNING Files pushed to the master will have global read permissions..

Push a file from the minion up to the master, the file will be saved to the salt master in the master's minion files cachedir (defaults to /var/cache/salt/master/minions/minion-id/files)

Since this feature allows a minion to push a file up to the master server it is disabled by default for security purposes. To enable, set file_recv to True in the master configuration file, and restart the master.

keep_symlinks

Keep the path value without resolving its canonical form

upload_path

Provide a different path inside the master's minion files cachedir

remove_source

Remove the source file on the minion

New in version 2016.3.0.

CLI Example:

salt '*' cp.push /etc/fstab
salt '*' cp.push /etc/system-release keep_symlinks=True
salt '*' cp.push /etc/fstab upload_path='/new/path/fstab'
salt '*' cp.push /tmp/filename remove_source=True
salt.modules.cp.push_dir(path, glob=None, upload_path=None)#

Push a directory from the minion up to the master, the files will be saved to the salt master in the master's minion files cachedir (defaults to /var/cache/salt/master/minions/minion-id/files). It also has a glob for matching specific files using globbing.

New in version 2014.7.0.

Since this feature allows a minion to push files up to the master server it is disabled by default for security purposes. To enable, set file_recv to True in the master configuration file, and restart the master.

upload_path

Provide a different path and directory name inside the master's minion files cachedir

CLI Example:

salt '*' cp.push /usr/lib/mysql
salt '*' cp.push /usr/lib/mysql upload_path='/newmysql/path'
salt '*' cp.push_dir /etc/modprobe.d/ glob='*.conf'
salt.modules.cp.recv(files, dest)#

Used with salt-cp, pass the files dict, and the destination.

This function receives small fast copy files from the master via salt-cp. It does not work via the CLI.

CLI Example:

salt '*' cp.recv
salt.modules.cp.recv_chunked(dest, chunk, append=False, compressed=True, mode=None)#

This function receives files copied to the minion using salt-cp and is not intended to be used directly on the CLI.

CLI Example:

salt '*' cp.recv_chunked
salt.modules.cp.stat_file(path, saltenv=None, octal=True)#

Changed in version 3005: saltenv will use value from config if not explicitly set

Return the permissions of a file, to get the permissions of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file.

CLI Example:

salt '*' cp.stat_file salt://path/to/file