# salt.modules.cp

Minion side functions for salt-cp

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

  Added 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.

    Added 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`.

    Added 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.

    Added 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.

    Added 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.

    Added 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.

  >   Added 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.

  >   Added 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.

  >   Added 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.

    Added 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

salt.modules.cp.list_master_symlinks(saltenv=None, prefix='')

  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

    Added 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.

  Added 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