Quick start guide

For the users who want to try the role quickly, this guide provides an example of how to configure wireless network in already downloaded image. Three files will be customized in the image

/boot/loader.conf

# bsd_cimage_loaderconf_data
hw.usb.template=3
umodem_load="YES"
boot_multicons="YES"
boot_serial="YES"
beastie_disable="YES"
loader_color="NO"
legal.realtek.license_ack=1

# bsd_cimage_loaderconf_sysctl

# bsd_cimage_loaderconf_modules
wlan_load="YES"
wlan_wep_load="YES"
wlan_ccmp_load="YES"
wlan_tkip_load="YES"
wlan_amrr_load="YES"
rtwn_load="YES"
if_rtwn_usb_load="YES"

/etc/rc.conf

wlans_rtwn0="wlan0"
ifconfig_wlan0="WPA SYNCDHCP"

/etc/wpa_supplicant.conf

network={
        ssid="my_access_point"
        psk="my_password"
        disabled=0
        }

After the configuration of the files is ready dump the image to a disk and boot the system. The wireless adapter should automatically connect to the network and obtain DHCP address. It should be possible to connect to the system ssh freebsd@<ip-address> (default passwords of FreeBSD images are freebsd: freebsd and root: root).

The wireless adapter in this example is USB Realtek RTL8188EU (idVendor = 0x0bda idProduct = 0x8179)

rtwn0: <Realtek 802.11n NIC, class 0/0, rev 2.00/0.00, addr 4> on usbus1
rtwn0: MAC/BB RTL8188EU, RF 6052 1T1R

See also

Follow the steps below

Install the role vbotka.freebsd_custom_image

shell> ansible-galaxy role install vbotka.freebsd_custom_image

Install the library vbotka.ansible_lib

shell> ansible-galaxy role install vbotka.ansible_lib

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

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

Create the playbook pb-wifi-basic.yml for single host images.example.com (2). Configure connection (4-5) and privilege escalation (6-8). Configure the path (16) to the image (17) and make sure the image is writable by root. The default system partition is s2a (19). Configure the mount-point(s) (21) and configure which partition will be customized (22). The mount-point doesn’t have to exist and will be create (and later deleted when unmounted) by the Ansible module mount. Review the modules (26) and loader’s configuration (28,35). Fit it to your needs if you use a different adapter. hange also configuration of rc.conf (41-42) if necessary. Change SSID (50) and password (51) of the access point. Enable symbolic link of /etc/wpa_supplicant.conf to /etc/wpa_supplicant.conf.wlan0 (53,54).

[contrib/playbook/pb-wifi-basic.yml]

- name: Download, mount, and configure wireless network in the system image
  hosts: images.example.com

  connection: ssh
  remote_user: admin
  become: true
  become_user: root
  become_method: ansible.builtin.sudo

  vars:
    bsd_cimage_sanity: false
    bsd_cimage_install: false
    bsd_cimage_debug: true
    bsd_cimage_debug_classified: true

    bsd_cimage_mount_dir: /export/images/FreeBSD/live
    bsd_cimage_mount_file: FreeBSD-13.3-RELEASE-arm-armv6-RPI-B.img
    bsd_cimage_mount_points:
      - partition: s2a
        fstype: ufs
        mountpoint: /mnt3
    bsd_cimage_mount_path: /mnt3

    bsd_cimage_loaderconf: true
    bsd_cimage_loaderconf_backup: true
    bsd_cimage_loaderconf_modules: [wlan, wlan_wep, wlan_ccmp, wlan_tkip, wlan_amrr, rtwn, if_rtwn_usb]
    bsd_cimage_loaderconf_data:
      - hw.usb.template=3
      - umodem_load="YES"
      - boot_multicons="YES"
      - boot_serial="YES"
      - beastie_disable="YES"
      - loader_color="NO"
      - legal.realtek.license_ack=1
    bsd_cimage_loaderconf_sysctl: []
    bsd_cimage_rcconf: true
    bsd_cimage_rcconf_backup: true
    bsd_cimage_rcconf_data:
      - { key: wlans_rtwn0, value: '"wlan0"' }
      - { key: ifconfig_wlan0, value: '"WPA SYNCDHCP"' }

    bsd_cimage_wpasupconf: true
    bsd_cimage_wpasupconf_backup: true
    bsd_cimage_wpasupconf_data:
      - dev: wlan0
        network:
          - conf:
              - { key: ssid, value: '"my_access_point"' }
              - { key: psk, value: '"my_password"' }
              - { key: disabled, value: "0" }
    bsd_cimage_wpasupconf_link: true
    bsd_cimage_wpasupconf_link_dev: wlan0

  roles:
    - vbotka.freebsd_custom_image

Create the inventory. Change the IP adress (2) and fit the paths to Python (8) and Perl (9) if necessary

 shell> cat hosts
 images.example.com ansible_host=<ip-address>

 [images]
 images.example.com

 [images:vars]
 ansible_python_interpreter=/usr/local/bin/python3.9
 ansible_perl_interpreter=/usr/local/bin/perl

Test syntax

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

See what variables will be included

shell> ansible-playbook pb-wifi-basic.yml -t bsd_cimage_debug -e bsd_cimage_debug=true

Run the playbook

shell> ansible-playbook pb-wifi-basic.yml

Note

By default, the role is not idempotent. At least 4 tasks will be reported changed: 1) Create memory disk 2) Mount mdX partitions 3) Unmount mount points 4) Detach memory disk.
Setting bsd_cimage_umount=false will keep the memory disk attached and partitions mounted. This will make the role idempotent.
The role doesn’t support check and diff --check --diff

Warning

Password of the access-point will be displayed. Set classified debug to false bsd_cimage_debug_classified=false to prevent it.
The image has not been secured by this playbook and should be used for testing only.

Make sure the partition is unmounted and write the customized image to a disk. For example

dd if=FreeBSD-13.0-CURRENT-arm-armv6-RPI-B-20201231-282381aa53a-255460.img of=/dev/sdX bs=1m conv=sync status=progress