Try SpotterCreate a file with a given size, or resize it if it exists
| "added in version" 3.0.0 of community.general"
Authors: quidame (@quidame)
Install with ansible-galaxy collection install community.general:==8.5.0
collections:
- name: community.general
version: 8.5.0This module is a simple wrapper around C(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.
- 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
mode:
description:
- The permissions the resulting filesystem object should have.
- For those used to I(/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, V('644') or V('1777')) so Ansible receives
a string and can do its own conversion from string into number. Adding a leading
zero (for example, V(0755)) works sometimes, but can fail in loops and some other
circumstances.
- 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, V(u+rwx)
or V(u=rw,g=r,o=r)).
- If O(mode) is not specified and the destination filesystem object B(does not) exist,
the default C(umask) on the system will be used when setting the mode for the newly
created filesystem object.
- If O(mode) is not specified and the destination filesystem object B(does) exist,
the mode of the existing filesystem object will be used.
- Specifying O(mode) is the best way to ensure filesystem objects are created with
the correct permissions. See CVE-2020-1736 for further details.
type: raw
path:
description:
- Path of the regular file to create or resize.
required: true
type: path
size:
description:
- Requested size of the file.
- The value is a number (either C(int) or C(float)) optionally followed by a multiplicative
suffix, that can be one of V(B) (bytes), V(KB) or V(kB) (= 1000B), V(MB) or V(mB)
(= 1000kB), V(GB) or V(gB) (= 1000MB), and so on for V(T), V(P), V(E), V(Z) and
V(Y); or alternatively one of V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB)
(= 1024KiB); V(G), V(g) or V(GiB) (= 1024MiB); and so on.
- If the multiplicative suffix is not provided, the value is treated as an integer
number of blocks of O(blocksize) bytes each (float values are rounded to the closest
integer).
- When the O(size) value is equal to the current file size, does nothing.
- When the O(size) value is bigger than the current file size, bytes from O(source)
(if O(sparse) is not V(false)) are appended to the file without truncating it, in
other words, without modifying the existing bytes of the file.
- When the O(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.
required: true
type: raw
force:
default: false
description:
- Whether or not to overwrite the file if it exists, in other words, to truncate it
from 0. When V(true), the module is not idempotent, that means it always reports
C(changed=true).
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
group:
description:
- Name of the group that should own the filesystem object, as would be fed to I(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.
type: str
owner:
description:
- Name of the user that should own the filesystem object, as would be fed to I(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.
type: str
serole:
description:
- The role part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(role) portion of the policy if available.
type: str
setype:
description:
- The type part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(type) portion of the policy if available.
type: str
seuser:
description:
- The user part of the SELinux filesystem object context.
- By default it uses the V(system) policy, where applicable.
- When set to V(_default), it will use the C(user) portion of the policy if available.
type: str
source:
default: /dev/zero
description:
- Device or file that provides input data to provision the file.
- This parameter is ignored when O(sparse=true).
type: path
sparse:
default: false
description:
- 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.
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
selevel:
description:
- The level part of the SELinux filesystem object context.
- This is the MLS/MCS attribute, sometimes known as the C(range).
- When set to V(_default), it will use the C(level) portion of the policy if available.
type: str
blocksize:
description:
- Size of blocks, in bytes if not followed by a multiplicative suffix.
- The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals
an integer).
- If not set, the size of blocks is guessed from the OS and commonly results in V(512)
or V(4096) bytes, that is used internally by the module or when O(size) has no unit.
type: raw
attributes:
aliases:
- attr
description:
- The attributes the resulting filesystem object should have.
- To get supported flags look at the man page for I(chattr) on the target system.
- This string should contain the attributes in the same order as the one displayed
by I(lsattr).
- The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to
be included in the string.
type: str
version_added: '2.3'
version_added_collection: ansible.builtin
unsafe_writes:
default: false
description:
- This option is silently ignored. This module always modifies file size in-place.
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
cmd:
description: Command executed to create or resize the file.
returned: when changed or failed
sample: /usr/bin/dd if=/dev/zero of=/var/swapfile bs=1048576 seek=3072 count=1024
type: str
filesize:
contains:
blocks:
description: Number of blocks in the file.
sample: 500
type: int
blocksize:
description: Size of the blocks in bytes.
sample: 1024
type: int
bytes:
description: Size of the file, in bytes, as the product of RV(filesize.blocks)
and RV(filesize.blocksize).
sample: 512000
type: int
iec:
description: Size of the file, in human-readable format, following IEC standard.
sample: 500.0 KiB
type: str
si:
description: Size of the file, in human-readable format, following SI standard.
sample: 512.0 kB
type: str
description: Dictionary of sizes related to the file.
returned: always
type: dict
path:
description: Realpath of the file if it is a symlink, otherwise the same than module's
param.
returned: always
sample: /var/swap0
type: str
size_diff:
description: Difference (positive or negative) between old size and new size, in
bytes.
returned: always
sample: -1234567890
type: int