# salt.modules.archive

A module to wrap (non-Windows) archive calls

Added in version 2014.1.0.

salt.modules.archive.cmd_unzip(zip_file, dest, excludes=None, options=None, template=None, runas=None, trim_output=False, password=None)

  Added in version 2015.5.0: In versions 2014.7.x and earlier, this function was known as `archive.unzip`.

  Uses the `unzip` command to unpack zip files. This command is part of the Info-ZIP suite of tools, and is typically packaged as simply `unzip`.

  zip_file

    Path of zip file to be unpacked

  dest

    The destination directory into which the file should be unpacked

  excludesNone

    Comma-separated list of files not to unpack. Can also be passed in a Python list.

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.cmd_unzip template=jinja /tmp/zipfile.zip '/tmp/{{grains.id}}' excludes=file_1,file_2

  options

    Optional when using `zip` archives, ignored when usign other archives files. This is mostly used to overwrite existing files with `o`. This options are only used when `unzip` binary is used.

    Added in version 2016.3.1.

  runasNone

    Unpack the zip file as the specified user. Defaults to the user under which the minion is running.

    Added in version 2015.5.0.

  trim_outputFalse

    The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100

  password

    Password to use with password protected zip files

    Note

    This is not considered secure. It is recommended to instead use `archive.unzip` for password-protected ZIP files. If a password is used here, then the unzip command run to extract the ZIP file will not show up in the minion log like most shell commands Salt runs do. However, the password will still be present in the events logged to the minion log at the `debug` log level. If the minion is logging at `debug` (or more verbose), then be advised that the password will appear in the log.

    Added in version 2016.11.0.

  CLI Example:

      salt '*' archive.cmd_unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2

salt.modules.archive.cmd_zip(zip_file, sources, template=None, cwd=None, runas=None)

  Added in version 2015.5.0: In versions 2014.7.x and earlier, this function was known as `archive.zip`.

  Uses the `zip` command to create zip files. This command is part of the Info-ZIP suite of tools, and is typically packaged as simply `zip`.

  zip_file

    Path of zip file to be created

  sources

    Comma-separated list of sources to include in the zip file. Sources can also be passed in a Python list.

    Changed in version 2017.7.0: Globbing is now supported for this argument

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.cmd_zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt

  cwdNone

    Use this argument along with relative paths in `sources` to create zip files which do not contain the leading directories. If not specified, the zip file will be created as if the cwd was `/`, and creating a zip file of `/foo/bar/baz.txt` will contain the parent directories `foo` and `bar`. To create a zip file containing just `baz.txt`, the following command would be used:

        salt '*' archive.cmd_zip /tmp/baz.zip baz.txt cwd=/foo/bar

    Added in version 2014.7.1.

  runasNone

    Create the zip file as the specified user. Defaults to the user under which the minion is running.

    Added in version 2015.5.0.

  CLI Example:

      salt '*' archive.cmd_zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
      # Globbing for sources (2017.7.0 and later)
      salt '*' archive.cmd_zip /tmp/zipfile.zip '/tmp/sourcefile*'

salt.modules.archive.gunzip(gzipfile, template=None, runas=None, options=None)

  Uses the gunzip command to unpack gzip files

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.gunzip template=jinja /tmp/{{grains.id}}.txt.gz

  runasNone

    The user with which to run the gzip command line

  optionsNone

    Pass any additional arguments to gzip

    Added in version 2016.3.4.

  CLI Example:

      # Create /tmp/sourcefile.txt
      salt '*' archive.gunzip /tmp/sourcefile.txt.gz
      salt '*' archive.gunzip /tmp/sourcefile.txt options='--verbose'

salt.modules.archive.gzip(sourcefile, template=None, runas=None, options=None)

  Uses the gzip command to create gzip files

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.gzip template=jinja /tmp/{{grains.id}}.txt

  runasNone

    The user with which to run the gzip command line

  optionsNone

    Pass any additional arguments to gzip

    Added in version 2016.3.4.

  CLI Example:

      # Create /tmp/sourcefile.txt.gz
      salt '*' archive.gzip /tmp/sourcefile.txt
      salt '*' archive.gzip /tmp/sourcefile.txt options='-9 --verbose'

salt.modules.archive.is_encrypted(name, clean=False, saltenv='base', source_hash=None, use_etag=False)

  Added in version 2016.11.0.

  Changed in version 3005.

  Returns `True` if the zip archive is password-protected, `False` if not. If the specified file is not a ZIP archive, an error will be raised.

  name

    The path / URL of the archive to check.

  cleanFalse

    Set this value to `True` to delete the path referred to by `name` once the contents have been listed. This option should be used with care.

    Note

    If there is an error listing the archive's contents, the cached file will not be removed, to allow for troubleshooting.

  saltenvbase

    Specifies the fileserver environment from which to retrieve `archive`. This is only applicable when `archive` is a file from the `salt://` fileserver.

  source_hash

    If `name` is an http(s)/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 archive if the cached copy matches the specified hash.

    Added in version 2018.3.0.

  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 Examples:

      salt '*' archive.is_encrypted /path/to/myfile.zip
      salt '*' archive.is_encrypted salt://foo.zip
      salt '*' archive.is_encrypted salt://foo.zip saltenv=dev
      salt '*' archive.is_encrypted https://domain.tld/myfile.zip clean=True
      salt '*' archive.is_encrypted https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
      salt '*' archive.is_encrypted ftp://10.1.2.3/foo.zip

