User’s guide

Introduction 

The goal of this role is the customization of FreeBSD installation images. FreeBSD provides the users with the option of Release Building. The usage of this powerful tool to make small changes, for example the configuration of the wireless network (see Quick start guide), would be an overkill. Instead, this role provides the users with the options to mount released images and development snapshots, and customize them. The role can be easily configured and extended. The users are expected to write playbooks and additional customization tasks when needed. When you decide to customize the functionality consider the Ansible role vbotka.config_light instead of creating additional custom tasks. The advantage would be unified configuration data in vbotka.config_light. Create custom tasks if the role vbotka.config_light is not able to do what you want. Contributions are welcome. See the examples in the directory contrib.

Many tasks are disabled by default. They can be enabled and run one by one to accomplish standalone tasks (see tasks/main.yml and defaults/main/main.yml). By default, download, unpack, mount, and umount are enabled. All included customization tasks are disabled by default (see tasks/customize.yml and default/main/customize.yml). See Tags Examples and Best practice on how to enable and run tasks one by one.

By default, the role is not idempotent. In the standard workflow, an image is always mounted when the role starts and unmounted when the customization completes. To speedup the repeating execution of a playbook, disable the unmounting of the image by setting the variable cimage_umount=false. This would make the role idempotent. Unmount the image before dumping it to a disk.

Ansible role: vbotka.freebsd_custom_image
Supported systems: FreeBSD

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, look at the current status of the role

shell> ansible-galaxy role info vbotka.freebsd_custom_image

and install it

shell> ansible-galaxy role install vbotka.freebsd_custom_image

Install the collections community.general, ansible.posix, and vbotka.freebsd

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

See also

To install specific versions from various sources see Installing content.
Look at other roles shell> ansible-galaxy search --author=vbotka

Playbook 

Below is a simple playbook playbook.yml that calls this role (9) for a single managed node images.example.com (1)

- hosts: images.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: true
  become_user: root
  become_method: sudo
  roles:
    - vbotka.freebsd_custom_image

Note

To test sanity ansible_os_family, gather_facts: true (2) must be enabled.

See also

For details see Connection Plugins (3-4)
See also Understanding Privilege Escalation (5-7)

Debug 

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

cimage_debug: true

, or set the extra variable in the command

shell> ansible-playbook playbook.yml -e cimage_debug=true

Note

The debug output of this role is optimized for the YAML format. Set it either in the environment

shell> export ANSIBLE_CALLBACK_RESULT_FORMAT=yaml

, or in the configuration

[defaults]
callback_result_format = yaml

See also

Tags 

The tags provide the user with a very useful tool to run selected tasks of the role. List the role’s tags to see what tags are available

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

playbook: playbook.yml

play #1 (images.example.com): images.example.com TAGS: []
   TASK TAGS: [cimage_customize, cimage_debug, cimage_download,
   cimage_loaderconf, cimage_mdconfig, cimage_mount, cimage_mount_points,
   cimage_packages, cimage_rcconf, cimage_sanity, cimage_umount,
   cimage_unpack, cimage_wpasupconf]

Basics

Display the variables. Use the tag cimage_debug and set cimage_debug: true

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

Download images

shell> ansible-playbook playbook.yml -t cimage_download

Unpack images

shell> ansible-playbook playbook.yml -t cimage_unpack

Create memory disk and mount the image

shell> ansible-playbook playbook.yml -t cimage_mount

Run sanity tests. Enable sanity cimage_sanity: true

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

Customize the image

shell> ansible-playbook playbook.yml -t cimage_customize

Umount the image

shell> ansible-playbook playbook.yml -t cimage_umount

Customization tasks 

The description of the customization’s tasks is not complete. The role and the documentation is work in progress. Feel free to share your feedback and report issues.

Contributions are welcome.

See also

Source code customize.yml

All customization tasks are disabled by default. The default variables of these tasks are stored under the same filenames in the directory defaults/main. Enable, configure, and run these tasks as needed. Keep this arrangement when you add custom tasks. Add custom tasks to the dictionary cimage_customize

defaults/main/customize.yml

---
cimage_customize:
  loaderconf: "{{ cimage_loaderconf }}"
  wpasupconf: "{{ cimage_wpasupconf }}"
  rcconf: "{{ cimage_rcconf }}"
  postinstall: "{{ cimage_postinstall }}"

cimage_postinstall: []

