From 8e4ad3cff3974edefcc5bb1e402d89afb75b2d4f Mon Sep 17 00:00:00 2001 From: Erik Johnson Date: Thu, 8 Dec 2016 12:41:30 -0600 Subject: [PATCH] Update information about xz-utils in archive state/module docs This may confuse people who aren't aware of what xz-utils is, and believe that they need some weird third-party application. --- salt/modules/archive.py | 20 ++++++++++++++++---- salt/states/archive.py | 14 +++++++------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/salt/modules/archive.py b/salt/modules/archive.py index 8c79c3746a..99e71bc77d 100644 --- a/salt/modules/archive.py +++ b/salt/modules/archive.py @@ -49,8 +49,20 @@ def list_(name, .. note:: This function will only provide results for XZ-compressed archives if - xz-utils_ is installed, as Python does not at this time natively - support XZ compression in its tarfile_ module. + 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: + + .. code-block:: bash + + 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 @@ -100,7 +112,7 @@ def list_(name, the ``salt://`` fileserver. .. _tarfile: https://docs.python.org/2/library/tarfile.html - .. _xz-utils: http://tukaani.org/xz/ + .. _xz: http://tukaani.org/xz/ CLI Examples: @@ -153,7 +165,7 @@ def list_(name, raise CommandExecutionError( 'Unable to list contents of {0}. If this is an XZ-compressed tar ' - 'archive, install xz-utils to enable listing its contents. If it ' + 'archive, install XZ Utils to enable listing its contents. If it ' 'is compressed using something other than XZ, it may be necessary ' 'to specify CLI options to decompress the archive. See the ' 'documentation for details.'.format(name) diff --git a/salt/states/archive.py b/salt/states/archive.py index 5fc1cb8b36..e6c9aee6c7 100644 --- a/salt/states/archive.py +++ b/salt/states/archive.py @@ -334,8 +334,8 @@ def extracted(name, .. versionchanged:: 2015.8.11,2016.3.2 XZ-compressed tar archives no longer require ``J`` to manually be set in the ``options``, they are now detected automatically and - decompressed using xz-utils_ and extracted using ``tar xvf``. This - is a more platform-independent solution, as not all tar + decompressed using the xz_ CLI command and extracted using ``tar + xvf``. This is a more platform-independent solution, as not all tar implementations support the ``J`` argument for extracting archives. .. note:: @@ -358,9 +358,9 @@ def extracted(name, the archive has already been extracted. For the vast majority of tar archives, :py:func:`archive.list ` "just works". Archives compressed using gzip, bzip2, and xz/lzma (with the - help of xz-utils_) are supported automatically. However, for archives - compressed using other compression types, CLI options must be passed to - :py:func:`archive.list `. + help of the xz_ CLI command) are supported automatically. However, for + archives compressed using other compression types, CLI options must be + passed to :py:func:`archive.list `. This argument will be passed through to :py:func:`archive.list ` as its ``options`` argument, to allow it @@ -485,7 +485,7 @@ def extracted(name, .. _tarfile: https://docs.python.org/2/library/tarfile.html .. _zipfile: https://docs.python.org/2/library/zipfile.html - .. _xz-utils: http://tukaani.org/xz/ + .. _xz: http://tukaani.org/xz/ overwrite If archive was already extracted, then setting this to True will @@ -1054,7 +1054,7 @@ def extracted(name, # XZ-compressed data log.debug( 'Tar file is XZ-compressed, attempting ' - 'decompression and extraction using xz-utils ' + 'decompression and extraction using XZ Utils ' 'and the tar command' ) # Must use python_shell=True here because not