Quick start guide
For users who want to try the role quickly, this guide provides an example on how to install and configure lighttpd on single FreeBSD host. The procedure is generic and can be easily modified to install and configure other applications on other systems. See examples in the directory contrib. The control node of this example is Linux and the user running the playbook on the controller is a member of the group adm.
Install the role
vbotka.config_light
shell> ansible-galaxy role install vbotka.config_light
Install the collections 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, use ansible-lint or disable the validation by clearing the variablescl_assemble_validate: '' cl_handlers_validate: ''
Create the playbook
pb.yml
for single host srv.example.com (2) and the role vbotka.config_light (11)
1shell> cat pb.yml
2- hosts: srv.example.com
3 gather_facts: true
4 connection: ssh
5 remote_user: admin
6 become: true
7 become_user: root
8 become_method: sudo
9
10 roles:
11 - vbotka.config_light
Create files in
host_vars
with customized variables of the role (2) and with the variables of the application (3)
1shell> ls -1 host_vars/srv.example.com/cl-*
2host_vars/srv.example.com/cl-common.yml
3host_vars/srv.example.com/cl-lighttpd.yml
Configure the role. To speedup the execution set the control-flow variables (2-5) to false and disable some steps. Enable these steps selectively when needed. The configuration data will be stored in the directory conf-light (10) in the current directory of the playbook. Set the ownership and permissions of the directories on the control node so that the user who is running the playbook will be able both read and write the files, and create the directories (7-9) (11-14).
1shell> cat host_vars/srv.example.com/cl-common.yml
2cl_sanity: false
3cl_setup: false
4cl_install: false
5cl_debug: false
6cl_backup: true
7cl_dird_owner: root
8cl_dird_group: adm
9cl_dird_dmode: '0770'
10cl_dird: "{{ playbook_dir }}/conf-light"
11cl_dira_owner: root
12cl_dira_group: adm
13cl_dira_dmode: '0770'
14cl_dira_fmode: '0660'
Note
The configuration data will be assembled into the directory cl_dira
The default value of cl_dira is {{ cl_dird }}/assemble
Configure the application. Start the server (2), run the server at boot (3), and configure two files (5,18).
1shell> cat host_vars/srv.example.com/cl-lighttpd.yml
2cl_service_lighttpd_enable: true
3cl_service_lighttpd_state: started
4
5# /usr/local/etc/lighttpd/lighttpd.conf
6cl_lighttpd_server_port: '80'
7cl_lighttpd_server_useipv6: disable
8cl_lighttpd_server_username: www
9cl_lighttpd_server_groupname: www
10cl_lighttpd_server_document_root: /usr/local/www/lighttpd
11cl_lighttpd_lighttpdconf_dict:
12 - {key: server.port, value: '"{{ cl_lighttpd_server_port }}"'}
13 - {key: server.use-ipv6, value: '"{{ cl_lighttpd_server_useipv6 }}"'}
14 - {key: server.username, value: '"{{ cl_lighttpd_server_username }}"'}
15 - {key: server.groupname, value: '"{{ cl_lighttpd_server_groupname }}"'}
16 - {key: server.document-root, value: '"{{ cl_lighttpd_server_document_root }}"'}
17
18# /etc/rc.conf
19cl_lighttpd_rcconf_lighttpd_enable: 'YES'
20cl_lighttpd_rcconf_dict:
21 - {key: lighttpd_enable, value: '"{{ cl_lighttpd_rcconf_lighttpd_enable }}"'}
Create configuration data in the directory
conf-light
1shell> tree conf-light
2conf-light/
3├── files.d
4│ ├── lighttpd-lighttpdconf.yml
5│ └── lighttpd-rcconf.yml
6├── handlers.d
7│ └── lighttpd-freebsd.yml
8├── packages.d
9│ └── lighttpd.yml
10├── services.d
11│ └── lighttpd.yml
12└── states.d
13 └── lighttpd-server-document-root.yml
conf-light/files.d/*
1shell> cat conf-light/files.d/lighttpd-lighttpdconf.yml
2lighttpd-lighttpdconf:
3 path: /usr/local/etc/lighttpd/lighttpd.conf
4 create: true
5 owner: root
6 group: wheel
7 mode: '0644'
8 assignment: ' = '
9 dict: "{{ cl_lighttpd_lighttpdconf_dict }}"
10 handlers:
11 - reload lighttpd
1shell> cat conf-light/files.d/lighttpd-rcconf.yml
2lighttpd_rcconf:
3 path: /etc/rc.conf
4 create: true
5 owner: root
6 group: wheel
7 mode: '0644'
8 assignment: '='
9 dict: "{{ cl_lighttpd_rcconf_dict }}"
10 handlers:
11 - reload lighttpd
conf-light/handlers.d/*
1shell> cat conf-light/handlers.d/lighttpd-freebsd.yml
2lighttpd_freebsd:
3
4 template: handlers-auto2.yml.j2
5 handlers:
6
7 - handler: enable and start lighttpd
8 module: service
9 params:
10 - 'name: lighttpd'
11 - 'state: started'
12 - 'enabled: true'
13
14 - handler: disable and stop lighttpd
15 module: service
16 params:
17 - 'name: lighttpd'
18 - 'state: stopped'
19 - 'enabled: false'
20
21 - handler: reload lighttpd
22 module: service
23 params:
24 - 'name: lighttpd'
25 - 'state: reloaded'
26 conditions:
27 - '- cl_service_lighttpd_enable|bool'
28
29 - handler: restart lighttpd
30 module: service
31 params:
32 - 'name: lighttpd'
33 - 'state: restarted'
34 conditions:
35 - '- cl_service_lighttpd_enable|bool'
36
37 - handler: lighttpd check
38 module: command
39 params:
40 - 'cmd: /usr/local/sbin/lighttpd -t'
conf-light/packages.d/*
1shell> cat conf-light/packages.d/lighttpd.yml
2lighttpd:
3 module: pkgng
4 name:
5 - www/lighttpd
conf-light/services.d/*
1shell> cat conf-light/services.d/lighttpd.yml
2lighttpd:
3 name: lighttpd
4 state: "{{ cl_service_lighttpd_state }}"
5 enabled: "{{ cl_service_lighttpd_enable }}"
conf-light/states.d/*
1shell> cat conf-light/states.d/lighttpd-server-document-root.yml
2lighttpd_server_document_root:
3 state: directory
4 path: "{{ cl_lighttpd_server_document_root }}"
5 owner: "{{ cl_lighttpd_server_username }}"
6 group: "{{ cl_lighttpd_server_groupname }}"
7 mode: '0750'
Enable setup and assemble configuration data. This command will assemble the configuration data and create handlers on the control node. Take a look at the directory
conf-light/assemble/
what files were created. Also take a look at the directoryroles/vbotka.config_light/handlers
what handlers were created.shell> ansible-playbook pb.yml -t cl_vars -e cl_setup=true
Note
The tasks setup, vars, and sanity are tagged
always
The tasks setup and sanity are enabled by default (cl_setup: true, cl_sanity: true)
Enable and test sanity
shell> ansible-playbook pb.yml -t cl_sanity -e cl_sanity=true
Display variables
shell> ansible-playbook pb.yml -t cl_debug -e cl_debug=true
Install packages
shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true
Set states of the files
shell> ansible-playbook pb.yml -t cl_states
Create and modify files
shell> ansible-playbook pb.yml -t cl_files
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
Note
The role and the configuration data in the examples are idempotent. Once the application is installed and configured ansible-playbook shouldn’t report any changes. To speedup the playbook disable setup, sanity, debug, and install. This way, the role will audit the required infrastructure
shell> ansible-playbook pb.yml [...] PLAY RECAP *************************************************************************** srv.example.com: ok=29 changed=0 unreachable=0 failed=0 skipped=88 rescued=0 ignored=0
Create file
/usr/local/www/lighttpd/index.html
1shell> ll /usr/local/www/lighttpd/index.html
2-rw-r--r-- 1 www www 51 Apr 12 18:58 /usr/local/www/lighttpd/index.html
3shell> cat /usr/local/www/lighttpd/index.html
4<html><body><h1>Lighttpd works!</h1></body></html>
Open the page in a browser
http://srv.example.com/
. The content should beLighttpd works!