ansible 之 unarchive

unarchive

用途：将归档文件解压缩

官方文档

[root@ansible ~]# ansible-doc unarchive
> UNARCHIVE    (/usr/lib/python2.7/site-packages/ansible-2.8.0.dev0-py2.7.egg/ansible/modules/files/unarchive.py)

        The `unarchive' module unpacks an archive. By default, it will copy the source file from the local system to the target before unpacking. Set `remote_src=yes' to
        unpack an archive which already exists on the target. For Windows targets, use the [win_unzip] module instead. If checksum validation is desired, use [get_url] or
        [uri] instead to fetch the file and set `remote_src=yes'.

  * This module is maintained by The Ansible Core Team
  * note: This module has a corresponding action plugin.

OPTIONS (= is mandatory):

- attributes
        The attributes the resulting file or directory should have.
        To get supported flags look at the man page for `chattr' on the target system.
        This string should contain the attributes in the same order as the one displayed by `lsattr'.
        The `=' operator is assumed as default, otherwise `+' or `-' operators need to be included in the string.
        (Aliases: attr)[Default: (null)]
        version_added: 2.3

- copy
        If true, the file is copied from local 'master' to the target machine, otherwise, the plugin will look for src archive at the target machine.
        This option has been deprecated in favor of `remote_src'.
        This option is mutually exclusive with `remote_src'.
        [Default: yes]
        type: bool

- creates
        If the specified absolute path (file or directory) already exists, this step will *not* be run.
        [Default: (null)]
        version_added: 1.6

- decrypt
        This option controls the autodecryption of source files using vault.
        [Default: yes]
        type: bool
        version_added: 2.4

= dest
        Remote absolute path where the archive should be unpacked.


- exclude
        List the directory and file entries that you would like to exclude from the unarchive action.
        [Default: (null)]
        version_added: 2.1

- extra_opts
        Specify additional options by passing in an array.
        [Default: ]
        version_added: 2.1

- group
        Name of the group that should own the file/directory, as would be fed to `chown'.
        [Default: (null)]

- keep_newer
        Do not replace existing files that are newer than files from the archive.
        [Default: no]
        type: bool
        version_added: 2.1

- list_files
        If set to True, return the list of files that are contained in the tarball.
        [Default: no]
        type: bool
        version_added: 2.0

- mode
        The permissions the resulting file or directory should have.
        For those used to `/usr/bin/chmod' remember that modes are actually octal numbers. You must either add a leading zero so that Ansible's YAML parser knows it is an
        octal number (like `0644' or `01777') or quote it (like `'644'' or `'1777'') so Ansible receives a string and can do its own conversion from string into number.
        Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results.
        As of version 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx' or `u=rw,g=r,o=r').
        As of version 2.6, the mode may also be the special string `preserve'.
        When set to `preserve' the file will be given the same permissions as the source file.
        [Default: (null)]

- owner
        Name of the user that should own the file/directory, as would be fed to `chown'.
        [Default: (null)]

- remote_src
        Set to `yes' to indicate the archived file is already on the remote system and not local to the Ansible controller.
        This option is mutually exclusive with `copy'.
        [Default: no]
        type: bool
        version_added: 2.2

- selevel
        The level part of the SELinux file context.
        This is the MLS/MCS attribute, sometimes known as the `range'.
        When set to `_default', it will use the `level' portion of the policy if available.
        [Default: s0]

- serole
        The role part of the SELinux file context.
        When set to `_default', it will use the `role' portion of the policy if available.
        [Default: (null)]

- setype
        The type part of the SELinux file context.
        When set to `_default', it will use the `type' portion of the policy if available.
        [Default: (null)]

- seuser
        The user part of the SELinux file context.
        By default it uses the `system' policy, where applicable.
        When set to `_default', it will use the `user' portion of the policy if available.
        [Default: (null)]