# EOF

Included customization tasks

Hint

Instead of creating more custom tasks, consider Ansible role vbotka.config_light. See the example Configure wifi by config_light

Variables 

There are two categories of variables. The variables that control the workflow of the role (see defaults/main/main.yml) and customization tasks variables (see other files in defaults/main).

Default variables

Review the default variables in the directory defaults/main. For example,

defaults/main/main.yml

---
# default vars for freebsd_custom_image
cimage_role_version: 2.8.1

# Display debug output.
cimage_debug: false
# Display classified debug output.
cimage_debug_classified: false

# Test sanity.
cimage_sanity: false
cimage_sanity_quiet: true

# Download images.
cimage_download: true

# Unpack images.
cimage_unpack: true

# Create memory disks and mount partitions. Module mount creates mountpoints.
cimage_mount: true

# Install packages or ports.
cimage_install: false

# Umount and delete mountpoints. Detach memory disk.
cimage_umount: true

# Use vbotka.freebsd.lib in collection vbotka.freebsd
cimage_ansible_lib:
  vbotka.freebsd_custom_image: vbotka.ansible_lib
  vbotka.freebsd.custom_image: vbotka.freebsd.lib

# EOF

defaults/main/images.yml

---
cimage_get_images: true
cimage_get_checksums: true
cimage_download_images: []
# cimage_download_images:
#   - site: https://download.freebsd.org/ftp/snapshots/ISO-IMAGES/13.0
#     image: FreeBSD-13.0-CURRENT-arm-armv6-RPI-B-20210107-f2b794e1e90-255641.img.xz
#     checksum: CHECKSUM.SHA512-FreeBSD-13.0-CURRENT-arm-armv6-RPI-B-20210107-f2b794e1e90-255641
#   - site: https://download.freebsd.org/ftp/releases/ISO-IMAGES/12.2
#     image: FreeBSD-12.2-STABLE-arm-armv6-RPI-B-20210107-r368787.img.xz
#     checksum: CHECKSUM.SHA512-FreeBSD-12.2-STABLE-arm-armv6-RPI-B-20210107-r368787

cimage_dir: /export/images/FreeBSD/unsorted
# cimage_owner:
# cimage_group:
# cimage_mode:
# cimage_mode_dir:

# EOF

defaults/main/customize.yml

---
cimage_customize:
  loaderconf: "{{ cimage_loaderconf }}"
  wpasupconf: "{{ cimage_wpasupconf }}"
  rcconf: "{{ cimage_rcconf }}"
  postinstall: "{{ cimage_postinstall }}"

cimage_postinstall: []

# EOF

Hint

Create custom tasks in the directory tasks/fn.
Fit the dictionary cimage_customize to your needs. See customize.yml

See also

Other files in defaults/main
The examples of the customization vars/main.yml.sample

Warning

Don’t make any changes in the files in the directory defaults/main. The role update will overwrite the changes.
The default value of cimage_debug_classified is false. Passwords will be displayed if this variable is enabled.

Best practice 

Create a playbook and test the syntax

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

See what variables will be included

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

Download images. To make the task idempotent use the attribute checksum in the items of the list cimage_download_images. See Default variables
```
shell> ansible-playbook playbook.yml -t cimage_download
```

Unpack the images

shell> ansible-playbook playbook.yml -t cimage_unpack

Create memory disk and mount image

shell> ansible-playbook playbook.yml -t cimage_mount

Dry-run the customization of the image and see what will be changed

shell> ansible-playbook  playbook.yml -t cimage_customize --check --diff

Customize the image. Run the playbook and keep the image mounted. Review the changes. Repeated execution of the customization should be idempotent
```
shell> ansible-playbook playbook.yml -t cimage_customize
```

Umount the image and detach the memory disk

shell> ansible-playbook playbook.yml -t cimage_umount

Dump the customized image to a disk and boot it

shell> dd if=image.img of=/dev/mmcsd0 bs=1m conv=sync status=progress

Hint

In Linux, use bs=1M

Keep the image mounted if you want to run the playbook periodically. In this case, repeated execution of the playbook should be idempotent
```
shell> ansible-playbook playbook.yml -e cimage_umount=false
```
However, the mountpoint is not configured in /etc/fstab and won’t survive a reboot. If this is a problem, put the configuration of the memory disk into /etc/rc.conf and configure the mountpoint in /etc/fstab.