archive.zip
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
:mod:`archive.cmd_zip <salt.modules.archive.cmd_zip>`. For versions
2014.7.x and earlier, see the :mod:`archive.cmd_zip
<salt.modules.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
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.
zip64 : False
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*'
archive.list
New in version 2016.11.0
Changed in version 2016.11.2
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.
.. _rarfile: https://pypi.python.org/pypi/rarfile
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.
New in version 2016.11.2
clean : False
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.
verbose : False
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.
saltenv : base
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.
New in version 2018.3.0
.. _tarfile: https://docs.python.org/2/library/tarfile.html
.. _xz: http://tukaani.org/xz/
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
archive.cmd_unzip
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``.
.. _`Info-ZIP`: http://www.info-zip.org/
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 existing 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
password
Password to use with password protected zip files
Note:
This is not considered secure. It is recommended to instead use
:py:func:`archive.unzip <salt.modules.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.
New in version 2016.11.0
CLI Example:
salt '*' archive.cmd_unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2
archive.unzip
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
:mod:`archive.cmd_unzip <salt.modules.archive.cmd_unzip>`. For versions
2014.7.x and earlier, see the :mod:`archive.cmd_zip
<salt.modules.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
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.
New in version 2016.3.0
extract_perms : True
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.
New in version 2016.11.0
.. _zipfile: https://docs.python.org/2/library/zipfile.html
CLI Example:
salt '*' archive.unzip /tmp/zipfile.zip /home/strongbad/ password='BadPassword'
archive.tar
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
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
# 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
archive.gzip
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
runas : None
The user with which to run the gzip command line
options : None
Pass any additional arguments to gzip
New 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'
archive.cmd_zip
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``.
.. _`Info-ZIP`: http://www.info-zip.org/
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
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
# Globbing for sources (2017.7.0 and later)
salt '*' archive.cmd_zip /tmp/zipfile.zip '/tmp/sourcefile*'
archive.is_encrypted
New in version 2016.11.0
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.
clean : False
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.
saltenv : base
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.
New in version 2018.3.0
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
archive.unrar
Uses `rar for Linux`_ to unpack rar files
.. _`rar for Linux`: http://www.rarlab.com/
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
archive.rar
Uses `rar for Linux`_ to create rar files
.. _`rar for Linux`: http://www.rarlab.com/
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
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
# Globbing for sources (2017.7.0 and later)
salt '*' archive.rar /tmp/rarfile.rar '/tmp/sourcefile*'
archive.gunzip
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
runas : None
The user with which to run the gzip command line
options : None
Pass any additional arguments to gzip
New 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'
我是分割线