community.general.filesize module – Create a file with a given size, or resize it if it exists
Note
This module is part of the community.general collection (version 8.6.4).
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
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.filesize
.
New in community.general 3.0.0
Synopsis
This module is a simple wrapper around
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.
Aliases: files.filesize
Requirements
The below requirements are needed on the host that executes this module.
dd (Data Duplicator) in PATH
Parameters
Parameter |
Comments |
---|---|
The attributes the resulting filesystem object 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 |
|
Size of blocks, in bytes if not followed by a multiplicative suffix. The numeric value (before the unit) MUST be an integer (or a If not set, the size of blocks is guessed from the OS and commonly results in |
|
Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When
Choices:
|
|
Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, Giving Ansible a number without following either 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, If If Specifying |
|
Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
Path of the regular file to create or resize. |
|
The level part of the SELinux filesystem object context. This is the MLS/MCS attribute, sometimes known as the When set to |
|
The role part of the SELinux filesystem object context. When set to |
|
The type part of the SELinux filesystem object context. When set to |
|
The user part of the SELinux filesystem object context. By default it uses the When set to |
|
Requested size of the file. The value is a number (either If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of When the When the When the 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. |
|
Device or file that provides input data to provision the file. This parameter is ignored when Default: |
|
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 OSes or filesystems not supporting sparse files.
Choices:
|
|
This option is silently ignored. This module always modifies file size in-place. Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: full |
Will return details on what has changed (or possibly needs changing in |
See Also
See also
- dd(1) manpage for Linux
Manual page of the GNU/Linux’s dd implementation (from GNU coreutils).
- dd(1) manpage for IBM AIX
Manual page of the IBM AIX’s dd implementation.
- dd(1) manpage for Mac OSX
Manual page of the Mac OSX’s dd implementation.
- dd(1M) manpage for Solaris
Manual page of the Oracle Solaris’s dd implementation.
- dd(1) manpage for FreeBSD
Manual page of the FreeBSD’s dd implementation.
- dd(1) manpage for OpenBSD
Manual page of the OpenBSD’s dd implementation.
- dd(1) manpage for NetBSD
Manual page of the NetBSD’s dd implementation.
- busybox(1) manpage for Linux
Manual page of the GNU/Linux’s busybox, that provides its own dd implementation.
Examples
- 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Command executed to create or resize the file. Returned: when changed or failed Sample: |
|
Dictionary of sizes related to the file. Returned: always |
|
Number of blocks in the file. Returned: success Sample: |
|
Size of the blocks in bytes. Returned: success Sample: |
|
Size of the file, in bytes, as the product of Returned: success Sample: |
|
Size of the file, in human-readable format, following IEC standard. Returned: success Sample: |
|
Size of the file, in human-readable format, following SI standard. Returned: success Sample: |
|
Realpath of the file if it is a symlink, otherwise the same than module’s param. Returned: always Sample: |
|
Difference (positive or negative) between old size and new size, in bytes. Returned: always Sample: |