salt.modules.cp
Minion side functions for salt-cp
-
New in version 3000.
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_dest(url, saltenv='base')
-
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 byinclude_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_dir(path, saltenv='base', include_empty=False, include_pat=None, exclude_pat=None)
-
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.
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 thesaltenv
parameter, and the other is to use a querystring syntax in thesalt://
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, thenFalse
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(path, saltenv='base', source_hash=None, verify_ssl=True)
-
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 thesaltenv
parameter, and the other is to use a querystring syntax in thesalt://
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 theconfig2
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_files(paths, saltenv='base')
-
Cache a local file on the minion in the localfiles cache
CLI Example:
salt '*' cp.cache_local_file /etc/hosts
salt.modules.cp.cache_local_file(path)
-
Retrieve all of the files on the master and cache them locally
CLI Example:
salt '*' cp.cache_master
salt.modules.cp.cache_master(saltenv='base')
-
List available environments for fileserver
CLI Example
salt '*' cp.envs
salt.modules.cp.envs()
-
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_dir(path, dest, saltenv='base', template=None, gzip=None, **kwargs)
-
Changed in version 2018.3.0:
dest
can now be a directoryUsed 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 thesaltenv
parameter, and the other is to use a querystring syntax in thesalt://
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(path, dest, saltenv='base', makedirs=False, template=None, gzip=None, **kwargs)
-
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_file_str(path, saltenv='base')
-
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_template(path, dest, template='jinja', saltenv='base', makedirs=False, **kwargs)
-
Changed in version 2018.3.0:
dest
can now be a directoryUsed 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://
andfile://
(local filesystem). If no scheme was specified, this is equivalent of usingfile://
. If afile://
URL is given, the function just returns absolute path to that file on a local filesystem. The function returnsFalse
if Salt was unable to fetch a file from asalt://
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 withsalt://
,http://
,https://
andfile://
URLs. The files fetched byhttp://
andhttps://
will not be cached. - saltenvbase
-
Salt fileserver environment from which to retrieve the file. Ignored if
path
is not asalt://
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.get_url(path, dest='', saltenv='base', makedirs=False, source_hash=None)
-
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(path, saltenv='base')
-
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.is_cached(path, saltenv='base')
-
List all of the files stored on the master
CLI Example:
salt '*' cp.list_master
salt.modules.cp.list_master(saltenv='base', prefix='')
-
List all of the directories stored on the master
CLI Example:
salt '*' cp.list_master_dirs
salt.modules.cp.list_master_dirs(saltenv='base', prefix='')
-
List all of the symlinks stored on the master
CLI Example:
salt '*' cp.list_master_symlinks
salt.modules.cp.list_master_symlinks(saltenv='base', prefix='')
-
List all of the files cached on the minion
CLI Example:
salt '*' cp.list_minion
salt.modules.cp.list_minion(saltenv='base')
-
List all of the available state modules in an environment
CLI Example:
salt '*' cp.list_states
salt.modules.cp.list_states(saltenv='base')
-
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
toTrue
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(path, keep_symlinks=False, upload_path=None, remove_source=False)
-
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
toTrue
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.push_dir(path, glob=None, upload_path=None)
-
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.
salt.modules.cp.recv(files, dest)
-
This function receives files copied to the minion using
salt-cp
and is not intended to be used directly on the CLI.
salt.modules.cp.recv_chunked(dest, chunk, append=False, compressed=True, mode=None)
-
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
salt.modules.cp.stat_file(path, saltenv='base', octal=True)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.cp.html