Note
This plugin is part of the community.general collection (version 3.8.1).
You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.general.
To use it in a playbook, specify: community.general.filesize.
New in version 3.0.0: of community.general
dd to create, extend or truncate a file, given its size. It can be used to manage swap files (that require contiguous blocks) or alternatively, huge sparse files.The below requirements are needed on the host that executes this module.
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| attributes string added in 2.3 of ansible.builtin | 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 | |
| blocksize raw | Size of blocks, in bytes if not followed by a multiplicative suffix. The numeric value (before the unit) MUST be an integer (or a float if it equals an integer).If not set, the size of blocks is guessed from the OS and commonly results in 512 or 4096 bytes, that is used internally by the module or when size has no unit. | |
| force boolean |
| Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When true, the module is not idempotent, that means it always reports changed=true.
force=true and sparse=true are mutually exclusive. |
| group string | Name of the group that should own the file/directory, as would be fed to chown. | |
| mode raw | 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 Ansible 1.8, the mode may be specified as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r).If mode is not specified and the destination file does not exist, the default umask on the system will be used when setting the mode for the newly created file.If mode is not specified and the destination file does exist, the mode of the existing file will be used.Specifying mode is the best way to ensure files are created with the correct permissions. See CVE-2020-1736 for further details. | |
| owner string | Name of the user that should own the file/directory, as would be fed to chown. | |
| path path / required | Path of the regular file to create or resize. | |
| selevel string | 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. | |
| serole string | The role part of the SELinux file context. When set to _default, it will use the role portion of the policy if available. | |
| setype string | The type part of the SELinux file context. When set to _default, it will use the type portion of the policy if available. | |
| seuser string | 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. | |
| size raw / required | Requested size of the file. The value is a number (either int or float) optionally followed by a multiplicative suffix, that can be one of B (bytes), KB or kB (= 1000B), MB or mB (= 1000kB), GB or gB (= 1000MB), and so on for T, P, E, Z and Y; or alternatively one of K, k or KiB (= 1024B); M, m or MiB (= 1024KiB); G, g or GiB (= 1024MiB); and so on.If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of blocksize bytes each (float values are rounded to the closest integer). When the size value is equal to the current file size, does nothing. When the size value is bigger than the current file size, bytes from source (if sparse is not false) are appended to the file without truncating it, in other words, without modifying the existing bytes of the file.When the size value is smaller than the current file size, it is truncated to the requested value without modifying bytes before this value. That means that a file of any arbitrary size can be grown to any other arbitrary size, and then resized down to its initial size without modifying its initial content. | |
| source path | Default: "/dev/zero" | Device or file that provides input data to provision the file. This parameter is ignored when sparse=true. |
| sparse boolean |
| Whether or not the file to create should be a sparse file. This option is effective only on newly created files, or when growing a file, only for the bytes to append. This option is not supported on OpenBSD, Solaris and AIX.
force=true and sparse=true are mutually exclusive. |
| unsafe_writes boolean added in 2.2 of ansible.builtin |
| This option is silently ignored. This module always modifies file size in-place. |
Note
check_mode and diff.See also
Manual page of the GNU/Linux’s dd implementation (from GNU coreutils).
Manual page of the IBM AIX’s dd implementation.
Manual page of the Mac OSX’s dd implementation.
Manual page of the Oracle Solaris’s dd implementation.
Manual page of the FreeBSD’s dd implementation.
Manual page of the OpenBSD’s dd implementation.
Manual page of the NetBSD’s dd implementation.
- name: Create a file of 1G filled with null bytes
community.general.filesize:
path: /var/bigfile
size: 1G
- name: Extend the file to 2G (2*1024^3)
community.general.filesize:
path: /var/bigfile
size: 2G
- name: Reduce the file to 2GB (2*1000^3)
community.general.filesize:
path: /var/bigfile
size: 2GB
- name: Fill a file with random bytes for backing a LUKS device
community.general.filesize:
path: ~/diskimage.luks
size: 512.0 MiB
source: /dev/urandom
- name: Take a backup of MBR boot code into a file, overwriting it if it exists
community.general.filesize:
path: /media/sdb1/mbr.bin
size: 440B
source: /dev/sda
force: true
- name: Create/resize a sparse file of/to 8TB
community.general.filesize:
path: /var/local/sparsefile
size: 8TB
sparse: true
- name: Create a file with specific size and attributes, to be used as swap space
community.general.filesize:
path: /var/swapfile
size: 2G
blocksize: 512B
mode: u=rw,go=
owner: root
group: root
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description | |
|---|---|---|---|
| cmd string | when changed or failed | Command executed to create or resize the file. Sample: /usr/bin/dd if=/dev/zero of=/var/swapfile bs=1048576 seek=3072 count=1024 | |
| filesize dictionary | always | Dictionary of sizes related to the file. | |
| blocks integer | success | Number of blocks in the file. Sample: 500 | |
| blocksize integer | success | Size of the blocks in bytes. Sample: 1024 | |
| bytes integer | success | Size of the file, in bytes, as the product of blocks and blocksize.Sample: 512000 | |
| iec string | success | Size of the file, in human-readable format, following IEC standard. Sample: 500.0 KiB | |
| si string | success | Size of the file, in human-readable format, following SI standard. Sample: 512.0 kB | |
| path string | always | Realpath of the file if it is a symlink, otherwise the same than module's param. Sample: /var/swap0 | |
| size_diff integer | always | Difference (positive or negative) between old size and new size, in bytes. Sample: -1234567890 | |
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/filesize_module.html