User’s guide

Introduction

• Ansible role: config_light

• Supported systems: FreeBSD, Ubuntu

• Requirements: ansible.posix , community.general

The role installs packages, creates and configures files and services. The handlers are created from user provided data. The control-flow will be determined by the user provided configuration data. Some attributes of the dictionaries determine which Ansible module will be used. This data-driven programming paradigm provides a flexible, and robust framework to apply basic Ansible modules. In the code, each Ansible module is used only once. This makes the implementation, upgrading, and testing of the modules simple and easy.

The user of this role is expected to master at least the following Ansible topics:

• Basic Concepts

• Roles

• Working With Playbooks

The supported OS (FreeBSD and Ubuntu) can use the role to install and configure arbitrary applications. Other Linux distributions, that support the used Ansible modules, should work with minimal changes. BSD*, Debian, and Red Hat ansible_os_family should work out of the box.

There are four imported tasks in the first part of the role to setup handlers, assemble, and check the configuration data:

tasks     description                  tags               enabled (default)
___________________________________________________________________________
setup     create handlers              cl_setup, always   cl_setup=true
vars      assemble configuration data  cl_vars, always    always
sanity    check sanity                 cl_sanity, always  cl_sanity=true
debug     help debugging data          cl_debug           cl_debug=false

Then, there are four imported tasks to manage the infrastructure:

tasks     description                  tags               enabled (default)
___________________________________________________________________________
packages  install packages             cl_packages        cl_install=true
states    modify states of files       cl_states          always
files     configure files              cl_files           always
services  configure services           cl_services        always

• packages: The Ansible modules package, apt, yum, and snap are used to install Linux packages. In FreeBSD, modules pkgng and portinstall are used to install FreeBSD packages and ports.

• states: The Ansible module mount is used to mount and unmount paths, and to configure fstab. The module file is used to modify states of files.

• files: The Ansible modules template, copy, replace, patch, lineinfile, blockinfile, and ini_file are used to configure files.

• services: The Ansible Module service is used to configure both Linux and BSD services.

See also

The directory contrib comprises examples on how to install and configure various applications and how to create handlers and templates. Some of them are commented Examples.

Hint

Feel free to share your feedback and report issues. The contributions to the project are welcome.

Installation

The most convenient way how to install an Ansible role is to use Ansible Galaxy CLI ansible-galaxy. The utility comes with the standard Ansible package and provides the user with a simple interface to the Ansible Galaxy’s services. For example, take a look at the current status of the role

shell> ansible-galaxy role info vbotka.config_light

and install it

shell> ansible-galaxy role install vbotka.config_light

Install the collections community.general and ansible.posix if necessary

shell> ansible-galaxy collection install ansible.posix
shell> ansible-galaxy collection install community.general

Install yamllint to use the default validation of the created handlers and assembled data. See the variables cl_assemble_validate and cl_handlers_validate in defaults/main.yml. Optionally, install and configure ansible-lint.

Note

• By default sanity checking of yamllint is disabled (cl_sanity_yamllint: false)

Hint

• To install specific versions from various sources see Ansible Galaxy

• Take a look at other roles shell> ansible-galaxy search --author=vbotka

Playbook

Below is a simple playbook that calls this role (11) at a single host srv.example.com (2)

shell> cat pb.yml
- hosts: srv.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: true
  become_user: root
  become_method: sudo

  roles:
    - vbotka.config_light

Note

• gather_facts: true (3) must be set to gather facts needed to evaluate OS-specific options of the role. For example, the variable ansible_os_family is needed to select the Ansible module to install packages.

• For details see Connection Plugins (4-5)

• and Understanding Privilege Escalation (6-8)

Debug

To see additional information enable debug output in the configuration

cl_debug: true

, or set the extra variable in the command:

shell> ansible-playbook pb.yml -e cl_debug=true

Note

The debug output of this role is optimized for the yaml callback plugin. Set this plugin, for example, in the environment shell> export ANSIBLE_STDOUT_CALLBACK=yaml.

See also

• Playbook Debugger

• Debugging modules

• Python Debugging With Pdb

Tags

The tags provide a handy tool to run selected tasks of the role. The below command lists the available tags:

shell> ansible-playbook pb.yml --list-tags

playbook: pb.yml

  play #1 (srv.example.com): srv.example.com        TAGS: []
  TASK TAGS: [always, cl_debug, cl_files, cl_packages, cl_sanity,
  cl_services, cl_setup, cl_states, cl_vars]

