NAME

SYNOPSIS

DESCRIPTION

Packmule will install packages and custom content described by the config YAML file. This makes describing a packing list very readable and efficient. The default config is the file ./packmule.yml. The config file can be specified with the "-y" argument. There are two major sections of the config, PKGS and CUSTOM. PKGS should simply be a list of package names to be installed with the "pkg" utility. CUSTOM should be a list of key-value pairs for installing software not installable by PKGS. CUSTOM's keys should be a location of a file to install on the computer running packmule. The values should be the location to install the key files at under the installation image. During distribution extraction bsdinstall(8) should show packmule-pkgs.txz alongside the other archives as it extracts the added content. Packmule can also create an unattended installation image from a regular installation image using the INSTALLERCONFIG section of the configuration file.

Packmule is written in Perl, and all variables starting with $ in this doc reference the variable names used in the Packmule script. These variables are included to help the reader follow both the script itself and the debugging output if they should choose to read it. The leading $ is kept to differentiate these Perl variables from environment variables.

OPTIONS

-U

Build USB memstick images instead of an iso. This is the same as the FreeBSD-*.img images available for download online. They have a different partition layout and internally require a different script to build.

-R

The Remove flag. Shortcut to unmount packmule's resources and remove its working directories. Use this to clean up the mule's droppings that are left behind after an error.

-D

The Debug flag. Useful for development. Does everything except tar $pkgroot and create the installation iso. This can be used to see exactly what packmule does as far as installing and copying packages.

-y config.yml

The '-y' flag specifies the input YAML file to use as a packing list. The default configuation file is './packmule.yml'. The pathname of the config file to use must follow the '-y' flag.

-I,--no-pkg-scripts

Used as a workaround to pkg pre-install failures, specifically those caused by failing to create a new user or group. If you encounter pkg install failures try using this option. See the LIMITATIONS section for more info.

CONFIGURATION

PKGS

This section holds names of packages to be installed through the pkg(8) tool. They are installed in the new image using the $workroot directory as the root.

CUSTOM

Individual files or directories to be copied into the new image. Values are separated by :, with the value on the left being the source file and the value on the right being the destination. ( /path/to/src : /install/location)

LIVE_CD_PKGS

Same as PKGS, but intalls onto the live cd image instead of the host.

LIVE_CD_CUSTOM

Same as CUSTOM, but intalls onto the live cd image instead of the host.

INSTALLERCONFIG

A path to an installerconfig script to be used for an unattended installation. More information about unattended installations and installerconfigs can be found in bsdinstall(8)

Here is an example configuration (config.yml): _____________________________________________

PKGS:
- perl5-5.24.3
- nethack36
- gnome3

CUSTOM:
/root/.shrc : /root/.shrc
/etc/hosts : /etc/hosts

LIVE_CD_PKGS
/etc/rc.conf : /etc/rc.conf

INSTALLERCONFIG : ~user/installerconfig ______________________________________________

The above example is much smaller than what is useful. This configuration will install perl, nethack, and gnome3 in the installation image. It also copies individual files such as resolv.conf and hosts. This is useful for installing custom configuration files automatically on a system, particularly in the case of VM's. A installation image could use this to include your rc.conf, .bashrc, .emacs, etc.

TIPS

HOW IT WORKS:

The tool works in five major stages:
1) the .iso is mounted under $mntdir
2) contents of the read-only .iso are copied into $workroot
3) the plist is read and each package is installed under $pkgroot
$pkgroot is compressed and added to $workroot/usr/freebsd-dist
to be installed as a distribution file
4) The $workroot is written into a installation .iso by the appropriate mkisoimages.sh script
5) the .iso is unmounted and all directories are cleaned up

LIMITATIONS:

AUTHORS