linsomniac.fsbuilder.fsbuilder — Ansible Module Documentation

Description

Manages filesystem objects (files, directories, links) with a single task.

Supports template rendering (via action plugin), copy, mkdir, touch, rm, symlink, hardlink, lineinfile, and blockinfile operations.

Each invocation handles a single item (Ansible loop handles iteration).

Parameters

Parameter	Type	Description
`access_time`	`str`	For state=touch, set file access time (epoch or datetime string).
`allow_unsafe_deletes`	`bool`	When true, disables safety checks that prevent deletion of critical system paths (C(/), C(/etc), C(/usr), etc.) with state=absent. Use with extreme caution. This is a safety override for rare cases where you genuinely need to remove a protected path. default: False
`backup`	`bool`	Create timestamped backup before overwriting. default: False
`block`	`str`	For state=blockinfile, the block content.
`block_state`	`str`	For state=blockinfile, whether block should be present or absent. default: 'present' choices: present, absent
`content`	`str`	Literal content to write to dest. Mutually exclusive with C(src).
`creates`	`path`	Skip this item if the specified path exists.
`dest` required	`path`	Target filesystem path.
`follow`	`bool`	Follow symlinks when setting attributes. default: True
`force`	`bool`	Force replacement of conflicting existing paths. default: False
`force_backup`	`bool`	When force is true, rename existing path instead of deleting. default: False
`insertafter`	`str`	Insert after matching line. Special value EOF appends.
`insertbefore`	`str`	Insert before matching line. Special value BOF prepends.
`line`	`str`	For state=lineinfile, the line to ensure present/absent.
`line_state`	`str`	For state=lineinfile, whether line should be present or absent. default: 'present' choices: present, absent
`makedirs`	`bool`	Create parent directories if they don't exist. default: False
`marker`	`str`	For state=blockinfile, marker template with {mark} placeholder. default: '# {mark} MANAGED BLOCK'
`marker_begin`	`str`	String to replace {mark} in opening marker. default: 'BEGIN'
`marker_end`	`str`	String to replace {mark} in closing marker. default: 'END'
`modification_time`	`str`	For state=touch, set file modification time (epoch or datetime string).
`recurse`	`bool`	For state=directory, apply attributes recursively. default: False
`regexp`	`str`	For state=lineinfile, regex pattern to match.
`remote_src`	`bool`	If true, src refers to a path on the remote host. default: False
`removes`	`path`	Skip this item if the specified path does not exist.
`src`	`path`	Source file path. For copy/template states, the source file. For link/hard states, the link target. Mutually exclusive with C(content).
`state`	`str`	The desired filesystem state. default: 'template' choices: template, copy, directory, exists, touch, absent, link, hard, lineinfile, blockinfile
`validate`	`str`	Command to validate file before moving into place. Must contain C(%s) placeholder for the temp file path.

Examples

- name: Deploy myapp - comprehensive example with loop
  linsomniac.fsbuilder.fsbuilder:
    owner: root
    group: myapp
    mode: a=rX,u+w
  loop:
    - dest: /etc/myapp/conf.d
      state: directory
    - dest: /etc/myapp/config.ini
      validate: "myapp --check-config %s"
      backup: true
      notify: Restart myapp
    - dest: /etc/myapp/version.txt
      content: "version={{ app_version }}"
    - dest: /etc/myapp/static.dat
      state: copy
    - dest: /etc/myapp/current
      src: /opt/myapp/releases/v2.1
      state: link
    - dest: /etc/myapp/.last-deploy
      state: touch
    - dest: /etc/myapp/legacy.conf
      state: absent

- name: Create a directory
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp
    state: directory
    mode: "0755"

- name: Write content to a file
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/config.ini
    state: copy
    content: |
      [main]
      setting = value

- name: Copy a file from the controller
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/static.dat
    state: copy

- name: Render a Jinja2 template (default state)
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/config.ini
    # state: template is the default; renders config.ini.j2

- name: Render an inline template
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/version.txt
    state: template
    content: "version={{ app_version }}"

- name: Create a symlink
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/current
    state: link
    src: /opt/myapp/releases/v2.1

- name: Create a hard link
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/hardlink.txt
    state: hard
    src: /etc/myapp/original.txt

- name: Ensure a file exists (empty if new)
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/flag
    state: exists

- name: Touch a file (always update timestamp)
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/.last-deploy
    state: touch

- name: Remove a file
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/legacy.conf
    state: absent

- name: Remove files matching a glob
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/myapp/conf.d/*.rpmsave
    state: absent

- name: Ensure a line is present in sshd_config
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/ssh/sshd_config
    state: lineinfile
    regexp: "^PermitRootLogin"
    line: "PermitRootLogin no"

- name: Manage a block in /etc/hosts
  linsomniac.fsbuilder.fsbuilder:
    dest: /etc/hosts
    state: blockinfile
    marker: "# {mark} ANSIBLE MANAGED - myapp"
    block: |
      192.168.1.10 app1.internal
      192.168.1.11 app2.internal

Return Values

Key	Type	Description	Returned
`backup_file`	`str`	Path to backup file if backup was created.	when backup is created
`changed`	`bool`	Whether any change was made.	always
`dest`	`str`	The target path.	always
`diff`	`dict`	Before/after diff when diff mode is enabled.	when diff mode is on and content changed
`msg`	`str`	Human-readable result message.	always
`state`	`str`	The state that was applied.	always