For example, by using the tag cl_debug display the variables and their values (when enabled cl_debug: true). With this tag specified ‘-t cl_debug’ all tasks imported before the task debug.yml (setup.yml, vars.yml, and sanity.yml) will also run because of the tag always (when enabled cl_sanity: true and cl_setup: true)

shell> ansible-playbook pb.yml -t cl_debug -e cl_debug=true

See what packages will be installed

shell> ansible-playbook pb.yml -t cl_packages --check

Install packages and exit the play

shell> ansible-playbook pb.yml -t cl_packages

See also

• See Best practice on how to use tags efficiently

• See main.yml annotated source code

Hint

• Do not display skipped hosts. Set ANSIBLE_DISPLAY_SKIPPED_HOSTS=false

  shell> ANSIBLE_DISPLAY_SKIPPED_HOSTS=false ansible-playbook pb.yml -t cl_debug
  

Variables

The Default variables control the options of the role.

The most important are the variables that control the collection of the configuration data. In each project, customize the files with the configuration data stored in the directory cl_dird

See also

• See vars.yml annotated source code

• Ansible variable precedence: Where should I put a variable?

Note

The names of the dictionaries in the configuration files cl_dird/*.d/* are not used by the role and can be any arbitrary strings that are valid names of Ansible variables. The names must be unique in the particular section (files.d, packages.d, …).

Default variables

Default variables are stored in the directory defaults.

Most of the variables are self-explaining. There are five very important variables cl_handlers, cl_packages, cl_states, cl_services, and cl_files (26-30). These dictionaries, which comprise the configuration data of handlers, packages, services, and files, will be explained in details. By default, these dictionaries are empty.

Best practice is to provide the data either in host_vars and group_vars or as a files in the directories cl_handlersd_dir, cl_packagesd_dir, cl_statesd_dir, cl_servicesd_dir, and cl_filesd_dir (37-41). Both methods can be applied at the same time. The variables will be assembled and combined by the tasks vars_handlers.yml, vars_packages.yml, vars_states.yml, vars_services.yml, and vars_files.yml. The assembled dictionaries, customized for each host in the play, will be stored in the host-specific files cl_packagesd, cl_statesd, cl_servicesd, and cl_filesd (60-63). The variable cl_handlers is not host-specific because the handlers will be created at the controller (localhost) only. Assembled dictionary cl_handlers will be stored in the file cl_handlersd (59). Take a look at the assembled data in the directory cl_dira (58).

By default, the base of the directories is role_path (36). The user is expected to put the configuration data to a more suitable directory, for example, to playbook_dir directory.

[defaults/main.yml]

---
# defaults for config_light

cl_setup: true                  # Import tasks/setup.yml
cl_install: true                # Install packages or ports
cl_debug: false                 # Print debug output
cl_backup: false                # Backup files
cl_copyfile_delete: false       # Delete dest then copy samples and defaults
cl_template_delete: false       # Delete dest then create from templates

# Sanity
cl_sanity: true                 # Import tasks/sanity.yml
cl_sanity_quiet: true           # Module assert, parameter quiet
cl_sanity_collections: false    # Test required collections
cl_sanity_modules_pkg: true     # Test modules in cl_packages are supported
cl_sanity_yamllint: false       # Test yamllint is installed

# Supported
cl_supported_linux_family: [Debian, RedHat]
cl_supported_modules_pkg: [apt, package, pkgng, snap, yum]

# Required collections
cl_collections: [ansible.posix, community.general]

# Combine assembled data with these variables
cl_handlers: {}
cl_packages: {}
cl_services: {}
cl_files: {}
cl_states: {}

# Assemble data from these directories
# cl_dird_owner: root        # no default
# cl_dird_group: adm         # no default
cl_dird_dmode: '0775'        # default very permissive, restrict if necessary
cl_dird: "{{ role_path }}/files"
cl_handlersd_dir: "{{ cl_dird }}/handlers.d"
cl_packagesd_dir: "{{ cl_dird }}/packages.d"
cl_servicesd_dir: "{{ cl_dird }}/services.d"
cl_filesd_dir: "{{ cl_dird }}/files.d"
cl_statesd_dir: "{{ cl_dird }}/states.d"

# Lint
cl_yamllint: yamllint
cl_yamllint_rules:
  extends: default
  rules:
    line-length:
      level: warning
cl_assemble_validate: "{{ cl_yamllint }} -d '{{ cl_yamllint_rules|to_json }}' %s"
cl_handlers_validate: "{{ cl_yamllint }} -d '{{ cl_yamllint_rules|to_json }}' %s"

# Assemble inventory_hostname data into these files
# cl_dira_owner: root        # no default
# cl_dira_group: adm         # no default
cl_dira_dmode: '0775'        # default very permissive, restrict if necessary
cl_dira_fmode: '0664'        # default very permissive, restrict if necessary
cl_dira: "{{ cl_dird }}/assemble"
cl_handlersd: "{{ cl_dira }}/handlersd"  # localhost; not inventory_hostname specific
cl_packagesd: "{{ cl_dira }}/packagesd.{{ inventory_hostname }}"
cl_servicesd: "{{ cl_dira }}/servicesd.{{ inventory_hostname }}"
cl_filesd: "{{ cl_dira }}/filesd.{{ inventory_hostname }}"
cl_statesd: "{{ cl_dira }}/statesd.{{ inventory_hostname }}"
cl_assemble_regexp: '^(.*)[^~]$' # Any string but terminated by ~
# Delete packagesd, servicesd, filesd, and statesd before assembling
cl_all_delete: false             # Delete packagesd, servicesd, filesd, and statesd
cl_packagesd_delete: false       # Delete packagesd
cl_servicesd_delete: false       # Delete servicesd
cl_filesd_delete: false          # Delete filesd
cl_statesd_delete: false         # Delete statesd

# Role handlers directory
# cl_handlers_dir_owner: admin   # no default
# cl_handlers_dir_group: admin   # no default
# cl_handlers_dir_dmode: '0775'  # no default
# cl_handlers_main_mode: '0644'  # no default
cl_handlers_delete_all: false
cl_handlers_delete: false
cl_handlers_create: true
cl_handlers_dir_become: false

# Snap
cl_snap_paths:
  - /usr/local/sbin
  - /usr/local/bin
  - /usr/sbin
  - /usr/bin
  - /sbin
  - /bin
# - /snap/bin
cl_snap_patterns:
  - snap

# States
cl_states_unmount: [absent, unmounted]
cl_states_mount: [present, mounted, remounted]
cl_states_file: [absent, directory, file, hard, link, touch]

# Files
cl_files_collections:
  copy: ansible.builtin
  template: ansible.builtin
  markers: ansible.builtin
  create-backup: ansible.builtin
  patch: ansible.posix
  lineinfile: ansible.builtin
  blockinfile: ansible.builtin
  inifile: ansible.builtin
  ucl: vbotka.freebsd
  delete-backup: ansible.builtin
cl_files_order: "{{ cl_files_collections|dict2items|
                    selectattr('value', 'in', ['ansible.builtin'] + cl_collections)|
                    map(attribute='key') }}"

# OS common
install_retries: 10
install_delay: 5

# FreeBSD
freebsd_install_method: packages
# freebsd_install_method: ports
freebsd_use_packages: true
cl_services_freebsd_rcconf_auto: false

# EOF
...

Warning

The defaults of the variables cl_dird_dmode (35), cl_dira_dmode (56) and cl_dira_fmode (57) to access the configuration data and the assembled dictionaries are very permissive. Restrict the permissions if these dictionaries might comprise classified data.

Configuration data

The configuration data describe the creation of handlers, installation of the packages or ports, and management of files and services. See the below sections on how to create the data for the Ansible modules that serve your use-case best. Review hints in the Examples.

Handlers

Synopsis

The dictionary cl_handlers comprises data to create handlers. The structure of the dictionary depends on the template that is used to create the files with the handlers. For example, the structure below can be used together with the template handlers-auto1.yml.j2.

Parameters

Parameter	Type	Comments
template	string required	Template filename
handlers	list required	List of handlers dictionaries
- handler	string required	Name of the handler
- module	string required	Ansible module in handler
- params	list required	Ansible module parameters
- conditions	list	List of conditions

Examples

FreeBSD handlers for Postfix

[contrib/postfix/conf-light/handlers.d/postfix-freebsd.yml]

postfix_freebsd:
  template: handlers-auto1.yml.j2
  handlers:

    - handler: enable and start postfix
      module: service
      params:
        - 'name: postfix'
        - 'state: started'
        - 'enabled: true'

    - handler: disable and stop postfix
      module: service
      params:
        - 'name: postfix'
        - 'state: stopped'
        - 'enabled: false'

    - handler: reload postfix
      module: service
      params:
        - 'name: postfix'
        - 'state: reloaded'
      conditions:
        - '- cl_service_postfix_enable|bool'

    - handler: restart postfix
      module: service
      params:
        - 'name: postfix'
        - 'state: restarted'
      conditions:
        - '- cl_service_postfix_enable|bool'

    - handler: postfix check
      module: command
      params:
        - 'cmd: /usr/local/sbin/postfix check'

    - handler: newaliases
      module: command
      params:
        - 'cmd: /usr/bin/newaliases'

#    - handler: 'postmap smtp sasl passwords'
#      module: command
#      params:
#        - 'cmd: /usr/local/sbin/postmap {{ postfix_main_cf_smtp_sasl_password_maps }}'

#    - handler: 'postmap virtual aliases'
#      module: command
#      params:
#        - cmd: /usr/local/sbin/postmap {{ postfix_virtual }}'

Create the handlers

shell> ansible-playbook pb.yml -t cl_vars -e cl_setup=true

Take a look at the file with the handlers

shell> cat roles/vbotka.config_light/handlers/handlers-auto-postfix_freebsd.yml

---
# Ansible managed
# Automatically generated file with handlers.

- name: postfix_freebsd enable and start postfix
  service:
    name: postfix
    state: started
    enabled: true

- name: postfix_freebsd disable and stop postfix
  service:
    name: postfix
    state: stopped
    enabled: false

- name: postfix_freebsd reload postfix
  service:
    name: postfix
    state: reloaded
  when:
    - cl_service_postfix_enable|bool

- name: postfix_freebsd restart postfix
  service:
    name: postfix
    state: restarted
  when:
    - cl_service_postfix_enable|bool

- name: postfix_freebsd postfix check
  command:
    cmd: /usr/local/sbin/postfix check

- name: postfix_freebsd newaliases
  command:
    cmd: /usr/bin/newaliases

# EOF

The file is imported into the handlers/main.ym

shell> grep handlers-auto-postfix_freebsd.yml roles/vbotka.config_light/handlers/main.yml
- import_tasks: handlers-auto-postfix_freebsd.yml

See also

• the template handlers-auto1.yml.j2

• vars-handlers.yml

• setup.yml

Note

The template handlers-auto1.yml.j2 is available in the role’s directory templates. The user is expected to create new templates when needed. Feel free to change the structure of the data and to create new templates that might fit the purpose better. Feel free to contribute new templates and configuration examples to the project.

Packages

Synopsis

The dictionary cl_packages comprises managed packages (Linux or BSD) or BSD ports.

FreeBSD

By default packages will be installed. If you want to install ports set

freebsd_install_method: ports

snap

By default snap packages won’t be installed or uninstalled if snap binary can’t be found in cl_snap_paths. If you want the role to fail when snap is missing set

cl_snap_missing_fatal: true

The variables cl_snap_missing_fatal, cl_snap_paths, cl_snap_patterns are declared in defaults/main.yml.

Parameters

Parameter	Type	Comments
name	list required	List of packages or BSD ports
module	string	Ansible module to manage packages. choices: package, apt, yum, snap, pkgng (default=package)
state	string	State of packages or BSD ports (default=present)
.	.	<TBD: see tasks/packages.yml>

Examples

FreeBSD install Postfix package or port

[contrib/postfix/conf-light/packages.d/postfix.yml]

postfix:
  module: pkgng
  name:
    - mail/postfix

Armbian package for Simple SMTP

[contrib/ssmtp/conf-light/packages.d/ssmtp.yml]

ssmtp:
  module: pkgng
  name:
    - mail/ssmtp

Ubuntu delete snap packages

[contrib/ubuntu-snap-disable/conf-light/packages.d/snap-deinstall.yml]

snap_deinstall_list1:
  module: snap
  state: absent
  name:
    - chromium
    - core
    - core18
    - gnome-3-28-1804
    - gtk-common-themes
    - simplenote
    - tusk
#   - snapd
#
# msg: Ooops! Snap installation failed while executing 'sh -c "/usr/bin/snap remove chromium core
# core18 gnome-3-28-1804 gtk-common-themes simplenote snapd tusk"', please examine logs and error
# output for more details.
# rc: 1
# stderr: |-
#   error: cannot remove "chromium", "core", "core18", "gnome-3-28-1804",
#          "gtk-common-themes", "simplenote", "snapd", "tusk": snap "snapd" is not
#          removable: remove all other snaps first

Ubuntu purge snapd package

[contrib/ubuntu-snap-disable/conf-light/packages.d/snapd.yml]

snap_deinstall_list2:
  module: apt
  state: absent
  purge: true
  name:
    - snapd

See also

• vars-packages.yml

• packages.yml

States

Synopsis

The dictionary cl_states comprises the states of the managed files. If mounted, the path is unmounted when state is in the list cl_states_unmount (default=absent)

cl_states_unmount: [absent, unmounted]

Then, the module file is applied if state is in the list cl_states_file (default=file)

cl_states_file: [absent, directory, file, hard, link, touch]

In the end, the path is mounted if state is in the list cl_states_mount (default=absent)

cl_states_mount: [present, mounted, remounted]

The variables cl_states_unmount, cl_states_mount, cl_states_file are declared in defaults/main.yml. Details of the parameters are described in the modules mount and file.

Parameters

Parameter	Type	Comments
path	string required	Path to file
state	string	State of the file
owner	string	Owner of the file
group	string	Group of the file
mode	string	Mode of the file
…	…	<TBD: see tasks/states.yml>

Examples

Ownership and permissions of the document root for Lighttpd

[contrib/lighttpd/conf-light/states.d/lighttpd-server-document-root.yml]

lighttpd_server_document_root:
  state: directory
  path: "{{ cl_lighttpd_server_document_root }}"
  owner: "{{ cl_lighttpd_server_username }}"
  group: "{{ cl_lighttpd_server_groupname }}"
  mode: '0750'

Delete snap directories

[contrib/ubuntu-snap-disable/conf-light/states.d/snap.yml]

snap_root:
  path: /snap
  state: absent
snap_var:
  path: /var/snap
  state: absent
snap_lib_var:
  path: /var/lib/snapd
  state: absent

See also

• See shell> ansible-doc -t module mount

• See shell> ansible-doc -t module file

• vars-states.yml

• states.yml

Services

Synopsis

The dictionary cl_services comprises managed services.

Parameters

Parameter	Type	Comments
name	string required	Name of the service
state	string	State of the service default: started
enabled	boolean	Start on boot default: true

Examples

FreeBSD services for Postfix and Sendmail

[contrib/postfix/conf-light/service.d/postfix.yml]

postfix:
  name: postfix
  state: "{{ cl_service_postfix_state }}"
  enabled: "{{ cl_service_postfix_enable }}"

[contrib/postfix/conf-light/service.d/sendmail.yml]

sendmail:
  name: sendmail
  state: "{{ cl_service_sendmail_state }}"
  enabled: "{{ cl_service_sendmail_enable }}"

See also

• vars-services.yml

• services.yml

Files

The variable cl_files is a dictionary of the files that shall be managed by this role. It’s optional which Ansible module will be used to manage a file. More options can be applied at the same file. For example, it is possible to create a file by the Ansible module template and modify it by the module lineinfile later. Several options, listed in the default order, are available

1. copy: If the attribute copyfile is defined in the dictionary

2. template: If the attribute template is defined in the dictionary

3. create blockinfile markers: If the attribute markers is defined in the dictionary

4. patch: If the attribute patch is defined in the dictionary

5. lineinfile: If the attribute dict or lines is defined in the dictionary

6. blockinfile: If the attribute blocks is defined in the dictionary

7. ini_file: If the attribute ini is defined in the dictionary

The variable cl_files_order controls the order of the execution. Multiple options, when present in the dictionary of a file definition, will be applied in this order. In addition to the options, listed above, there are create-backup and delete-backup tasks to backup files that was changed if enabled by cl_backup (default: false). By default, the backup files are created after copy, template, and markers. Fit the order of the execution to your needs.

See also

• vars-files.yml

• files.yml

• files-create-backup.yml

• files-delete-backup.yml

copy

Copy files.

Parameters for copyfile

Parameter		Type	Comments
path		string required	Path to file
copyfile		dict required	copyfile parameters (see tasks/files-copy.yml)
	path	string required	Path of the source file
	remote_src	string	Source file from remote
	force	boolean	If no, transfer if dest does not exist
	…	…	<TBD>
owner		string	Owner of the file
group		string	Group of the file
mode		string	Mode of the file
attributes		string	Attributes of the file
validate		string	Command to validate file
handlers		list	List of handlers

Example of copyfile

Create the description of the file (2) and declare the variable for the dictionary (7)

[contrib/lighttpd_nagios/conf-light/files.d/lighttpd-modulesconf.yml]

lighttpd-modulesconf:
  path: /usr/local/etc/lighttpd/modules.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  copyfile: "{{ cl_lighttpd_modulesconf_copy }}"
  markers: "{{ cl_lighttpd_modulesconf_markers }}"
  lines: "{{ cl_lighttpd_modulesconf_lines }}"
  blocks: "{{ cl_lighttpd_modulesconf_blocks }}"
  handlers:
    - configtest lighttpd
    - reload lighttpd

Create the dictionary cl_lighttpd_modulesconf_copy (69)

[contrib/lighttpd_nagios/cl-lighttpd.yml]

# /usr/local/etc/lighttpd/modules.conf
cl_lighttpd_modulesconf_copy:
  path: /usr/local/etc/lighttpd/modules.conf.sample
  remote_src: true
  force: false

Then, the command

shell> ansible-playbook config-light.yml -t cl_files_copy

will copy sample file modules.conf.sample to modules.conf if the destination does not exist.

See also

• See files-copy.yml at GitHub

• See files-copy.yml annotated source code

template

Create files from templates.

Parameters for template

Parameter		Type	Comments
path		string required	Path to file
template		dict required	Template parameters (see files-templates.yml)
	path	string required	Path of the source file
	force	boolean	If no, transfer if dest does not exist
	…	…	<TBD>
owner		string	Owner of the file
group		string	Group of the file
mode		string	Mode of the file
attributes		string	Attributes of the file
validate		string	Command to validate file
handlers		list	List of handlers

Example of template

File /etc/mail/mailer.conf for postfix

[contrib/postfix/conf-light/files.d/mailer-conf.yml]

mailerconf:
  path: /etc/mail/mailer.conf
  template:
    path: mailer.conf.j2
    force: true
  owner: root
  group: wheel
  mode: '0644'

See also

• See files-template.yml how the files are modified or created by the Ansible module template

• See files-template.yml annotated source code

Note

There are couple of templates ready to be used in the directory templates. The user is expected to create new templates when needed. Feel free to contribute new templates to the project.

blockinfile markers

Create markers for Ansible module blockinfile. Mark existing blocks that you want to configure.

Parameters for blockinfile markers

Parameter		Type	Comments
path		string required	Path to file
markers		list required	List of dictionaries (see fn/mark-block.yml)
	regex1	string required	Regex of block’s beginning
	replace1	string required	Block’s beginning
	regex2	string required	Regex of block’s ending
	replace2	string required	Block’s ending

Example of blockinfile markers

For example, in file /usr/local/etc/lighttpd/modules.conf, create blockinfile markers in the following block

##

server.modules = (
  "mod_access",
  #  "mod_alias",
  #  "mod_auth",
  #  "mod_authn_file",
  #  "mod_evasive",
  #  "mod_setenv",
  #  "mod_usertrack",
  #  "mod_redirect",
  #  "mod_rewrite",
  )

##

Create the description of the file (2) and declare the variable for the list of the markers (8)

[contrib/lighttpd_nagios/conf-light/files.d/lighttpd-modulesconf.yml]

lighttpd-modulesconf:
  path: /usr/local/etc/lighttpd/modules.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  copyfile: "{{ cl_lighttpd_modulesconf_copy }}"
  markers: "{{ cl_lighttpd_modulesconf_markers }}"
  lines: "{{ cl_lighttpd_modulesconf_lines }}"
  blocks: "{{ cl_lighttpd_modulesconf_blocks }}"
  handlers:
    - configtest lighttpd
    - reload lighttpd

Create the list of the dictionaries cl_lighttpd_modulesconf_markers (73)

[contrib/lighttpd_nagios/cl-lighttpd.yml]

# /usr/local/etc/lighttpd/modules.conf
cl_lighttpd_modulesconf_copy:
  path: /usr/local/etc/lighttpd/modules.conf.sample
  remote_src: true
  force: false
cl_lighttpd_modulesconf_markers:
  - marker: server.modules
    regex1: 'server.modules\s*=\s*\('
    replace1: 'server.modules = ('
    regex2: '\)'
    replace2: ')'

Then, the command

shell> ansible-playbook config-light.yml -t cl_files_copy,cl_files_markers

will copy sample file modules.conf.sample to modules.conf and will create blockinfile markers

##

# BEGIN ANSIBLE MANAGED BLOCK server.modules
server.modules = (
  "mod_access",
#  "mod_alias",
#  "mod_auth",
#  "mod_authn_file",
#  "mod_evasive",
#  "mod_setenv",
#  "mod_usertrack",
#  "mod_redirect",
#  "mod_rewrite",

)
# END ANSIBLE MANAGED BLOCK server.modules

##

See also

• files-markers.yml

• mark-block.yml

patch

Patch files.

Parameters for patch

Parameter		Type	Comments
path		string required	Path to file to be patched
patch		dict required	Parameters of patch module (see files-patch.yml)
	src	string required	Path of the patch file
	basedir	path	Apply patch in this dir
	…	…	<TBD>
handlers		list	List of handlers

Example of patch

File /etc/network.subr for /etc/rc.d/wpa_cli

[contrib/freebsd-custom-image-wpacli/conf-light/files.d/network_subr.yml]

network_subr:
  path: "{{ bsd_cimage_mount_path }}/etc/network.subr"
  patch:
    src: "{{ playbook_dir }}/files/network.subr.patch"
    basedir: "{{ bsd_cimage_mount_path }}/etc"

See also

• See files-patch.yml annotated source code

• See details about the example in the role vbotka.freebsd_wpa_cli

lineinfile

Create or configure lines in a file.

Parameters for lineinfile

Parameter		Type	Comments
path		string required	Path to file
lines		list required	lineinfile params. Either dict or lines is required.
	regexp	string required	Regular expression
	line	string required	Line
	backrefs
	state
	firstmatch
	insertafter
	insertbefore
	…	…	<TBD>
assignment		string	Assignment of key and value in dict
dict		list required	lineinfile params. Either dict or lines is required. (see files-lineinfile.yml)
	key	string required	Key value for regexp
	value	string required	Value for line
	firstmatch
	insertafter
	insertbefore
	…	…	<TBD>
owner		string	Owner of the file
group		string	Group of the file
mode		string	Mode of the file
attributes		string	Attributes of the file
other		string	Attributes of module file
create		boolean	Create file
validate		string	Command to validate file
handlers		list	List of handlers

Example of lineinfile with lines

File /usr/local/etc/dma/dma.conf for DragonFly Mail Agent

[contrib/dma/conf-light/files.d/dma-dmaconf.yml]

dma_dmaconf:
  path: /usr/local/etc/dma/dma.conf
  create: true
  owner: root
  group: mail
  mode: '0644'
  lines: "{{ cl_dma_dmaconf_lines }}"

[contrib/dma/host_vars/srv.example.com/config-light-dma.yml]

cl_dma_dmaconf_lines:
    - {regexp: '^SMARTHOST\s*(.*)$', line: 'SMARTHOST {{ cl_dma_smarthost }}'}
    - {regexp: '^PORT\s*(.*)$', line: 'PORT {{ cl_dma_port }}'}
    - {regexp: '^AUTHPATH\s*(.*)$', line: 'AUTHPATH {{ cl_dma_authpath }}'}
    - {regexp: '^ALIASES\s*(.*)$', line: 'ALIASES {{ cl_dma_aliasespath }}'}
    - {regexp: '^SECURETRANSFER\s*(.*)$', line: 'SECURETRANSFER'}
    - {regexp: '^STARTTLS\s*(.*)$', line: 'STARTTLS'}
    - {regexp: '^MASQUERADE\s*(.*)$', line: 'MASQUERADE {{ cl_dma_masquerade }}'}

Example of lineinfile with dict

File /usr/local/etc/lighttpd/lighttpd.conf for lighttpd

[contrib/lighttpd/conf-light/files.d/lighttpd-lighttpdconf.yml]

lighttpd-lighttpdconf:
  path: /usr/local/etc/lighttpd/lighttpd.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  assignment: ' = '
  dict: "{{ cl_lighttpd_lighttpdconf_dict }}"
  handlers:
    - reload lighttpd

[contrib/lighttpd/host_vars/srv.example.com/cl-lighttpd.yml]

cl_lighttpd_lighttpdconf_dict:
  - {key: server.port, value: '"{{ cl_lighttpd_server_port }}"'}
  - {key: server.use-ipv6, value: '"{{ cl_lighttpd_server_useipv6 }}"'}
  - {key: server.username, value: '"{{ cl_lighttpd_server_username }}"'}
  - {key: server.groupname, value: '"{{ cl_lighttpd_server_groupname }}"'}
  - {key: server.document-root, value: '"{{ cl_lighttpd_server_document_root }}"'}

See also

• See files-lineinfile.yml at GitHub how the files are modified or created by the Ansible module lineinfile

• See files-lineinfile.yml annotated source code

blockinfile

Create or configure blocks in files.

Parameters for blockinfile

Parameter		Type	Comments
path		string required	Path to file
blocks		list required	List of dictionaries (see files-blockinfile.yml)
	marker	string required	Label of the marker
	block	string required	Text between markers
	…	…	<TBD>
owner		string	Owner of the file
group		string	Group of the file
mode		string	Mode of the file
create		boolean	Create if does not exist
validate		string	Command to validate file
handlers		list	List of handlers

Example of blockinfileinfile

Create the description of the file (2) and declare the list of the blocks (10)

[contrib/lighttpd_nagios/conf-light/files.d/lighttpd-modulesconf.yml]

lighttpd-modulesconf:
  path: /usr/local/etc/lighttpd/modules.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  copyfile: "{{ cl_lighttpd_modulesconf_copy }}"
  markers: "{{ cl_lighttpd_modulesconf_markers }}"
  lines: "{{ cl_lighttpd_modulesconf_lines }}"
  blocks: "{{ cl_lighttpd_modulesconf_blocks }}"
  handlers:
    - configtest lighttpd
    - reload lighttpd

Create the list of the blocks cl_lighttpd_modulesconf_blocks (89)

[contrib/lighttpd_nagios/cl-lighttpd.yml]

cl_lighttpd_modulesconf_server_modules:
  - mod_access
  - mod_alias
  - mod_auth
  - mod_setenv
cl_lighttpd_modulesconf_blocks:
  - marker: server.modules
    block: |
      server.modules = (
      {% for module in cl_lighttpd_modulesconf_server_modules %}
        "{{ module }}",
      {% endfor %}
      )

Then, the command

shell> ansible-playbook config-light.yml -t cl_files_blockinfile

will create this block in modules.conf

##

# BEGIN ANSIBLE MANAGED BLOCK server.modules
server.modules = (
  "mod_access",
  "mod_alias",
  "mod_auth",
  "mod_setenv",
)
# END ANSIBLE MANAGED BLOCK server.modules

##

See also

• See files-blockinfile.yml annotated source code

ini_file

Create or configure ini entries in a file.

Parameters for ini_file

Parameter		Type	Comments
path		string required	Path to file
ini		list required	ini_file parameters list of dictionaries (see files-inifile.yml)
	section	string required	Section name in INI file
	option	string	Name of the option
	value	string	Value of the option
	state	string	If absent the option or section will be removed
	allow_no_value	boolean	Allow option without value
	no_extra_spaces	boolean	Do not insert spaces
	…	…	<TBD>
owner		string	Owner of the file
group		string	Group of the file
mode		string	Mode of the file
attributes		string	Attributes of the file
create		boolean	Create file
handlers		list	List of handlers

Example of ini_file

<TODO: No example yet>

See also

• See files-inifile.yml annotated source code

• community.general ini_file.py

Note

Quoting Multiple options with the same name exist #273 “There is no “The INI format”, there are many different interpretations out there what valid INI formats should be …”

Best practice

Check syntax

Check syntax of the playbook

shell> ansible-playbook pb.yml --syntax-check

Validation

Install yamllint to use the default validation of the created handlers and assembled data. See the variables cl_assemble_validate and cl_handlers_validate in defaults/main.yml. Optionally, use other linter, for example, ansible-lint and change the variables. You can disable the validation by clearing the variables

cl_assemble_validate: ''
cl_handlers_validate: ''

Setup

Assemble data, create handlers, check sanity, and display variables. When you take a look at tasks/main.yml you’ll see that the first three groups of the tasks (setup, vars, and sanity) are tagged always. As a result, when you apply the tag cl_debug all three groups of the tasks will be executed before cl_debug

shell> ansible-playbook pb.yml -t cl_debug -e cl_setup=true -e cl_sanity=true -e cl_debug=true

Manage packages

Dry-run the management of packages

shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true -CD

Manage packages

shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true

Then disable the installation cl_install=false to speedup the playbook.

Manage states of files

Dry-run the management of files’ states

shell> ansible-playbook pb.yml -t cl_states -CD

Set the states (existence and attributes) of the files

shell> ansible-playbook pb.yml -t cl_states

Manage configuration files

Dry-run the configuration of files

shell> ansible-playbook pb.yml -t cl_files -CD

Create and modify files

shell> ansible-playbook pb.yml -t cl_files

Manage services

Dry-run the configuration of services

shell> ansible-playbook pb.yml -t cl_services -CD

Configure services

shell> ansible-playbook pb.yml -t cl_services

Hint

If you know what you are doing skip the above selection of particular tags and run the complete role at once

shell> ansible-playbook pb.yml -e cl_setup=true -e cl_install=true

Idempotency

The role and the configuration data in the examples are idempotent. When the application is installed and configured there should be no changes reported by ansible-playbook when running the playbook repeatedly. Disable setup, sanity, debug, and install to speedup the execution when running the playbook periodically to audit the configuration

shell> ansible-playbook pb.yml -e cl_setup=false \
                               -e cl_sanity=false \
                               -e cl_debug=false \
                               -e cl_install=false