salt.modules.archive

A module to wrap (non-Windows) archive calls

New in version 2014.1.0.

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

New 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
excludes
: None
Comma-separated list of files not to unpack. Can also be passed in a Python list.
template
: None

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 exsiting files with o. This options are only used when unzip binary is used.

New in version 2016.3.1.

runas
: None

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

New in version 2015.5.0.

trim_output
: False
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.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)

New 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.
template
: None

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
cwd
: None

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

New in version 2014.7.1.

runas
: None

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

New in version 2015.5.0.

CLI Example:

salt '*' archive.cmd_zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2
salt.modules.archive.gunzip(gzipfile, template=None, runas=None)

Uses the gunzip command to unpack gzip files

template
: None

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

CLI Example:

# Create /tmp/sourcefile.txt
salt '*' archive.gunzip /tmp/sourcefile.txt.gz
salt.modules.archive.gzip(sourcefile, template=None, runas=None)

Uses the gzip command to create gzip files

template
: None

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

CLI Example:

# Create /tmp/sourcefile.txt.gz
salt '*' archive.gzip /tmp/sourcefile.txt
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.
cwd
: None

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.

New in version 2014.7.1.

template
: None

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
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.
dest
The destination directory into which to unpack the tarfile
cwd
: None
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.
template
: None

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
# 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
template
: None

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_output
: False
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=False)

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
excludes
: None
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.

New in version 2016.3.1.

template
: None

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
runas
: None
Unpack the zip file as the specified user. Defaults to the user under which the minion is running.
trim_output
: False
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: None

Password to use with password protected zip files

New in version 2016.3.0.

extract_perms: False

The python zipfile module does not extract file/directory attributes by default. Setting this flag will attempt to apply the file permision 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.

New in version Carbon.

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)

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.
template
: None

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
cwd
: None

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
runas
: None
Create the zip file as the specified user. Defaults to the user under which the minion is running.

CLI Example:

salt '*' archive.zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2