poudriere image.8

This page is auto-generated from src/man/poudriere-image.8

POUDRIERE-IMAGE(8)

FreeBSD System Manager's Manual

POUDRIERE-IMAGE(8)

NAME

poudriere image — build OS filesystem images

SYNOPSIS

poudriere image

-j name -t type [options]

DESCRIPTION

Builds a filesystem image per the specified options.

WARNING: This feature is still considered ALPHA.

OPTIONS

-A post-script

Source the post-script file after populating the $WRKDIR/world directory.

See the ENVIRONMENT section for a list of environment variables that are available.

-b

Place the swap partition before the primary partition(s) to allow the primary partition to be grown to fill the remaining space on a disk.

-B pre-script

Source the pre-script file before the image prepare function. Can optionally replace the prepare function, in which case it should create the image file, add partitions, format filesystems, and then mount them to $WRKDIR/world before the contents are installed to that directory.

See the ENVIRONMENT section for a list of environment variables that are available or may need to be populated by the script.

-c overlaydir

This specifies an extra directory whose contents will be copied directly into the final image, starting from the root.

-f packagelist

This specifies a list of packages to be pre-installed in the final image.

-h hostname

This specifies the hostname used for the image. Defaults to poudriere-image.

-i originimage

Path to a previously built image. For -t zsnapshot, this should be full.img.gz. For -t zfs this should be image.full.zfs.

-j name

This argument specifies the name of the jail that is used.

-m overlaydir

Build a miniroot image as well (for tar type images), and copy this directory into the miniroot image.

-n name

This specifies the name of the resulting image.

-o outputdir

This argument specifies directory where the resulting image will be created.

-p tree

This argument specifies the name of the ports tree that is used.

-R flags

The flags to pass to ‘zfs send’ when creating the replication stream. These will control which features are enabled in the stream. Default: -Rec

-S snapshotname

Name of the snapshot for zsnapshot type.

-s size

This specifies the maximum size of the image that is built.

-t type

This specifies the type of image to create:

hybridiso

An ISO 9660 format image that that is also a valid GPT image and can be written to a USB device for BIOS/legacy and UEFI boot.

iso

An ISO 9660 format image.

iso+mfs

An ISO 9660 format image where the root filesystem is MFS mounted.

iso+zmfs

An ISO 9660 format image where the root filesystem is LZ77 compressed and is MFS mounted.

usb

A GPT-layout prepared UFS2 image containing a UEFI boot loader.

usb+mfs

A GPT-layout prepared UFS2 image containing a UEFI boot loader where the root filesystem is MFS mounted.

usb+zmfs

A GPT-layout prepared UFS2 image containing a UEFI boot loader where the root filesystem is LZ77 compressed and is MFS mounted.

rawdisk

A raw UFS2, softupdates-enabled, disk image.

zrawdisk

A raw ZFS disk image.

zfs

Create a ZFS image in the same style as bsdinstall(8). Supports the following sub-types, defaulting to gpt if not subtype is specified:

zfs+gpt

Creates a complete disk image with a GPT partition table. Includes both UEFI and Legacy boot code.

zfs+raw

Created an image of only the ZFS pool with no partitions. Not bootable.

zfs+send

Creates a full ZFS replication stream of the whole pool, including the boot environment, to be received using the zfs-recv(8) command. Alias for zfs+send+full. You may create both send streams by specifying both sub-types (example: zfs+send+full+be).

zfs+send+be

Creates a ZFS replication stream of only the boot environment.

tar

An XZ-compressed tarball.

firmware

A NanoBSD style image with a GPT partitions and a UEFI boot loader.

rawfirmware

A raw disk image.

zsnapshot

Create a zfs snapshot full and incremental to be used in a jail.

-w size

This specifies the size of the swap partition to be added to the image. Size 0 skips the creation of a swap partition.

-X excludefile

This specifies a list of files to exclude from the final image.

-z set

This specifies which SET to use for the build.

ENVIRONMENT

IMAGESIZE

The size of the image file to be created, in bytes.

IMAGENAME

The name of the image (from -n name).

SKIP_PREPARE

If set, do not run the image types default prepare function. The pre-script must then create the image file, add partitions, format filesystems, and then mount them to $WRKDIR/world .

WORLDDIR

The path to the directory that is the root of the image.

ZFS_BEROOT_NAME

The name of the dataset that contains all boot environments. Default: ROOT.

ZFS_BOOTFS_NAME

The name of the default boot environment dataset. Default: default.

ZFS_POOL_NAME

The name of the ZFS pool. Defaults to zroot.

md

The name of the mdconfig(8) device corresponding to the image file. The pre-script should populated this variable with the name of the md device created, so that it is properly cleaned up after the image is created.

CUSTOMIZATION

Create optional src.conf

An optional src.conf which will be used for building images. Any of the following are allowed and will be applied in the order shown:

/usr/local/etc/poudriere.d/src.conf

/usr/local/etc/poudriere.d/<jailname>-src.conf

/usr/local/etc/poudriere.d/image-<jailname>-src.conf

/usr/local/etc/poudriere.d/image-<jailname>-<setname>-src.conf

SEE ALSO

poudriere(8), poudriere-bulk(8), poudriere-distclean(8), poudriere-jail(8), poudriere-logclean(8), poudriere-options(8), poudriere-pkgclean(8), poudriere-ports(8), poudriere-queue(8), poudriere-status(8), poudriere-testport(8), poudriere-version(8)

AUTHORS

Baptiste Daroussin ⟨bapt@FreeBSD.org⟩
Bryan Drewery ⟨bdrewery@FreeBSD.org⟩

April 18, 2023

FreeBSD 15.0-CURRENT