salt.modules.archive.list_(name, archive_format=None, options=None, strip_components=None, clean=False, verbose=False, saltenv='base', source_hash=None, use_etag=False)

  Added in version 2016.11.0.

  Changed in version 2016.11.2,3005: The rarfile Python module is now supported for listing the contents of rar archives. This is necessary on minions with older releases of the `rar` CLI tool, which do not support listing the contents in a parsable format.

  List the files and directories in an tar, zip, or rar archive.

  Note

  This function will only provide results for XZ-compressed archives if the xz CLI command is available, as Python does not at this time natively support XZ compression in its tarfile module. Keep in mind however that most Linux distros ship with xz already installed.

  To check if a given minion has xz, the following Salt command can be run:

      salt minion_id cmd.which xz

  If `None` is returned, then xz is not present and must be installed. It is widely available and should be packaged as either `xz` or `xz-utils`.

  name

    Path/URL of archive

  archive_format

    Specify the format of the archive (`tar`, `zip`, or `rar`). If this argument is omitted, the archive format will be guessed based on the value of the `name` parameter.

  options

    For tar archives only. This function will, by default, try to use the tarfile module from the Python standard library to get a list of files/directories. If this method fails, then it will fall back to using the shell to decompress the archive to stdout and pipe the results to `tar -tf -` to produce a list of filenames. XZ-compressed archives are already supported automatically, but in the event that the tar archive uses a different sort of compression not supported natively by tarfile, this option can be used to specify a command that will decompress the archive to stdout. For example:

        salt minion_id archive.list /path/to/foo.tar.gz options='gzip --decompress --stdout'

    Note

    It is not necessary to manually specify options for gzip'ed archives, as gzip compression is natively supported by tarfile.

  strip_components

    This argument specifies a number of top-level directories to strip from the results. This is similar to the paths that would be extracted if `--strip-components` (or `--strip`) were used when extracting tar archives.

    Added in version 2016.11.2.

  cleanFalse

    Set this value to `True` to delete the path referred to by `name` once the contents have been listed. This option should be used with care.

    Note

    If there is an error listing the archive's contents, the cached file will not be removed, to allow for troubleshooting.

  verboseFalse

    If `False`, this function will return a list of files/dirs in the archive. If `True`, it will return a dictionary categorizing the paths into separate keys containing the directory names, file names, and also directories/files present in the top level of the archive.

    Changed in version 2016.11.2: This option now includes symlinks in their own list. Before, they were included with files.

  saltenvbase

    Specifies the fileserver environment from which to retrieve `archive`. This is only applicable when `archive` is a file from the `salt://` fileserver.

  source_hash

    If `name` is an http(s)/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 archive if the cached copy matches the specified hash.

    Added in version 2018.3.0.

  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 Examples:

      salt '*' archive.list /path/to/myfile.tar.gz
      salt '*' archive.list /path/to/myfile.tar.gz strip_components=1
      salt '*' archive.list salt://foo.tar.gz
      salt '*' archive.list https://domain.tld/myfile.zip
      salt '*' archive.list https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
      salt '*' archive.list ftp://10.1.2.3/foo.rar

salt.modules.archive.rar(rarfile, sources, template=None, cwd=None, runas=None)

  Uses rar for Linux to create rar files

  rarfile

    Path of rar file to be created

  sources

    Comma-separated list of sources to include in the rar file. Sources can also be passed in a Python list.

    Changed in version 2017.7.0: Globbing is now supported for this argument

  cwdNone

    Run the rar command from the specified directory. Use this argument along with relative file paths to create rar files which do not contain the leading directories. If not specified, this will default to the home directory of the user under which the salt minion process is running.

    Added in version 2014.7.1.

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.rar template=jinja /tmp/rarfile.rar '/tmp/sourcefile1,/tmp/{{grains.id}}.txt'

  CLI Example:

      salt '*' archive.rar /tmp/rarfile.rar /tmp/sourcefile1,/tmp/sourcefile2
      # Globbing for sources (2017.7.0 and later)
      salt '*' archive.rar /tmp/rarfile.rar '/tmp/sourcefile*'

