User’s guide

Introduction

The goal of this configuration is to start dhclient and other system services (e.g. routing, ntpdate, ntpd, …) after the wifi interface connects to the network. The utility wpa_cli, running in the background, will be notified by wpa_supplicant when the interface connects or disconnects to/from the network. On such event wpa_cli executes the action file (-a action_file). See templates what pre-configured scripts are available. For example, wpa_action-1.1.0.sh, after the connection, starts dhclient, restarts routing, and optionally synchronizes date and time. This solves the potential problem of synchronizing date and time by settimeofday at boot time of a wireless-only system. If wpa_supplicant doesn’t manage to connect to the network by the time ntpdate is executed ntpdate will time-out. Then, in most systems, the ntpd service will start (see rcorder /etc/rc.d/*). When the hardware device has no battery and no RTC, the offset might be huge. In this case ntpd will reject the offset and will terminate itself, believing something very strange must have happened.

• Ansible role: wpa_cli

• Supported systems: FreeBSD

• Requirements: None

Warning

The role modifies scripts in /etc/rc.d

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.freebsd_wpa_cli

and install it

shell> ansible-galaxy role install vbotka.freebsd_wpa_cli

Install the collections community.general and ansible.posix

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

See also

• See freebsd_postinstall

• See wpasupplicant.yml how to configure wpa_supplicant by Ansible

• To install specific versions from various sources see Installing content.

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

Playbook

Create simple playbook that calls the role (10) at a single host srv.example.com (2)

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

See also

• For details see Connection Plugins (4-5)

• See also Understanding Privilege Escalation (6-8)

Debug

Some tasks will display additional information when the variable wpacli_debug is enabled. Enable debug output either in the configuration

wpacli_debug: true

, or set the extra variable in the command

shell> ansible-playbook playbook.yml -e wpacli_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

Tags

The tags provide the user with a very useful tool to run selected tasks of the role. To see what tags are available list the tags of the role with the command

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

playbook: playbook.yml

play #1 (srv.example.com): srv.example.com TAGS: [] TASK TAGS:
   [always, wpacli_action_script, wpacli_assert, wpacli_debug,
   wpacli_packages, wpacli_pid_dir, wpacli_rc,
   wpacli_rc_defaults_patch, wpacli_rc_networksubr_patch,
   wpacli_rc_script, wpacli_rcconf, wpacli_wpa_cli]

Examples

• Display the list of the variables and their values with the tag wpacli_debug (when the debug is enabled wpacli_debug: true)

 shell> ansible-playbook playbook.yml -t wpacli_debug

• See what packages will be installed

 shell> ansible-playbook playbook.yml -t wpacli_packages --check

• Install packages and exit the play

 shell> ansible-playbook playbook.yml -t wpacli_packages

Tasks

<TODO>

See also

• Source code main.yml

Development and testing

In order to deliver an Ansible project it’s necessary to test the code and configuration. The tags provide the administrators with a tool to test single tasks’ files and single tasks. For example, to test a single task at a single remote host test_01, create the playbook

shell> cat playbook.yml
- hosts: test_01
  become: true
  roles:
    - vbotka.freebsd_wpa_cli

Customize configuration in host_vars/test_01/wpa-cli.yml and check the syntax

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

Then dry-run the selected task and see what will be changed. Replace <tag> with valid tag or with a comma-separated list of tags

shell> ansible-playbook playbook.yml -t <tag> --check --diff

When all seems to be ready run the command. Run the command twice and make sure the playbook and the configuration is idempotent

shell> ansible-playbook playbook.yml

wpa-cli.yml

Synopsis

Create wpa_cli action file (default /root/bin/wpa_action.sh)

<TODO>

See also

• Annotated Source code wpa-cli.yml

• See wpa_supplicant README

rc.yml

Synopsis

Configuration of /etc/rc.d

<TODO>

See also

• Annotated Source code rc.yml

• See Practical rc.d scripting in BSD

rc.conf.patch

--- rc.conf.orig	2019-01-06 23:53:26.848957000 +0100
+++ rc.conf	2019-01-06 23:55:58.354651000 +0100
@@ -133,6 +133,9 @@
 wpa_supplicant_program="/usr/sbin/wpa_supplicant"
 wpa_supplicant_flags="-s"	# Extra flags to pass to wpa_supplicant
 wpa_supplicant_conf_file="/etc/wpa_supplicant.conf"
+wpa_cli_program="/usr/sbin/wpa_cli"
+wpa_cli_ctrl_interface="/var/run/wpa_supplicant"
+wpa_cli_action_file="/root/bin/wpa_action.sh"
 #
 firewall_enable="NO"		# Set to YES to enable firewall functionality
 firewall_script="/etc/rc.firewall" # Which script to run to set up the firewall

network.subr.patch

--- network.subr.orig	2019-01-06 23:13:49.382184000 +0100
+++ network.subr	2019-01-06 23:13:43.162190000 +0100
@@ -222,6 +222,7 @@
 	if wpaif $1; then
 		/etc/rc.d/wpa_supplicant start $1
 		_cfg=0		# XXX: not sure this should count
+		/etc/rc.d/wpa_cli start $1
 	elif hostapif $1; then
 		/etc/rc.d/hostapd start $1
 		_cfg=0
@@ -252,6 +253,7 @@
 	_cfg=1
 
 	if wpaif $1; then
+		/etc/rc.d/wpa_cli stop $1
 		/etc/rc.d/wpa_supplicant stop $1
 		_cfg=0
 	elif hostapif $1; then

Variables

See also

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

Default variables

The default variables are stored in the file defaults/main.yml. These variables can be customized in the file vars/main.yml. The file vars/main.yml will be preserved by the update of the role.

Warning

• Don’t make any changes to the file defaults/main.yml. The changes will be overwritten by the update of the role. Customize the default values in the file vars/main.yml.

See also

• The examples of the customization vars/main.yml.sample

[defaults/main.yml]

---
# defaults for vbotka.freebsd_wpa_cli
wpacli_role_version: 2.6.3

# Install wpacli_packages
wpacli_install: true

# Enable wpa_cli in rc.conf
# (It's a string used in rc.conf. It's not a boolean type.
# Options are "YES" or "NO" uppercase mandatory.
wpacli_enable: "YES"

# Enable test of supported OS versions listed in wpacli_versions_tested
wpacli_assert_enable: true

# Enable debug output
wpacli_debug: false

# Create backups of modified files
wpacli_backup_conf: false

# List of supported OS versions
wpacli_versions_tested: "{{ wpacli_versions_tested_rel | flatten }}"
wpacli_versions_tested_rel:
  - ["11.3", "11.4"]
  - ["12.1", "12.2", "12.3", "12.4"]
  - ["13.0", "13.1", "13.2", "13.3"]
  - ["14.0", "14.1"]

# Installation method.
# Options are "packages" for binary packages or "ports"
freebsd_install_method: packages

# If installation method is "ports" use binary packages if
# available
freebsd_use_packages: true

# Number of times an unsuccessful installation is retried
freebsd_install_retries: 10

# Delay in seconds an unsuccessful installation is retried
freebsd_install_delay: 5

# Path to wpa_cli.
# '/usr/sbin/wpa_cli' is included in the base system. Change to
# '/usr/local/sbin/wpa_cli' to use the binaries installed by
# security/wpa_supplicant.
# Change together with the path to wpa_supplicant. Optionaly use
# vbotka.freebsd_postinstall to accomplish this.
#   - include_role:
#       name: vbotka.freebsd_postinstall
#       tasks_from: wpasupplicant.yml
wpacli_program: /usr/sbin/wpa_cli

# Install packages
wpacli_packages:
  - security/wpa_supplicant

# wpa_cli PID
wpacli_pid_dir: /var/run/wpa_cli
wpacli_pid_dir_owner: root
wpacli_pid_dir_group: wheel
wpacli_pid_dir_mode: "0750"

# Create wpa_cli action script
wpacli_action_script: false
# Path to the action script
wpacli_action_script_dir: /root/bin
wpacli_action_script_dir_owner: root
wpacli_action_script_dir_group: wheel
wpacli_action_script_dir_mode: "0755"
# Filename of the action script
wpacli_action_script_file: wpa_action.sh
# Ownership and permissions of the action script
wpacli_action_script_owner: root
wpacli_action_script_group: wheel
wpacli_action_script_mode: "0750"
# Action script template
wpacli_action_script_template: wpa_action-1.0.0.sh.j2
# Paramters used in the template
wpacli_action_script_log_to_file: false
wpacli_action_script_logfile: /tmp/wpa_action.$ifname
wpacli_action_script_ntp_set: false
wpacli_action_script_ntp_server: "0.pool.ntp.org"
wpacli_action_script_ntpdate_flags: -b

# Parameters in /etc/rc.conf
wpacli_ctrl_interface: /var/run/wpa_supplicant
wpacli_rcconf:
  - { key: wpa_cli_enable, val: "{{ wpacli_enable }}" }
  - { key: wpa_cli_program, val: "{{ wpacli_program }}" }
  - { key: wpa_cli_ctrl_interface, val: "{{ wpacli_ctrl_interface }}" }
  - { key: wpa_cli_action_file, val: "{{ wpacli_action_script_dir }}/{{ wpacli_action_script_file }}" }

# See role: vbotka.freebsd_postinstall task: wpasupplicant.yml
# fp_wpasupplicant_conf_ctrl_interface: "/var/run/wpa_supplicant"

# EOF

Best practice

Test syntax

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

See what variables will be used

shell> ansible-playbook playbook.yml -t wpacli_debug -e wpacli_debug=true

Dry-run, display differences and display variables

shell> ansible-playbook playbook.yml -e wpacli_debug=true --check --diff

Install packages

shell> ansible-playbook playbook.yml -t wpacli_packages -e wpacli_install=true

Run the playbook

shell> ansible-playbook playbook.yml

Test the idem-potency. The role and the configuration data shall be idempotent. Once the installation and configuration have passed there should be no changes reported by ansible-playbook when running the playbook repeatedly. Disable debug, and install to speedup the playbook and run the playbook again.

 shell> ansible-playbook playbook.yml