Handlers

Synopsis

The dictionary cl_handlers comprises data to create handlers. The structure of the dictionary depends on the template that creates 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

- listen

string

Topic to listen to

- module

string required

Ansible module in handler

- params

list required

Ansible module parameters

- conditions

list

List of conditions

Version control

The role is distributed with no handlers and empty file handlers/main.yml

---
# handlers

It’s up to you whether you include the changed main.yml and created handlers in the version control. In git, run the below command to ignore changes in main.yml

shell> git update-index --assume-unchanged handlers/main.yml

To ignore the created handlers put into the .gitignore

handlers/*.yml

Examples

FreeBSD handlers for Postfix

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

 1---
 2postfix_freebsd:
 3  template: handlers-auto1.yml.j2
 4  handlers:
 5    - handler: Start postfix
 6      listen: start postfix
 7      module: vbotka.freebsd.service
 8      params:
 9        - "script: postfix"
10        - "command: start"
11
12    - handler: Stop postfix
13      listen: stop postfix
14      module: vbotka.freebsd.service
15      params:
16        - "script: postfix"
17        - "command: stop"
18
19    - handler: Reload postfix
20      listen: reload postfix
21      module: vbotka.freebsd.service
22      params:
23        - "script: postfix"
24        - "command: reload"
25      conditions:
26        - "- cl_service_postfix_enable | bool"
27
28    - handler: Restart postfix
29      listen: restart postfix
30      module: vbotka.freebsd.service
31      params:
32        - "script: postfix"
33        - "command: restart"
34      conditions:
35        - "- cl_service_postfix_enable | bool"
36
37    - handler: Postfix check
38      listen: postfix check
39      module: command
40      params:
41        - "cmd: /usr/local/sbin/postfix check"
42
43    - handler: Newaliases
44      listen: newaliases
45      module: command
46      params:
47        - "cmd: /usr/bin/newaliases"
48
49#    - handler: 'postmap smtp sasl passwords'
50#      module: command
51#      params:
52#        - 'cmd: /usr/local/sbin/postmap {{ postfix_main_cf_smtp_sasl_password_maps }}'
53
54#    - handler: 'postmap virtual aliases'
55#      module: command
56#      params:
57#        - cmd: /usr/local/sbin/postmap {{ postfix_virtual }}'

Create the handlers

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

Look at the file with the handlers

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

 1---
 2# Ansible managed
 3# Automatically generated file with handlers.
 4
 5- name: postfix_freebsd enable and start postfix
 6  service:
 7    name: postfix
 8    state: started
 9    enabled: true
10
11- name: postfix_freebsd disable and stop postfix
12  service:
13    name: postfix
14    state: stopped
15    enabled: false
16
17- name: postfix_freebsd reload postfix
18  service:
19    name: postfix
20    state: reloaded
21  when:
22    - cl_service_postfix_enable|bool
23
24- name: postfix_freebsd restart postfix
25  service:
26    name: postfix
27    state: restarted
28  when:
29    - cl_service_postfix_enable|bool
30
31- name: postfix_freebsd postfix check
32  command:
33    cmd: /usr/local/sbin/postfix check
34
35- name: postfix_freebsd newaliases
36  command:
37    cmd: /usr/bin/newaliases
38
39# 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 # noqa: name[missing]

There is no name in the import_tasks task. The comment # noqa: name[missing] prevents ansible-lint from complaining about the missing name.

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 create new templates that might fit the purpose better. Feel free to contribute new templates and configuration examples to the project.

See also