salt.modules.archive.tar(options, tarfile, sources=None, dest=None, cwd=None, template=None, runas=None)

  Note

  This function has changed for version 0.17.0. In prior versions, the `cwd` and `template` arguments must be specified, with the source directories/files coming as a space-separated list at the end of the command. Beginning with 0.17.0, `sources` must be a comma-separated list, and the `cwd` and `template` arguments are optional.

  Uses the tar command to pack, unpack, etc. tar files

  options

    Options to pass to the tar command

    Changed in version 2015.8.0: The mandatory - prefixing has been removed. An options string beginning with a --long-option, would have uncharacteristically needed its first - removed under the former scheme.

    Also, tar will parse its options differently if short options are used with or without a preceding -, so it is better to not confuse the user into thinking they're using the non-- format, when really they are using the with-- format.

  tarfile

    The filename of the tar archive to pack/unpack

  sources

    Comma delimited list of files to pack into the tarfile. Can also be passed as a Python list.

    Changed in version 2017.7.0: Globbing is now supported for this argument

  dest

    The destination directory into which to unpack the tarfile

  cwdNone

    The directory in which the tar command should be executed. If not specified, will default to the home directory of the user under which the salt minion process is running.

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.tar cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} template=jinja

  CLI Examples:

      # Create a tarfile
      salt '*' archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1,/tmp/file_2
      # Create a tarfile using globbing (2017.7.0 and later)
      salt '*' archive.tar cjvf /tmp/tarfile.tar.bz2 '/tmp/file_*'
      # Unpack a tarfile
      salt '*' archive.tar xf foo.tar dest=/target/directory

salt.modules.archive.unrar(rarfile, dest, excludes=None, template=None, runas=None, trim_output=False)

  Uses rar for Linux to unpack rar files

  rarfile

    Name of rar file to be unpacked

  dest

    The destination directory into which to unpack the rar file

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{grains.id}}/ excludes=file_1,file_2

  trim_outputFalse

    The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100

  CLI Example:

      salt '*' archive.unrar /tmp/rarfile.rar /home/strongbad/ excludes=file_1,file_2

salt.modules.archive.unzip(zip_file, dest, excludes=None, options=None, template=None, runas=None, trim_output=False, password=None, extract_perms=True)

  Uses the `zipfile` Python module to unpack zip files

  Changed in version 2015.5.0: This function was rewritten to use Python's native zip file support. The old functionality has been preserved in the new function `archive.cmd_unzip`. For versions 2014.7.x and earlier, see the `archive.cmd_zip` documentation.

  zip_file

    Path of zip file to be unpacked

  dest

    The destination directory into which the file should be unpacked

  excludesNone

    Comma-separated list of files not to unpack. Can also be passed in a Python list.

  options

    This options are only used when `unzip` binary is used. In this function is ignored.

    Added in version 2016.3.1.

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{grains.id}}/ excludes=file_1,file_2

  runasNone

    Unpack the zip file as the specified user. Defaults to the user under which the minion is running.

  trim_outputFalse

    The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100

  CLI Example:

      salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2

  password

    Password to use with password protected zip files

    Note

    The password will be present in the events logged to the minion log file at the `debug` log level. If the minion is logging at `debug` (or more verbose), then be advised that the password will appear in the log.

    Added in version 2016.3.0.

  extract_permsTrue

    The Python zipfile module does not extract file/directory attributes by default. When this argument is set to `True`, Salt will attempt to apply the file permission attributes to the extracted files/folders.

    On Windows, only the read-only flag will be extracted as set within the zip file, other attributes (i.e. user/group permissions) are ignored.

    Set this argument to `False` to disable this behavior.

    Added in version 2016.11.0.

  CLI Example:

      salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ password='BadPassword'

salt.modules.archive.zip_(zip_file, sources, template=None, cwd=None, runas=None, zip64=False)

  Uses the `zipfile` Python module to create zip files

  Changed in version 2015.5.0: This function was rewritten to use Python's native zip file support. The old functionality has been preserved in the new function `archive.cmd_zip`. For versions 2014.7.x and earlier, see the `archive.cmd_zip` documentation.

  zip_file

    Path of zip file to be created

  sources

    Comma-separated list of sources to include in the zip file. Sources can also be passed in a Python list.

    Changed in version 2017.7.0: Globbing is now supported for this argument

  templateNone

    Can be set to 'jinja' or another supported template engine to render the command arguments before execution:

        salt '*' archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt

  cwdNone

    Use this argument along with relative paths in `sources` to create zip files which do not contain the leading directories. If not specified, the zip file will be created as if the cwd was `/`, and creating a zip file of `/foo/bar/baz.txt` will contain the parent directories `foo` and `bar`. To create a zip file containing just `baz.txt`, the following command would be used:

        salt '*' archive.zip /tmp/baz.zip baz.txt cwd=/foo/bar

  runasNone

    Create the zip file as the specified user. Defaults to the user under which the minion is running.

  zip64False

    Used to enable ZIP64 support, necessary to create archives larger than 4 GByte in size. If true, will create ZIP file with the ZIPp64 extension when the zipfile is larger than 2 GB. ZIP64 extension is disabled by default in the Python native zip support because the default zip and unzip commands on Unix (the InfoZIP utilities) don't support these extensions.

  CLI Example:

      salt '*' archive.zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
      # Globbing for sources (2017.7.0 and later)
      salt '*' archive.zip /tmp/zipfile.zip '/tmp/sourcefile*'