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, e.g. the configuration of 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 Ansible role vbotka.config_light instead of creating additional custom tasks. The advantage would be unified configuration data in config_light. Create custom tasks if config_light is not able to do what you want. Contributions are welcome. See the examples in the directory contrib.

Many of the tasks in the workflow are disabled by default and can be enabled and run one by one to accomplish standalone tasks (see tasks/main.yml and defaults/main.yml). By default, sanity, mount, customize, and umount are enabled. All included customization tasks are disabled by default (see tasks/customize). 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 completes. To speedup repeating execution of a playbook, it’s possible to disable the unmounting of the image by setting the variable bsd_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
Requirements: vbotka.ansible_lib

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_custom_image

and install it

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

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

See also

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

Playbook 

Below is a simple playbook that calls this role (10) for a single host images.example.com (2)

shell> cat playbook.yml
- 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

gather_facts: true (3) must be set to test sanity ansible_os_family

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 bsd_cimage_debug is enabled. Enable debug output either in the configuration

bsd_cimage_debug: true

, or set the extra variable in the command

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

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 (images.example.com): images.example.com TAGS: []
   TASK TAGS: [always, bsd_cimage_customize, bsd_cimage_debug,
   bsd_cimage_download, bsd_cimage_loaderconf, bsd_cimage_mdconfig,
   bsd_cimage_mount, bsd_cimage_mount_points, bsd_cimage_packages,
   bsd_cimage_rcconf, bsd_cimage_sanity, bsd_cimage_umount,
   bsd_cimage_unpack, bsd_cimage_wpasupconf]

Basics 

Display the variables. Use the tag bsd_cimage_debug. Enable debug (bsd_cimage_debug: true)

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

Download images

 shell> ansible-playbook playbook.yml -t bsd_cimage_download

Unpack images

 shell> ansible-playbook playbook.yml -t bsd_cimage_unpack

Create memory disk and mount the image

 shell> ansible-playbook playbook.yml -t bsd_cimage_mount

Run sanity tests. Enable sanity (bsd_cimage_sanity: true)

 shell> ansible-playbook playbook.yml -t bsd_cimage_mount

Customize the image

 shell> ansible-playbook playbook.yml -t bsd_cimage_customize

Umount the image

 shell> ansible-playbook playbook.yml -t bsd_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 file-names in the directory defaults/main. Enable, configure and run these tasks as needed. Keep this arrangement when you add custom tasks.

Note

Instead of creating additional custom tasks, consider Ansible role config_light. See Configure wifi by config_light

Variables 

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

See also

Ansible variable precedence: Where should I put a variable?

Default variables 

Review the default variables in the directory defaults/main. These variables can be customized in the directory vars/main. The files in the directory vars/main will be preserved by the update of the role.

[defaults/main.yml]

---
# default vars for freebsd_custom_image

# Test sanity
bsd_cimage_sanity: false
# Display debug output
bsd_cimage_debug: false
# Display classified debug output
bsd_cimage_debug_classified: false
# Install packages or ports
bsd_cimage_install: false
# Create memory disks and mount partitions. Module mount creates mountpoints.
bsd_cimage_mount: true
# Create mountpoints by module file
bsd_cimage_mount_points_create: false
# Umount and delete mountpoints. Detach memory disk
bsd_cimage_umount: true

# Packages  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

freebsd_install_method: packages
# freebsd_install_method: ports
freebsd_use_packages: true
freebsd_install_retries: 10
freebsd_install_delay: 5

bsd_cimage_packages: []
# - shells/bash
# Images  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bsd_cimage_download: []
# bsd_cimage_download:
#   - 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

bsd_cimage_dir: /export/images/FreeBSD/unsorted
# bsd_cimage_owner:
# bsd_cimage_group:
# bsd_cimage_mode:

# mount image
bsd_cimage_mount_dir: /export/images/FreeBSD/live
bsd_cimage_mount_file: ""
# bsd_cimage_mount_file: FreeBSD-13.0-CURRENT-arm-armv6-RPI-B-20201231-282381aa53a-255460.img
bsd_cimage_mount_mode: "0755"
bsd_cimage_mount_points:
  - partition: s2a
    fstype: ufs
    mountpoint: /mnt3

# Unpack - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bsd_cimage_unpack_cmd:
  .xz: unxz --keep
bsd_cimage_unpack_ext: "{{ bsd_cimage_unpack_cmd.keys() | list }}"

# Customize - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# This mountpoint is the root of the tree that shall be customized. There can be more partitions
# mounted to different mountpoints from single image.
bsd_cimage_mount_path: /mnt3

# authorized keys
# bsd_cimage_authorized_key:
#   - user: "freebsd"
#     key: "{{ lookup('file', 'copy/ssh-pub-keys/admin-ar1/id_rsa.pub') }}"
#   - user: "freebsd"
#     key: "{{ lookup('file', 'copy/ssh-pub-keys/admin-ar2/id_rsa.pub') }}"

# EOF

See also

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

Warning

Don’t make any changes to the files in defaults/main. The changes will be overwritten by the update of the role. Customize the default values in the files in vars/main.yml.
Default value of bsd_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 bsd_cimage_debug \
                                     -e bsd_cimage_debug=true \
                                     -e bsd_cimage_debug_classified=true

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

Unpack the images

shell> ansible-playbook playbook.yml -t bsd_cimage_unpack

Create memory disk and mount image

shell> ansible-playbook playbook.yml -t bsd_cimage_mount

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

shell> ansible-playbook  playbook.yml -t bsd_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 bsd_cimage_customize
```

Umount the image and detach the memory disk

shell> ansible-playbook playbook.yml -t bsd_cimage_umount

Dump the customized image to a disk and boot it

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

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