= src
        If `remote_src=no' (default), local path to archive file to copy to the target server; can be absolute or relative. If `remote_src=yes', path on the target server
        to existing archive file to unpack.
        If `remote_src=yes' and `src' contains `://', the remote machine will download the file from the URL first. (version_added 2.0). This is only for simple cases, for
        full download support use the [get_url] module.


- unsafe_writes
        Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file.
        By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files, but sometimes systems are configured or just
        broken in ways that prevent this. One example is docker mounted files, which cannot be updated atomically from inside the container and can only be written in an
        unsafe manner.
        This option allows Ansible to fall back to unsafe methods of updating files when atomic operations fail (however, it doesn't force Ansible to perform unsafe
        writes).
        IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.
        [Default: False]
        type: bool
        version_added: 2.2

- validate_certs
        This only applies if using a https URL as the source of the file.
        This should only set to `no' used on personally controlled sites using self-signed certificate.
        Prior to 2.2 the code worked as if this was set to `yes'.
        [Default: yes]
        type: bool
        version_added: 2.2


NOTES:
      * Requires `gtar'/`unzip' command on target host.
      * Can handle `.zip' files using `unzip' as well as `.tar', `.tar.gz', `.tar.bz2' and `.tar.xz' files using `gtar'.
      * Uses gtar's `--diff' arg to calculate if changed or not. If this `arg' is not supported, it will always unpack the archive.
      * Existing files/directories in the destination which are not in the archive are not touched. This is the same behavior as a normal archive extraction.
      * Existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not.
      * For Windows targets, use the [win_unzip] module instead.

AUTHOR: Michael DeHaan
        METADATA:
          status:
          - preview
          supported_by: core
        
TODO: Re-implement tar support using native tarfile module., Re-implement zip support using native zipfile module.

EXAMPLES:
- name: Extract foo.tgz into /var/lib/foo
  unarchive:
    src: foo.tgz
    dest: /var/lib/foo

- name: Unarchive a file that is already on the remote machine
  unarchive:
    src: /tmp/foo.zip
    dest: /usr/local/bin
    remote_src: yes

- name: Unarchive a file that needs to be downloaded (added in 2.0)
  unarchive:
    src: https://example.com/example.zip
    dest: /usr/local/bin
    remote_src: yes

- name: Unarchive a file with extra options
  unarchive:
    src: /tmp/foo.zip
    dest: /usr/local/bin
    extra_opts:
    - --transform
    - s/^xxx/yyy/

参数说明

• attributes

• copy
  默认值：yes
  类型：bool
  如果 copy 值设置为 yes ，则在解压缩归档文件之前，先将压缩包拷贝到远程主机上，再解压文件。这个参数将被遗弃，倾向于使用 remote_src`

• creates
  默认值：null
  如果特定的绝对路径（文件或目录）已经存在，则这步不会执行

• decrypt
  默认值：yes
  类型：bool
  用 vault 自动解压缩源文件

• dest
  远程主机的绝对路径

• exclude
  默认值：null
  解压缩完文件以后，列出文件目录

• extra_opts
  传入额外的参数

• group
  默认值：null
  文件或目录所属组

• keep_newer
  默认值：no
  类型：bool
  如果远程主机上已存在该文件，且改文件内容比归档的文件更新，则不会替换远程主机上的文件

• list_files
  默认值：no
  类型：bool

• mode
  默认值：null
  权限设置

• owner
  默认值：null
  设置所属用户

• remote_src
  默认值：no
  类型：bool
  如果设置为 yes，则会解压缩远程主机上已经存在的压缩文件。而不是先把管理机上的压缩文件先拷贝到远程主机，再解压缩

• selevel

• setype

• seuser

• src
  如果 remote_src=no （默认值），则会将本地的压缩包文件拷贝到远程主机，可以是相对路径，也可以是绝对路径。
  如果 remote_src=yes（默认值）， src中包含 ://，则远程主机先从 URL 中下载文件。也可参考 get_url 模块

• unsafe_writes

• validate_certs
  默认值：yes
  类型：bool
  只是用于 https 类型的 URL 源文件