.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "IMAGE-FACTORY" "1" "2020-08-05" "image-factory" "image-factory\[cq]s Manual"
.hy
.SH NAME
.PP
image-factory - build golden Linux images
.SH SYNOPSIS
.PP
\f[B]image-factory\f[R] [\f[B]-h\f[R]|\f[B]--help\f[R]]
[\f[B]-c\f[R]|\f[B]--cache-dir\f[R] \f[I]CACHE_DIR\f[R]]
[\f[B]-f\f[R]|\f[B]--format\f[R] {\f[I]qcow2\f[R],\f[I]raw\f[R]}]
[\f[B]--image-size\f[R] \f[I]IMAGE_SIZE\f[R]] [\f[B]--mac\f[R]
\f[I]MAC\f[R]] [\f[B]--installer-logs\f[R]]
[\f[B]--no-installer-logs\f[R]] [\f[B]--log-file\f[R]]
[\f[B]--no-log-file\f[R]] [\f[B]--log-filename\f[R]
\f[I]LOG_FILENAME\f[R]] \f[I]image\f[R]
.SH DESCRIPTION
.PP
\f[B]image-factory\f[R] is a command line tool for building golden Linux
images.
It uses \f[B]virt-install\f[R] to do installations via the network.
The installation and configuration of the images is done using the
netinstall support from the distributions, i.e.
.IP \[bu] 2
preseed for Debian/Ubuntu
.IP \[bu] 2
Kickstart for CentOS/Fedora
.IP \[bu] 2
AutoYaST for openSUSE
.PP
\f[B]image-factory\f[R] is used by IONOS Cloud to build the golden
public Linux images for their Enterprise Cloud.
The configuration files are shipped with this project to allow anyone to
rebuild their images.
.PP
\f[B]image-factory\f[R] runs following steps:
.IP \[bu] 2
Create a virtual RAW image using qemu-img.
.IP \[bu] 2
Cache \f[B]linux\f[R] kernel and \f[B]initrd\f[R].
.IP \[bu] 2
Run installation using \f[B]virt-install\f[R].
\f[I]qemu:///session\f[R] is used as session for normal users and
\f[I]qemu:///system\f[R] when run as root.
.IP \[bu] 2
The installation partition is mounted and the installer logs are
removed.
.IP \[bu] 2
\f[B]zerofree\f[R] is run on the partition.
.IP \[bu] 2
If \f[B]format\f[R] is set to \f[I]qcow2\f[R], the virtual raw images
will be converted to qcow2 using \f[B]qemu-img\f[R].
.IP \[bu] 2
The SHA 256 sum is calculated for the image.
.IP \[bu] 2
The image will be uploaded to all locations configured in
\f[B]upload_destinations\f[R].
.IP \[bu] 2
If \f[B]post-build-command\f[R] is configured, the specified command
will be executed.
.SH OPTIONS
.TP
\f[B]-h\f[R], \f[B]--help\f[R]
Show a help message and exit
.TP
\f[B]-c\f[R] \f[I]CACHE_DIR\f[R], \f[B]--cache-dir\f[R] \f[I]CACHE_DIR\f[R]
Cache directory (default: \f[I]\[ti]/.cache/image-factory\f[R] or
\f[I]var/cache/image-factory\f[R] for root)
.TP
\f[B]-f\f[R] {\f[I]qcow2\f[R],\f[I]raw\f[R]}, \f[B]--format\f[R] {\f[I]qcow2\f[R],\f[I]raw\f[R]}
Image format to use (default: \f[I]raw\f[R])
.TP
\f[B]--image-size\f[R] \f[I]IMAGE_SIZE\f[R]
Size of the raw image (default: \f[I]2G\f[R])
.TP
\f[B]--mac\f[R] \f[I]MAC\f[R]
MAC address used in the installation machine
.TP
\f[B]--installer-logs\f[R]
Print installer logs into logging output
.TP
\f[B]--no-installer-logs\f[R]
Do not print installer logs into logging output
.TP
\f[B]--log-file\f[R]
Store logs into a file (in addition to stdout/stderr)
.TP
\f[B]--no-log-file\f[R]
Do not store logs into a file (in addition to stdout/stderr)
.TP
\f[B]--log-filename\f[R] \f[I]LOG_FILENAME\f[R]
log into specified file
.TP
\f[I]image\f[R]
Image to build.
The date in form of \f[I]YYYY-MM-DD\f[R] and the file format suffix will
be added to the generated image filename.
.SH CONFIGURATION
.PP
Each image needs to be also configured in
\f[I]/etc/image-factory.conf\f[R] or
\f[I]\[ti]/.config/image-factory.conf\f[R].
These configuration files use the INI file format.
The image name will be used as section and following keys are used:
.TP
\f[B]append\f[R]
Extra kernel parameter for the netboot image to use
.TP
\f[B]cache_dir\f[R]
Cache directory (default: \f[I]\[ti]/.cache/image-factory\f[R] or
\f[I]var/cache/image-factory\f[R] for root).
Can be overridden by \f[B]--cache-dir\f[R].
.TP
\f[B]cores\f[R]
Number of CPU cores to use during installation.
Default: \f[I]1\f[R]
.TP
\f[B]format\f[R]
Image format to use.
Can be \f[I]qcow2\f[R] or \f[I]raw\f[R] (default).
Can be overridden by \f[B]--format\f[R].
.TP
\f[B]image-size\f[R]
Size of the raw image (default: \f[I]2G\f[R]).
Can be overridden by \f[B]--image-size\f[R].
.TP
\f[B]initrd\f[R]
URI of the netboot installer initrd.
Supported schemes are \f[I]file:\f[R], \f[I]http:\f[R],
\f[I]https:\f[R], and \f[I]rsync:\f[R].
Unless using \f[I]file:\f[R], the specified initrd will be cached
locally.
.TP
\f[B]installer-logs\f[R]
Boolean whether to print installer logs into logging output.
Can be overridden by \f[B]--installer-logs\f[R] or
\f[B]--no-installer-logs\f[R].
.TP
\f[B]keep-raw\f[R]
Boolean whether to keep raw image (in case format is not raw).
Default is \f[I]False\f[R].
.TP
\f[B]kickstart\f[R]
Filename of the Kickstart file.
Needed when using Kickstart on CentOS/Fedora.
.TP
\f[B]linux\f[R]
URI of the netboot installer Linux kernel.
Supported schemes are \f[I]file:\f[R], \f[I]http:\f[R],
\f[I]https:\f[R], and \f[I]rsync:\f[R].
Unless using \f[I]file:\f[R], the specified kernel will be cached
locally.
.TP
\f[B]log-file\f[R]
Boolean whether to store logs into a file (in addition to
stdout/stderr).
Can be overridden by \f[B]--log-file\f[R] or \f[B]--no-log-file\f[R].
.TP
\f[B]log-filename\f[R]
Filename to log into (if enabled).
Can be overridden by \f[B]--log-filename\f[R].
.TP
\f[B]mac\f[R]
MAC address used in the installation machine.
Can be overridden by \f[B]--mac\f[R].
.TP
\f[B]post-build-command\f[R]
Optional command to run after the image was successfully built.
The name of the image will be passed as first argument.
.TP
\f[B]preseed\f[R]
Filename of the preseed file.
Needed when using preseed on Debian/Ubuntu.
.TP
\f[B]ram\f[R]
Memory for virtual machine to use during installation.
.TP
\f[B]upload_destinations\f[R]
Comma-separated list of upload destinations.
Each upload destination needs a section in the configuration file (see
UPLOAD DESTINATION CONFIGURATION below).
To disable the upload, let \f[B]upload_destinations\f[R] undefined or
set to an empty string.
.TP
\f[B]vnc\f[R]
VNC port for the installation virtual machine.
It is recommended to bind the VNC port to localhost only.
.TP
\f[B]yast\f[R]
Filename of the AutoYaST file.
Needed when using AutoYaST on openSUSE.
.SH UPLOAD DESTINATION CONFIGURATION
.PP
Each upload destination configured in \f[B]upload_destinations\f[R]
needs a section in the INI configuration, where at least
\f[B]upload_type\f[R] and \f[B]upload_target\f[R] are set.
Following keys are accepted:
.TP
\f[B]post-upload-command\f[R]
Additional command to run after a successful upload.
\f[I]${image}\f[R] can be used as parameter in post-upload-command.
If multiple commands are needed, suffix the key with a number (counting
up from 1), e.g.
\f[B]post-upload-command1\f[R].
.TP
\f[B]upload_args\f[R]
Additional arguments for the upload command to use,
e.g.\ \f[I]--progress\f[R] for uploads with rsync.
.TP
\f[B]upload_target\f[R]
Upload target in the format the upload type supports it.
.TP
\f[B]upload_type\f[R]
Type of upload.
Currently only \f[I]rsync\f[R] is supported.
.SH SEE ALSO
.PP
qemu-img(1), virt-install(1), zerofree(8)
.SH AUTHOR
.PP
Benjamin Drung <benjamin.drung@cloud.ionos.com>