Build manpages for composer-cli and lorax-composer

Add manpage creation to make docs target to keep them updated.

Makefile

@@ -25,6 +25,8 @@ install: all
 	mkdir -p $(DESTDIR)/$(mandir)/man1
 	install -m 644 docs/man/lorax.1 $(DESTDIR)/$(mandir)/man1
 	install -m 644 docs/man/livemedia-creator.1 $(DESTDIR)/$(mandir)/man1
+	install -m 644 docs/man/lorax-composer.1 $(DESTDIR)/$(mandir)/man1
+	install -m 644 docs/man/composer-cli.1 $(DESTDIR)/$(mandir)/man1
 	mkdir -p $(DESTDIR)/etc/bash_completion.d
 	install -m 644 etc/bash_completion.d/composer-cli $(DESTDIR)/etc/bash_completion.d
 
@@ -53,7 +55,7 @@ tag:
 	git tag -f $(TAG)
 
 docs:
-	$(MAKE) -C docs apidoc html
+	$(MAKE) -C docs apidoc html man
 
 archive:
 	@git archive --format=tar --prefix=$(PKGNAME)-$(VERSION)/ $(TAG) > $(PKGNAME)-$(VERSION).tar

docs/conf.py

@@ -218,7 +218,7 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'Lorax.tex', u'Lorax Documentation',
-   u'Anaconda Team', 'manual'),
+   u'Weldr Team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -247,8 +247,10 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('lorax', 'lorax', u'Lorax Documentation', [u'Anaconda Team'], 1),
+    ('lorax', 'lorax', u'Lorax Documentation', [u'Weldr Team'], 1),
-    ('livemedia-creator', 'livemedia-creator', u'Live Media Creator Documentation', [u'Anaconda Team'], 1)
+    ('livemedia-creator', 'livemedia-creator', u'Live Media Creator Documentation', [u'Weldr Team'], 1),
+    ('lorax-composer', 'lorax-composer', u'Lorax Composer Documentation', [u'Weldr Team'], 1),
+    ('composer-cli', 'composer-cli', u'Composer Cmdline Utility Documentation', [u'Weldr Team'], 1),
 ]
 
 # If true, show URL addresses after external links.
@@ -262,7 +264,7 @@ man_pages = [
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'Lorax', u'Lorax Documentation',
-   u'Anaconda Team', 'Lorax', 'One line description of project.',
+   u'Weldr Team', 'Lorax', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -283,8 +285,8 @@ texinfo_documents = [
 
 # Bibliographic Dublin Core info.
 epub_title = u'Lorax'
-epub_author = u'Anaconda Team'
+epub_author = u'Weldr Team'
-epub_publisher = u'Anaconda Team'
+epub_publisher = u'Weldr Team'
 epub_copyright = u'2018, Red Hat, Inc.'
 
 # The basename for the epub file. It defaults to the project name.

docs/man/composer-cli.1

@@ -0,0 +1,253 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "COMPOSER-CLI" "1" "Oct 24, 2018" "30.5" "Lorax"
+.SH NAME
+composer-cli \- Composer Cmdline Utility Documentation
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.INDENT 0.0
+.TP
+.B Authors
+Brian C. Lane <\fI\%bcl@redhat.com\fP>
+.UNINDENT
+.sp
+\fBcomposer\-cli\fP is used to interact with the \fBlorax\-composer\fP API server, managing blueprints, exploring available packages, and building new images.
+.sp
+It requires \fI\%lorax\-composer\fP to be installed on the
+local system, and the user running it needs to be a member of the \fBweldr\fP
+group. They do not need to be root, but all of the \fI\%security precautions\fP apply.
+.SH COMPOSER-CLI CMDLINE ARGUMENTS
+.sp
+Lorax Composer commandline tool
+
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: composer\-cli [\-h] [\-j] [\-s SOCKET] [\-\-log LOG] [\-a APIVER]
+                    [\-\-test TESTMODE] [\-V]
+                    ...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Positional Arguments
+.INDENT 0.0
+.TP
+.Bargs
+.UNINDENT
+.SS Named Arguments
+.INDENT 0.0
+.TP
+.B\-j, \-\-json
+Output the raw JSON response instead of the normal output.
+.sp
+Default: False
+.TP
+.B\-s, \-\-socket
+Path to the socket file to listen on
+.sp
+Default: "/run/weldr/api.socket"
+.TP
+.B\-\-log
+Path to logfile (./composer\-cli.log)
+.TP
+.B\-a, \-\-api
+API Version to use
+.sp
+Default: "0"
+.TP
+.B\-\-test
+Pass test mode to compose. 1=Mock compose with fail. 2=Mock compose with finished.
+.sp
+Default: 0
+.TP
+.B\-V
+show program\(aqs version number and exit
+.sp
+Default: False
+.UNINDENT
+.sp
+.INDENT 0.0
+.TP
+.B compose start <BLUEPRINT> <TYPE>
+Start a compose using the selected blueprint and output type.
+.TP
+.B compose types
+List the supported output types.
+.TP
+.B compose status
+List the status of all running and finished composes.
+.TP
+.B compose list [waiting|running|finished|failed]
+List basic information about composes.
+.TP
+.B compose log <UUID> [<SIZE>]
+Show the last SIZE kB of the compose log.
+.TP
+.B compose cancel <UUID>
+Cancel a running compose and delete any intermediate results.
+.TP
+.B compose delete <UUID,...>
+Delete the listed compose results.
+.TP
+.B compose info <UUID>
+Show detailed information on the compose.
+.TP
+.B compose metadata <UUID>
+Download the metadata use to create the compose to <uuid>\-metadata.tar
+.TP
+.B compose logs <UUID>
+Download the compose logs to <uuid>\-logs.tar
+.TP
+.B compose results <UUID>
+Download all of the compose results; metadata, logs, and image to <uuid>.tar
+.TP
+.B compose image <UUID>
+Download the output image from the compose. Filename depends on the type.
+.TP
+.B blueprints list
+List the names of the available blueprints.
+.TP
+.B blueprints show <BLUEPRINT,...>
+Display the blueprint in TOML format.
+.TP
+.B blueprints changes <BLUEPRINT,...>
+Display the changes for each blueprint.
+.TP
+.B blueprints diff <BLUEPRINT> <FROM\-COMMIT> <TO\-COMMIT>
+Display the differences between 2 versions of a blueprint.
+FROM\-COMMIT can be a commit hash or NEWEST
+TO\-COMMIT  can be a commit hash, NEWEST, or WORKSPACE
+.TP
+.B blueprints save <BLUEPRINT,...>
+Save the blueprint to a file, <BLUEPRINT>.toml
+.TP
+.B blueprints delete <BLUEPRINT>
+Delete a blueprint from the server
+.TP
+.B blueprints depsolve <BLUEPRINT,...>
+Display the packages needed to install the blueprint.
+.TP
+.B blueprints push <BLUEPRINT>
+Push a blueprint TOML file to the server.
+.TP
+.B blueprints freeze <BLUEPRINT,...>
+Display the frozen blueprint\(aqs modules and packages.
+.TP
+.B blueprints freeze show <BLUEPRINT,...>
+Display the frozen blueprint in TOML format.
+.TP
+.B blueprints freeze save <BLUEPRINT,...>
+Save the frozen blueprint to a file, <blueprint\-name>.frozen.toml.
+.TP
+.B blueprints tag <BLUEPRINT>
+Tag the most recent blueprint commit as a release.
+.TP
+.B blueprints undo <BLUEPRINT> <COMMIT>
+Undo changes to a blueprint by reverting to the selected commit.
+.TP
+.B blueprints workspace <BLUEPRINT>
+Push the blueprint TOML to the temporary workspace storage.
+.TP
+.B modules list
+List the available modules.
+.TP
+.B projects list
+List the available projects.
+.TP
+.B projects info <PROJECT,...>
+Show details about the listed projects.
+.TP
+.B sources list
+List the available sources
+.TP
+.B sources info <SOURCE\-NAME,...>
+Details about the source.
+.TP
+.B sources add <SOURCE.TOML>
+Add a package source to the server.
+.TP
+.B sources change <SOURCE.TOML>
+Change an existing source
+.TP
+.B sources delete <SOURCE\-NAME>
+Delete a package source.
+.UNINDENT
+.sp
+status show                         Show API server status.
+
+.SH EDIT A BLUEPRINT
+.sp
+Start out by listing the available blueprints using \fBcomposer\-cli blueprints
+list\fP, pick one and save it to the local directory by running \fBcomposer\-cli
+blueprints save http\-server\fP\&. If there are no blueprints available you can
+copy one of the examples \fI\%from the test suite\fP\&.
+.sp
+Edit the file (it will be saved with a .toml extension) and change the
+description, add a package or module to it. Send it back to the server by
+running \fBcomposer\-cli blueprints push http\-server.toml\fP\&. You can verify that it was
+saved by viewing the changelog \- \fBcomposer\-cli blueprints changes http\-server\fP\&.
+.SH BUILD AN IMAGE
+.sp
+Build a \fBqcow2\fP disk image from this blueprint by running \fBcomposer\-cli
+compose start http\-server qcow2\fP\&. It will print a UUID that you can use to
+keep track of the build. You can also cancel the build if needed.
+.sp
+The available types of images is displayed by \fBcomposer\-cli compose types\fP\&.
+Currently this consists of: ami, ext4\-filesystem, live\-iso, partitioned\-disk,
+qcow2, tar, vhd, vmdk
+.SH MONITOR THE BUILD STATUS
+.sp
+Monitor it using \fBcomposer\-cli compose status\fP, which will show the status of
+all the builds on the system. You can view the end of the anaconda build logs
+once it is in the \fBRUNNING\fP state using \fBcomposer\-cli compose log UUID\fP
+where UUID is the UUID returned by the start command.
+.sp
+Once the build is in the \fBFINISHED\fP state you can download the image.
+.SH DOWNLOAD THE IMAGE
+.sp
+Downloading the final image is done with \fBcomposer\-cli compose image UUID\fP and it will
+save the qcow2 image as \fBUUID\-disk.qcow2\fP which you can then use to boot a VM like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+qemu\-kvm \-\-name test\-image \-m 1024 \-hda ./UUID\-disk.qcow2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH AUTHOR
+Weldr Team
+.SH COPYRIGHT
+2018, Red Hat, Inc.
+.\" Generated by docutils manpage writer.
+.

docs/man/livemedia-creator.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "LIVEMEDIA-CREATOR" "1" "Nov 29, 2016" "26.2" "Lorax"
+.TH "LIVEMEDIA-CREATOR" "1" "Oct 24, 2018" "30.5" "Lorax"
 .SH NAME
 livemedia-creator \- Live Media Creator Documentation
 .
@@ -96,7 +96,7 @@ usage: livemedia\-creator [\-h]
                          [\-\-ram MEMORY] [\-\-vcpus VCPUS] [\-\-vnc VNC]
                          [\-\-arch ARCH] [\-\-kernel\-args KERNEL_ARGS]
                          [\-\-ovmf\-path OVMF_PATH] [\-\-virt\-uefi] [\-\-no\-kvm]
-                         [\-\-dracut\-arg DRACUT_ARGS]
+                         [\-\-with\-rng WITH_RNG] [\-\-dracut\-arg DRACUT_ARGS]
                          [\-\-live\-rootfs\-size LIVE_ROOTFS_SIZE]
                          [\-\-live\-rootfs\-keep\-size] [\-\-oci\-config OCI_CONFIG]
                          [\-\-oci\-runtime OCI_RUNTIME]
@@ -104,199 +104,289 @@ usage: livemedia\-creator [\-h]
                          [\-\-vagrantfile VAGRANTFILE] [\-\-title TITLE]
                          [\-\-project PROJECT] [\-\-releasever RELEASEVER]
                          [\-\-volid VOLID] [\-\-squashfs_args SQUASHFS_ARGS]
-                         [\-\-timeout TIMEOUT]
+                         [\-\-timeout TIMEOUT] [\-V]
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.SS Named Arguments
 .INDENT 0.0
 .TP
-.B Options:
+.B\-\-make\-iso
-.INDENT 7.0
-.TP
-.B \-\-make\-iso=False
 Build a live iso
+.sp
+Default: False
 .TP
-.B \-\-make\-disk=False
+.B\-\-make\-disk
 Build a partitioned disk image
+.sp
+Default: False
 .TP
-.B \-\-make\-fsimage=False
+.B\-\-make\-fsimage
 Build a filesystem image
+.sp
+Default: False
 .TP
-.B \-\-make\-appliance=False
+.B\-\-make\-appliance
 Build an appliance image and XML description
+.sp
+Default: False
 .TP
-.B \-\-make\-ami=False
+.B\-\-make\-ami
 Build an ami image
+.sp
+Default: False
 .TP
-.B \-\-make\-tar=False
+.B\-\-make\-tar
 Build a tar of the root filesystem
+.sp
+Default: False
 .TP
-.B \-\-make\-pxe\-live=False
+.B\-\-make\-pxe\-live
 Build a live pxe boot squashfs image
+.sp
+Default: False
 .TP
-.B \-\-make\-ostree\-live=False
+.B\-\-make\-ostree\-live
 Build a live pxe boot squashfs image of Atomic Host
+.sp
+Default: False
 .TP
-.B \-\-make\-oci=False
+.B\-\-make\-oci
 Build an Open Container Initiative image
+.sp
+Default: False
 .TP
-.B \-\-make\-vagrant=False
+.B\-\-make\-vagrant
 Build a Vagrant Box image
+.sp
+Default: False
 .TP
-.B \-\-iso
+.B\-\-iso
 Anaconda installation .iso path to use for qemu
 .TP
-.B \-\-iso\-only=False
+.B\-\-iso\-only
 Remove all iso creation artifacts except the boot.iso, combine with \-\-iso\-name to rename the boot.iso
+.sp
+Default: False
 .TP
-.B \-\-iso\-name
+.B\-\-iso\-name
 Name of output iso file for \-\-iso\-only. Default is boot.iso
 .TP
-.B \-\-ks
+.B\-\-ks
 Kickstart file defining the install.
 .TP
-.B \-\-image\-only=False
+.B\-\-image\-only
 Exit after creating fs/disk image.
+.sp
+Default: False
 .TP
-.B \-\-no\-virt=False
+.B\-\-no\-virt
 Run anaconda directly on host instead of using qemu
+.sp
+Default: False
 .TP
-.B \-\-proxy
+.B\-\-proxy
 proxy URL to use for the install
 .TP
-.B \-\-anaconda\-arg
+.B\-\-anaconda\-arg
 Additional argument to pass to anaconda (no\-virt mode). Pass once for each argument
 .TP
-.B \-\-armplatform
+.B\-\-armplatform
 the platform to use when creating images for ARM, i.e., highbank, mvebu, omap, tegra, etc.
 .TP
-.B \-\-location
+.B\-\-location
 location of iso directory tree with initrd.img and vmlinuz. Used to run qemu with a newer initrd than the iso.
 .TP
-.B \-\-logfile=./livemedia.log
+.B\-\-logfile
 Name and path for primary logfile, other logs will be created in the same directory.
+.sp
+Default: ./livemedia.log
 .TP
-.B \-\-lorax\-templates
+.B\-\-lorax\-templates
 Path to mako templates for lorax
 .TP
-.B \-\-tmp=/var/tmp
+.B\-\-tmp
 Top level temporary directory
+.sp
+Default: /var/tmp
 .TP
-.B \-\-resultdir
+.B\-\-resultdir
 Directory to copy the resulting images and iso into. Defaults to the temporary working directory
 .TP
-.B \-\-macboot=True
+.B\-\-macboot
-Undocumented
+Default: True
 .TP
-.B \-\-nomacboot=True
+.B\-\-nomacboot
-Undocumented
+Default: True
 .TP
-.B \-\-disk\-image
+.B\-\-title
-Path to existing disk image to use for creating final image.
-.TP
-.B \-\-keep\-image=False
-Keep raw disk image after .iso creation
-.TP
-.B \-\-fs\-image
-Path to existing filesystem image to use for creating final image.
-.TP
-.B \-\-image\-name
-Name of output file to create. Used for tar, fs and disk image. Default is a random name.
-.TP
-.B \-\-fs\-label=Anaconda
-Label to set on fsimage, default is \(aqAnaconda\(aq
-.TP
-.B \-\-image\-type
-Create an image with qemu\-img. See qemu\-img \-\-help for supported formats.
-.TP
-.B \-\-qemu\-arg=[]
-Arguments to pass to qemu\-img. Pass once for each argument, they will be used for ALL calls to qemu\-img.
-.TP
-.B \-\-qcow2=False
-Create qcow2 image instead of raw sparse image when making disk images.
-.TP
-.B \-\-qcow2\-arg=[]
-Arguments to pass to qemu\-img. Pass once for each argument, they will be used for ALL calls to qemu\-img.
-.TP
-.B \-\-compression=xz
-Compression binary for make\-tar. xz, lzma, gzip, and bzip2 are supported. xz is the default.
-.TP
-.B \-\-compress\-arg=[]
-Arguments to pass to compression. Pass once for each argument
-.TP
-.B \-\-app\-name
-Name of appliance to pass to template
-.TP
-.B \-\-app\-template
-Path to template to use for appliance data.
-.TP
-.B \-\-app\-file=appliance.xml
-Appliance template results file.
-.TP
-.B \-\-ram=1024
-Memory to allocate for installer in megabytes.
-.TP
-.B \-\-vcpus
-Passed to qemu \-smp command
-.TP
-.B \-\-vnc
-Passed to qemu \-display command. eg. vnc=127.0.0.1:5, default is to choose the first unused vnc port.
-.TP
-.B \-\-arch
-System arch to build for. Used to select qemu\-system\-* command. Defaults to qemu\-system\-<arch>
-.TP
-.B \-\-kernel\-args
-Additional argument to pass to the installation kernel
-.TP
-.B \-\-ovmf\-path=/usr/share/edk2/ovmf/
-Path to OVMF firmware
-.TP
-.B \-\-virt\-uefi=False
-Use OVMF firmware to boot the VM in UEFI mode
-.TP
-.B \-\-no\-kvm=False
-Skip using kvm with qemu even if it is available.
-.TP
-.B \-\-dracut\-arg
-Argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the default. (default: )
-.TP
-.B \-\-live\-rootfs\-size=0
-Size of root filesystem of live image in GiB
-.TP
-.B \-\-live\-rootfs\-keep\-size=False
-Keep the original size of root filesystem in live image
-.TP
-.B \-\-oci\-config
-config.json OCI configuration file
-.TP
-.B \-\-oci\-runtime
-runtime.json OCI configuration file
-.TP
-.B \-\-vagrant\-metadata
-optional metadata.json file
-.TP
-.B \-\-vagrantfile
-optional vagrantfile
-.TP
-.B \-\-title=Linux Live Media
 Substituted for @TITLE@ in bootloader config files
+.sp
+Default: "Linux Live Media"
 .TP
-.B \-\-project=Linux
+.B\-\-project
 substituted for @PROJECT@ in bootloader config files
+.sp
+Default: "Linux"
 .TP
-.B \-\-releasever=25
+.B\-\-releasever
 substituted for @VERSION@ in bootloader config files
+.sp
+Default: "29"
 .TP
-.B \-\-volid
+.B\-\-volid
 volume id
 .TP
-.B \-\-squashfs_args
+.B\-\-squashfs_args
 additional squashfs args
 .TP
-.B \-\-timeout
+.B\-\-timeout
 Cancel installer after X minutes
+.TP
+.B\-V
+show program\(aqs version number and exit
 .UNINDENT
+.SS disk/fs image arguments
+.INDENT 0.0
+.TP
+.B\-\-disk\-image
+Path to existing disk image to use for creating final image.
+.TP
+.B\-\-keep\-image
+Keep raw disk image after .iso creation
+.sp
+Default: False
+.TP
+.B\-\-fs\-image
+Path to existing filesystem image to use for creating final image.
+.TP
+.B\-\-image\-name
+Name of output file to create. Used for tar, fs and disk image. Default is a random name.
+.TP
+.B\-\-fs\-label
+Label to set on fsimage, default is \(aqAnaconda\(aq
+.sp
+Default: "Anaconda"
+.TP
+.B\-\-image\-type
+Create an image with qemu\-img. See qemu\-img \-\-help for supported formats.
+.TP
+.B\-\-qemu\-arg
+Arguments to pass to qemu\-img. Pass once for each argument, they will be used for ALL calls to qemu\-img.
+.sp
+Default: []
+.TP
+.B\-\-qcow2
+Create qcow2 image instead of raw sparse image when making disk images.
+.sp
+Default: False
+.TP
+.B\-\-qcow2\-arg
+Arguments to pass to qemu\-img. Pass once for each argument, they will be used for ALL calls to qemu\-img.
+.sp
+Default: []
+.TP
+.B\-\-compression
+Compression binary for make\-tar. xz, lzma, gzip, and bzip2 are supported. xz is the default.
+.sp
+Default: "xz"
+.TP
+.B\-\-compress\-arg
+Arguments to pass to compression. Pass once for each argument
+.sp
+Default: []
+.UNINDENT
+.SS appliance arguments
+.INDENT 0.0
+.TP
+.B\-\-app\-name
+Name of appliance to pass to template
+.TP
+.B\-\-app\-template
+Path to template to use for appliance data.
+.TP
+.B\-\-app\-file
+Appliance template results file.
+.sp
+Default: "appliance.xml"
+.UNINDENT
+.SS qemu arguments
+.INDENT 0.0
+.TP
+.B\-\-ram
+Memory to allocate for installer in megabytes.
+.sp
+Default: 2048
+.TP
+.B\-\-vcpus
+Passed to qemu \-smp command
+.TP
+.B\-\-vnc
+Passed to qemu \-display command. eg. vnc=127.0.0.1:5, default is to choose the first unused vnc port.
+.TP
+.B\-\-arch
+System arch to build for. Used to select qemu\-system\-* command. Defaults to qemu\-system\-<arch>
+.TP
+.B\-\-kernel\-args
+Additional argument to pass to the installation kernel
+.TP
+.B\-\-ovmf\-path
+Path to OVMF firmware
+.sp
+Default: "/usr/share/edk2/ovmf/"
+.TP
+.B\-\-virt\-uefi
+Use OVMF firmware to boot the VM in UEFI mode
+.sp
+Default: False
+.TP
+.B\-\-no\-kvm
+Skip using kvm with qemu even if it is available.
+.sp
+Default: False
+.TP
+.B\-\-with\-rng
+RNG device for QEMU (none for no RNG)
+.sp
+Default: "/dev/random"
+.UNINDENT
+.SS dracut arguments
+.INDENT 0.0
+.TP
+.B\-\-dracut\-arg
+Argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the default. (default: )
+.UNINDENT
+.SS pxe to live arguments
+.INDENT 0.0
+.TP
+.B\-\-live\-rootfs\-size
+Size of root filesystem of live image in GiB
+.sp
+Default: 0
+.TP
+.B\-\-live\-rootfs\-keep\-size
+Keep the original size of root filesystem in live image
+.sp
+Default: False
+.UNINDENT
+.SS OCI arguments
+.INDENT 0.0
+.TP
+.B\-\-oci\-config
+config.json OCI configuration file
+.TP
+.B\-\-oci\-runtime
+runtime.json OCI configuration file
+.UNINDENT
+.SS Vagrant arguments
+.INDENT 0.0
+.TP
+.B\-\-vagrant\-metadata
+optional metadata.json file
+.TP
+.B\-\-vagrantfile
+optional vagrantfile
 .UNINDENT
 .SH QUICKSTART
 .sp
@@ -446,10 +536,16 @@ When creating live iso\(aqs you need to have, at least, these packages in the %p
 dracut\-config\-generic
 dracut\-live
 \-dracut\-config\-rescue
-grub\-efi
+grub2\-efi
 memtest86+
 syslinux
 .UNINDENT
+.SS User created repositories
+.sp
+If you are using your own repositories and installing groups (eg. @core) make
+sure you create the repodata with groups like this \fBcreaterepo \-g
+/path/to/groups.xml /path/to/rpms\fP
+.SS Using a Proxy with repos
 .sp
 One drawback to using qemu is that it pulls the packages from the repo each
 time you run it. To speed things up you either need a local mirror of the
@@ -470,7 +566,21 @@ packages will get cached, so your kickstart url would look like:
 .UNINDENT
 .sp
 You can also add an update repo, but don\(aqt name it updates. Add \-\-proxy to it
-as well.
+as well. You can use all of the \fI\%kickstart commands\fP in your kickstart. Make sure there
+is only one \fBurl\fP command, other repos have to use the \fBrepo\fP command and cannot be
+named \fBupdates\fP which is reserved for Anaconda\(aqs use. eg.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+url \-\-url=PRIMARY\-REPO\-URL \-\-proxy=PROXY\-URL
+repo \-\-name="repo1" \-\-baseurl=FIRST\-REPO\-URL \-\-proxy=PROXY\-URL
+repo \-\-name="repo2" \-\-baseurl=SECOND\-REPO_URL \-\-proxy=PROXY\-URL
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH ANACONDA IMAGE INSTALL (NO-VIRT)
 .sp
 You can create images without using qemu by passing \fB\-\-no\-virt\fP on the
@@ -666,8 +776,9 @@ As of lorax version 22.2 you can use livemedia\-creator and anaconda version
 \fBNOTE:\fP
 .INDENT 0.0
 .INDENT 3.5
-As of mock 1.2.12 you no longer need to bind mount \fB/dev/\fP, loop devices are setup
+As of mock 1.3.4 you need to use \fB\-\-old\-chroot\fP with mock. Mock now defaults to using systemd\-nspawn
-as part of the standard mock \fB/dev/\fP creation.
+which cannot create the needed loop device nodes. Passing \fB\-\-old\-chroot\fP will use the old system
+where \fB/dev/loop*\fP is setup for you.
 .UNINDENT
 .UNINDENT
 .sp
@@ -712,10 +823,10 @@ Make sure tar and dracut\-network are in the %packages section and that the
 \fBurl points to the correct repo\fP
 .IP 7. 3
 Init the mock
-\fBmock \-r fedora\-rawhide\-x86_64 \-\-init\fP
+\fBmock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-init\fP
 .IP 8. 3
 Copy the kickstart inside the mock
-\fBmock \-r fedora\-rawhide\-x86_64 \-\-copyin ./fedora\-minimal.ks /root/\fP
+\fBmock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-copyin ./fedora\-minimal.ks /root/\fP
 .IP 9. 3
 Make a minimal iso:
 .INDENT 3.0
@@ -723,7 +834,7 @@ Make a minimal iso:
 .sp
 .nf
 .ft C
-mock \-r fedora\-rawhide\-x86_64 \-\-chroot \-\- livemedia\-creator \-\-no\-virt \e
+mock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-chroot \-\- livemedia\-creator \-\-no\-virt \e
 \-\-resultdir=/results/try\-1 \-\-logfile=/results/logs/try\-1/try\-1.log \e
 \-\-make\-iso \-\-ks /root/fedora\-minimal.ks
 .ft P
@@ -783,13 +894,13 @@ Make sure tar and dracut\-network are in the %packages section and that the
 \fBurl points to the correct repo\fP
 .IP 7. 3
 Init the mock
-\fBmock \-r fedora\-rawhide\-x86_64 \-\-init\fP
+\fBmock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-init\fP
 .IP 8. 3
 Copy the kickstart inside the mock
-\fBmock \-r fedora\-rawhide\-x86_64 \-\-copyin ./fedora\-minimal.ks /root/\fP
+\fBmock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-copyin ./fedora\-minimal.ks /root/\fP
 .IP 9. 3
 Copy the Anaconda boot.iso inside the mock
-\fBmock \-r fedora\-rawhide\-x86_64 \-\-copyin ./boot.iso /root/\fP
+\fBmock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-copyin ./boot.iso /root/\fP
 .IP 10. 3
 Make a minimal iso:
 .INDENT 3.0
@@ -797,7 +908,7 @@ Make a minimal iso:
 .sp
 .nf
 .ft C
-mock \-r fedora\-rawhide\-x86_64 \-\-chroot \-\- livemedia\-creator \e
+mock \-r fedora\-rawhide\-x86_64 \-\-old\-chroot \-\-chroot \-\- livemedia\-creator \e
 \-\-resultdir=/results/try\-1 \-\-logfile=/results/logs/try\-1/try\-1.log \e
 \-\-make\-iso \-\-ks /root/fedora\-minimal.ks \-\-iso /root/boot.iso
 .ft P
@@ -986,6 +1097,24 @@ When creating a new kickstart it is helpful to use vnc so that you can monitor
 the installation as it happens, and if it gets stuck without lmc detecting the
 problem you can switch to tty1 and examine the system directly.
 .sp
+If you suspect problems with %pre or %post sections you can redirect the output
+to the terminal and examine it by logging into the VM. eg.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+%pre
+chvt
+exec < /dev/tty3 > /dev/tty3 2>/dev/tty3
+#do stuff
+echo hello world
+%end
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
 If it does get stuck the best way to cancel is to use kill \-9 on the qemu pid,
 lmc will detect that the process died and cleanup.
 .sp
@@ -1017,8 +1146,8 @@ anaconda\-devel\-list mailing list, and \fI\%on github\fP
 Feedback, enhancements and bugs are welcome.  You can use \fI\%bugzilla\fP to
 report bugs against the lorax component.
 .SH AUTHOR
-Anaconda Team
+Weldr Team
 .SH COPYRIGHT
-2015, Red Hat, Inc.
+2018, Red Hat, Inc.
 .\" Generated by docutils manpage writer.
 .

docs/man/lorax-composer.1

@@ -0,0 +1,504 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "LORAX-COMPOSER" "1" "Oct 24, 2018" "30.5" "Lorax"
+.SH NAME
+lorax-composer \- Lorax Composer Documentation
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.INDENT 0.0
+.TP
+.B Authors
+Brian C. Lane <\fI\%bcl@redhat.com\fP>
+.UNINDENT
+.sp
+\fBlorax\-composer\fP is an API server that allows you to build disk images using
+\fI\%Blueprints\fP to describe the package versions to be installed into the image.
+It is compatible with the Weldr project\(aqs bdcs\-api REST protocol. More
+information on Weldr can be found \fI\%on the Weldr blog\fP\&.
+.sp
+Behind the scenes it uses \fI\%livemedia\-creator\fP and
+\fI\%Anaconda\fP to handle the
+installation and configuration of the images.
+.SH IMPORTANT THINGS TO NOTE
+.INDENT 0.0
+.IP \(bu 2
+SELinux must be in Permissive mode. Anaconda requires SELinux be in permissive mode
+for image creation to work correctly. You can either edit the setting in the
+\fB/etc/sysconfig/selinux\fP file, or run \fBsetenforce 0\fP before starting lorax\-composer.
+.IP \(bu 2
+All image types lock the root account, except for live\-iso. You will need to either
+use one of the \fI\%Customizations\fP methods for setting a ssh key/password, install a
+package that creates a user, or use something like \fIcloud\-init\fP to setup access at
+boot time.
+.UNINDENT
+.SH INSTALLATION
+.sp
+The best way to install \fBlorax\-composer\fP is to use \fBsudo dnf install
+lorax\-composer composer\-cli\fP, this will setup the weldr user and install the
+systemd socket activation service. You will then need to enable it with \fBsudo
+systemctl enable lorax\-composer.socket && sudo systemctl start
+lorax\-composer.socket\fP\&. This will leave the server off until the first request
+is made. Systemd will then launch the server and it will remain running until
+the system is rebooted. This will cause some delay in responding to the first
+request from the UI or \fIcomposer\-cli\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+If you want lorax\-composer to respond immediately to the first request you can
+start and enable \fIlorax\-composer.service\fP instead of \fIlorax\-composer.socket\fP
+.UNINDENT
+.UNINDENT
+.SH QUICKSTART
+.INDENT 0.0
+.IP 1. 3
+Create a \fBweldr\fP user and group by running \fBuseradd weldr\fP
+.IP 2. 3
+Remove any pre\-existing socket directory with \fBrm \-rf /run/weldr/\fP
+A new directory with correct permissions will be created the first time the server runs.
+.IP 3. 3
+Enable the socket activation with \fBsystemctl enable lorax\-composer.socket
+&& sudo systemctl start lorax\-composer.socket\fP\&.
+.UNINDENT
+.sp
+NOTE: You can also run it directly with \fBlorax\-composer /path/to/blueprints\fP\&.  However,
+\fBlorax\-composer\fP does not react well to being started both on the command line and via
+socket activation at the same time.  It is therefore recommended that you run it directly
+on the command line only for testing or development purposes.  For real use or development
+of other projects that simply use the API, you should stick to socket activation only.
+.sp
+The \fB/path/to/blueprints/\fP directory is where the blueprints\(aq git repo will
+be created, and all the blueprints created with the \fB/api/v0/blueprints/new\fP
+route will be stored.  If there are blueprint \fB\&.toml\fP files in the top level
+of the directory they will be imported into the blueprint git storage when
+\fBlorax\-composer\fP starts.
+.SH LOGS
+.sp
+Logs are stored under \fB/var/log/lorax\-composer/\fP and include all console
+messages as well as extra debugging info and API requests.
+.SH SECURITY
+.sp
+Some security related issues that you should be aware of before running \fBlorax\-composer\fP:
+.INDENT 0.0
+.IP \(bu 2
+One of the API server threads needs to retain root privileges in order to run Anaconda.
+.IP \(bu 2
+SELinux must be set to Permissive or disabled to allow \fBlivemedia\-creator\fP to run Anaconda.
+.IP \(bu 2
+Only allow authorized users access to the \fBweldr\fP group and socket.
+.UNINDENT
+.sp
+Since Anaconda kickstarts are used there is the possibility that a user could
+inject commands into a blueprint that would result in the kickstart executing
+arbitrary code on the host.  Only authorized users should be allowed to build
+images using \fBlorax\-composer\fP\&.
+.SH LORAX-COMPOSER CMDLINE ARGUMENTS
+.sp
+Lorax Composer API Server
+
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+usage: lorax\-composer [\-h] [\-\-socket SOCKET] [\-\-user USER] [\-\-group GROUP]
+                      [\-\-log LOG] [\-\-mockfiles MOCKFILES]
+                      [\-\-sharedir SHAREDIR] [\-V] [\-c CONFIG]
+                      [\-\-releasever STRING] [\-\-tmp TMP] [\-\-proxy PROXY]
+                      BLUEPRINTS
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Positional Arguments
+.INDENT 0.0
+.TP
+.BBLUEPRINTS
+Path to the blueprints
+.UNINDENT
+.SS Named Arguments
+.INDENT 0.0
+.TP
+.B\-\-socket
+Path to the socket file to listen on
+.sp
+Default: "/run/weldr/api.socket"
+.TP
+.B\-\-user
+User to use for reduced permissions
+.sp
+Default: "weldr"
+.TP
+.B\-\-group
+Group to set ownership of the socket to
+.sp
+Default: "weldr"
+.TP
+.B\-\-log
+Path to logfile (/var/log/lorax\-composer/composer.log)
+.sp
+Default: "/var/log/lorax\-composer/composer.log"
+.TP
+.B\-\-mockfiles
+Path to JSON files used for /api/mock/ paths (/var/tmp/bdcs\-mockfiles/)
+.sp
+Default: "/var/tmp/bdcs\-mockfiles/"
+.TP
+.B\-\-sharedir
+Directory containing all the templates. Overrides config file sharedir
+.TP
+.B\-V
+show program\(aqs version number and exit
+.sp
+Default: False
+.TP
+.B\-c, \-\-config
+Path to lorax\-composer configuration file.
+.sp
+Default: "/etc/lorax/composer.conf"
+.TP
+.B\-\-releasever
+Release version to use for $releasever in dnf repository urls
+.TP
+.B\-\-tmp
+Top level temporary directory
+.sp
+Default: "/var/tmp"
+.TP
+.B\-\-proxy
+Set proxy for DNF, overrides configuration file setting.
+.UNINDENT
+.SH HOW IT WORKS
+.sp
+The server runs as root, and as \fBweldr\fP\&. Communication with it is via a unix
+domain socket (\fB/run/weldr/api.socket\fP by default). The directory and socket
+are owned by \fBroot:weldr\fP so that any user in the \fBweldr\fP group can use the API
+to control \fBlorax\-composer\fP\&.
+.sp
+At startup the server will check for the correct permissions and
+ownership of a pre\-existing directory, or it will create a new one if it
+doesn\(aqt exist.  The socket path and group owner\(aqs name can be changed from the
+cmdline by passing it the \fB\-\-socket\fP and \fB\-\-group\fP arguments.
+.sp
+It will then drop root privileges for the API thread and run as the \fBweldr\fP
+user. The queue and compose thread still runs as root because it needs to be
+able to mount/umount files and run Anaconda.
+.SH COMPOSING IMAGES
+.sp
+The \fI\%welder\-web\fP GUI project can be used to construct
+blueprints and create composes using a web browser.
+.sp
+Or use the command line with \fI\%composer\-cli\fP\&.
+.SH BLUEPRINTS
+.sp
+Blueprints are simple text files in \fI\%TOML\fP format that describe
+which packages, and what versions, to install into the image. They can also define a limited set
+of customizations to make to the final image.
+.sp
+Example blueprints can be found in the \fBlorax\-composer\fP \fI\%test suite\fP, with a simple one
+looking like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+name = "base"
+description = "A base system with bash"
+version = "0.0.1"
+
+[[packages]]
+name = "bash"
+version = "4.4.*"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBname\fP field is the name of the blueprint. It can contain spaces, but they will be converted to \fB\-\fP
+when it is written to disk. It should be short and descriptive.
+.sp
+\fBdescription\fP can be a longer description of the blueprint, it is only used for display purposes.
+.sp
+\fBversion\fP is a \fI\%semver compatible\fP version number. If
+a new blueprint is uploaded with the same \fBversion\fP the server will
+automatically bump the PATCH level of the \fBversion\fP\&. If the \fBversion\fP
+doesn\(aqt match it will be used as is. eg. Uploading a blueprint with \fBversion\fP
+set to \fB0.1.0\fP when the existing blueprint \fBversion\fP is \fB0.0.1\fP will
+result in the new blueprint being stored as \fBversion 0.1.0\fP\&.
+.SS [[packages]] and [[modules]]
+.sp
+These entries describe the package names and matching version glob to be installed into the image.
+.sp
+The names must match the names exactly, and the versions can be an exact match
+or a filesystem\-like glob of the version using \fB*\fP wildcards and \fB?\fP
+character matching.
+.sp
+NOTE: As of lorax\-composer\-29.2\-1 the versions are not used for depsolving,
+that is planned for a future release. And currently there are no differences
+between \fBpackages\fP and \fBmodules\fP in \fBlorax\-composer\fP\&.
+.SS [[groups]]
+.sp
+These entries describe a group of packages to be installed into the image.  Package groups are
+defined in the repository metadata.  Each group has a descriptive name used primarily for display
+in user interfaces and an ID more commonly used in kickstart files.  Here, the ID is the expected
+way of listing a group.
+.sp
+Groups have three different ways of categorizing their packages:  mandatory, default, and optional.
+For purposes of blueprints, mandatory and default packages will be installed.  There is no mechanism
+for selecting optional packages.
+.SS Customizations
+.sp
+The \fB[[customizations]]\fP section can be used to configure the hostname of the final image. eg.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[[customizations]]
+hostname = "baseimage"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS [[customizations.sshkey]]
+.sp
+Set an existing user\(aqs ssh key in the final image:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[[customizations.sshkey]]
+user = "root"
+key = "PUBLIC SSH KEY"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The key will be added to the user\(aqs authorized_keys file.
+.SS [[customizations.user]]
+.sp
+Add a user to the image, and/or set their ssh key.
+All fields for this section are optional except for the \fBname\fP, here is a complete example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[[customizations.user]]
+name = "admin"
+description = "Administrator account"
+password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."
+key = "PUBLIC SSH KEY"
+home = "/srv/widget/"
+shell = "/usr/bin/bash"
+groups = ["widget", "users", "wheel"]
+uid = 1200
+gid = 1200
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the password starts with \fB$6$\fP, \fB$5$\fP, or \fB$2b$\fP it will be stored as
+an encrypted password. Otherwise it will be treated as a plain text password.
+.SS [[customizations.group]]
+.sp
+Add a group to the image. \fBname\fP is required and \fBgid\fP is optional:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[[customizations.group]]
+name = "widget"
+gid = 1130
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH ADDING OUTPUT TYPES
+.sp
+\fBlivemedia\-creator\fP supports a large number of output types, and only some of
+these are currently available via \fBlorax\-composer\fP\&. To add a new output type to
+lorax\-composer a kickstart file needs to be added to \fB\&./share/composer/\fP\&. The
+name of the kickstart is what will be used by the \fB/compose/types\fP route, and the
+\fBcompose_type\fP field of the POST to start a compose. It also needs to have
+code added to the \fBpylorax.api.compose.compose_args()\fP function. The
+\fB_MAP\fP entry in this function defines what lorax\-composer will pass to
+\fBpylorax.installer.novirt_install()\fP when it runs the compose.  When the
+compose is finished the output files need to be copied out of the build
+directory (\fB/var/lib/lorax/composer/results/<UUID>/compose/\fP),
+\fBpylorax.api.compose.move_compose_results()\fP handles this for each type.
+You should move them instead of copying to save space.
+.sp
+If the new output type does not have support in livemedia\-creator it should be
+added there first. This will make the output available to the widest number of
+users.
+.SS Example: Add partitioned disk support
+.sp
+Partitioned disk support is something that livemedia\-creator already supports
+via the \fB\-\-make\-disk\fP cmdline argument. To add this to lorax\-composer it
+needs 3 things:
+.INDENT 0.0
+.IP \(bu 2
+A \fBpartitioned\-disk.ks\fP file in \fB\&./share/composer/\fP
+.IP \(bu 2
+A new entry in the _MAP in \fBpylorax.api.compose.compose_args()\fP
+.IP \(bu 2
+Add a bit of code to \fBpylorax.api.compose.move_compose_results()\fP to move the disk image from
+the compose directory to the results directory.
+.UNINDENT
+.sp
+The \fBpartitioned\-disk.ks\fP is pretty similar to the example minimal kickstart
+in \fB\&./docs/fedora\-minimal.ks\fP\&. You should remove the \fBurl\fP and \fBrepo\fP
+commands, they will be added by the compose process. Make sure the bootloader
+packages are included in the \fB%packages\fP section at the end of the kickstart,
+and you will want to leave off the \fB%end\fP so that the compose can append the
+list of packages from the blueprint.
+.sp
+The new \fB_MAP\fP entry should be a copy of one of the existing entries, but with \fBmake_disk\fP set
+to \fBTrue\fP\&. Make sure that none of the other \fBmake_*\fP options are \fBTrue\fP\&. The \fBimage_name\fP is
+what the name of the final image will be.
+.sp
+\fBmove_compose_results()\fP can be as simple as moving the output file into
+the results directory, or it could do some post\-processing on it. The end of
+the function should always clean up the \fB\&./compose/\fP directory, removing any
+unneeded extra files. This is especially true for the \fBlive\-iso\fP since it produces
+the contents of the iso as well as the boot.iso itself.
+.SH PACKAGE SOURCES
+.sp
+By default lorax\-composer uses the host\(aqs configured repositories. It copies
+the \fB*.repo\fP files from \fB/etc/yum.repos.d/\fP into
+\fB/var/lib/lorax/composer/repos.d/\fP at startup, these are immutable system
+repositories and cannot be deleted or changed. If you want to add additional
+repos you can put them into \fB/var/lib/lorax/composer/repos.d/\fP or use the
+\fB/api/v0/projects/source/*\fP API routes to create them.
+.sp
+The new source can be added by doing a POST to the \fB/api/v0/projects/source/new\fP
+route using JSON (with \fIContent\-Type\fP header set to \fIapplication/json\fP) or TOML
+(with it set to \fItext/x\-toml\fP).  The format of the source looks like this (in
+TOML):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+name = "custom\-source\-1"
+url = "https://url/path/to/repository/"
+type = "yum\-baseurl"
+proxy = "https://proxy\-url/"
+check_ssl = true
+check_gpg = true
+gpgkey_urls = ["https://url/path/to/gpg\-key"]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBproxy\fP and \fBgpgkey_urls\fP entries are optional. All of the others are required. The supported
+types for the urls are:
+.INDENT 0.0
+.IP \(bu 2
+\fByum\-baseurl\fP is a URL to a yum repository.
+.IP \(bu 2
+\fByum\-mirrorlist\fP is a URL for a mirrorlist.
+.IP \(bu 2
+\fByum\-metalink\fP is a URL for a metalink.
+.UNINDENT
+.sp
+If \fBcheck_ssl\fP is true the https certificates must be valid. If they are self\-signed you can either set
+this to false, or add your Certificate Authority to the host system.
+.sp
+If \fBcheck_gpg\fP is true the GPG key must either be installed on the host system, or \fBgpgkey_urls\fP
+should point to it.
+.sp
+You can edit an existing source (other than system sources), by doing a POST to the \fBnew\fP route
+with the new version of the source. It will overwrite the previous one.
+.sp
+A list of existing sources is available from \fB/api/v0/projects/source/list\fP, and detailed info
+on a source can be retrieved with the \fB/api/v0/projects/source/info/<source\-name>\fP route. By default
+it returns JSON but it can also return TOML if \fB?format=toml\fP is added to the request.
+.sp
+Non\-system sources can be deleted by doing a \fBDELETE\fP request to the
+\fB/api/v0/projects/source/delete/<source\-name>\fP route.
+.sp
+The documentation for the source API routes can be \fI\%found here\fP
+.sp
+The configured sources are used for all blueprint depsolve operations, and for composing images.
+When adding additional sources you must make sure that the packages in the source do not
+conflict with any other package sources, otherwise depsolving will fail.
+.SS DVD ISO Package Source
+.sp
+In some situations the system may want to \fIonly\fP use a DVD iso as the package
+source, not the repos from the network. \fBlorax\-composer\fP and \fBanaconda\fP
+understand \fBfile://\fP URLs so you can mount an iso on the host, and replace the
+system repo files with a configuration file pointing to the DVD.
+.INDENT 0.0
+.IP \(bu 2
+Stop the \fBlorax\-composer.service\fP if it is running
+.IP \(bu 2
+Move the repo files in \fB/etc/yum.repos.d/\fP someplace safe
+.IP \(bu 2
+Create a new \fBiso.repo\fP file in \fB/etc/yum.repos.d/\fP:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[iso]
+name=iso
+baseurl=file:///mnt/iso/
+enabled=1
+gpgcheck=1
+gpgkey=file:///mnt/iso/RPM\-GPG\-KEY\-redhat\-release
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+Remove all the cached repo files from \fB/var/lib/lorax/composer/repos/\fP
+.IP \(bu 2
+Restart the \fBlorax\-composer.service\fP
+.IP \(bu 2
+Check the output of \fBcomposer\-cli status show\fP for any output specific depsolve errors.
+For example, the DVD usually does not include \fBgrub2\-efi\-*\-cdboot\-*\fP so the live\-iso image
+type will not be available.
+.UNINDENT
+.sp
+If you want to \fIadd\fP the DVD source to the existing sources you can do that by
+mounting the iso and creating a source file to point to it as described in the
+\fI\%Package Sources\fP documentation.  In that case there is no need to remove the other
+sources from \fB/etc/yum.repos.d/\fP or clear the cached repos.
+.SH AUTHOR
+Weldr Team
+.SH COPYRIGHT
+2018, Red Hat, Inc.
+.\" Generated by docutils manpage writer.
+.

docs/man/lorax.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "LORAX" "1" "Nov 29, 2016" "26.2" "Lorax"
+.TH "LORAX" "1" "Oct 24, 2018" "30.5" "Lorax"
 .SH NAME
 lorax \- Lorax Documentation
 .
@@ -66,123 +66,181 @@ usage: lorax [\-h] \-p PRODUCT \-v VERSION \-r RELEASE [\-s REPOSITORY]
              [\-\-add\-arch\-template ADD_ARCH_TEMPLATES]
              [\-\-add\-arch\-template\-var ADD_ARCH_TEMPLATE_VARS] [\-\-noverify]
              [\-\-sharedir SHAREDIR] [\-\-enablerepo [repo]]
-             [\-\-disablerepo [repo]] [\-\-rootfs\-size ROOTFS_SIZE] [\-V]
+             [\-\-disablerepo [repo]] [\-\-rootfs\-size ROOTFS_SIZE]
+             [\-\-noverifyssl] [\-\-dnfplugin DNFPLUGINS]
+             [\-\-dracut\-arg DRACUT_ARGS] [\-V]
              OUTPUTDIR
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.SS Positional Arguments
 .INDENT 0.0
 .TP
-.B Positional arguments:
+.BOUTPUTDIR
-.INDENT 7.0
-.TP
-.Boutputdir
 Output directory
 .UNINDENT
+.SS Named Arguments
+.INDENT 0.0
 .TP
-.B Options:
+.B\-V
-.INDENT 7.0
-.TP
-.B \-p\fP,\fB  \-\-product
-product name
-.TP
-.B \-v\fP,\fB  \-\-version
-version identifier
-.TP
-.B \-r\fP,\fB  \-\-release
-release information
-.TP
-.B \-s=[]\fP,\fB  \-\-source=[]
-source repository (may be listed multiple times)
-.TP
-.B \-\-repo=[]
-source dnf repository file
-.TP
-.B \-m=[]\fP,\fB  \-\-mirrorlist=[]
-mirrorlist repository (may be listed multiple times)
-.TP
-.B \-t\fP,\fB  \-\-variant
-variant name
-.TP
-.B \-b=your distribution provided bug reporting tool\fP,\fB  \-\-bugurl=your distribution provided bug reporting tool
-bug reporting URL for the product
-.TP
-.B \-\-isfinal=False
-Undocumented
-.TP
-.B \-c=/etc/lorax/lorax.conf\fP,\fB  \-\-config=/etc/lorax/lorax.conf
-config file
-.TP
-.B \-\-proxy
-repo proxy url:port
-.TP
-.B \-i=[]\fP,\fB  \-\-installpkgs=[]
-package glob to install before runtime\-install.tmpl runs. (may be listed multiple times)
-.TP
-.B \-e=[]\fP,\fB  \-\-excludepkgs=[]
-package glob to remove before runtime\-install.tmpl runs. (may be listed multiple times)
-.TP
-.B \-\-buildarch
-build architecture
-.TP
-.B \-\-volid
-volume id
-.TP
-.B \-\-macboot=True
-Undocumented
-.TP
-.B \-\-nomacboot=True
-Undocumented
-.TP
-.B \-\-noupgrade=True
-Undocumented
-.TP
-.B \-\-logfile=./lorax.log
-Path to logfile
-.TP
-.B \-\-tmp=/var/tmp
-Top level temporary directory
-.TP
-.B \-\-cachedir
-DNF cache directory. Default is a temporary dir.
-.TP
-.B \-\-workdir
-Work directory, overrides \-\-tmp. Default is a temporary dir under /var/tmp
-.TP
-.B \-\-force=False
-Run even when the destination directory exists
-.TP
-.B \-\-add\-template=[]
-Additional template for runtime image
-.TP
-.B \-\-add\-template\-var=[]
-Set variable for runtime image template
-.TP
-.B \-\-add\-arch\-template=[]
-Additional template for architecture\-specific image
-.TP
-.B \-\-add\-arch\-template\-var=[]
-Set variable for architecture\-specific image
-.TP
-.B \-\-noverify=True
-Do not verify the install root
-.TP
-.B \-\-sharedir
-Directory containing all the templates. Overrides config file sharedir
-.TP
-.B \-\-enablerepo=[]
-Names of repos to enable
-.TP
-.B \-\-disablerepo=[]
-Names of repos to disable
-.TP
-.B \-\-rootfs\-size=2
-Size of root filesystem in GiB. Defaults to 2.
-.TP
-.B \-V
 show program\(aqs version number and exit
 .UNINDENT
+.SS required arguments
+.INDENT 0.0
+.TP
+.B\-p, \-\-product
+product name
+.TP
+.B\-v, \-\-version
+version identifier
+.TP
+.B\-r, \-\-release
+release information
+.TP
+.B\-s, \-\-source
+source repository (may be listed multiple times)
+.sp
+Default: []
+.TP
+.B\-\-repo
+source dnf repository file
+.sp
+Default: []
+.UNINDENT
+.SS Named Arguments
+.INDENT 0.0
+.TP
+.B\-m, \-\-mirrorlist
+mirrorlist repository (may be listed multiple times)
+.sp
+Default: []
+.TP
+.B\-t, \-\-variant
+variant name
+.sp
+Default: ""
+.TP
+.B\-b, \-\-bugurl
+bug reporting URL for the product
+.sp
+Default: "your distribution provided bug reporting tool"
+.TP
+.B\-\-isfinal
+Default: False
+.TP
+.B\-c, \-\-config
+config file
+.sp
+Default: "/etc/lorax/lorax.conf"
+.TP
+.B\-\-proxy
+repo proxy url:port
+.TP
+.B\-i, \-\-installpkgs
+package glob to install before runtime\-install.tmpl runs. (may be listed multiple times)
+.sp
+Default: []
+.TP
+.B\-e, \-\-excludepkgs
+package glob to remove before runtime\-install.tmpl runs. (may be listed multiple times)
+.sp
+Default: []
+.TP
+.B\-\-buildarch
+build architecture
+.TP
+.B\-\-volid
+volume id
+.TP
+.B\-\-macboot
+Default: True
+.TP
+.B\-\-nomacboot
+Default: True
+.TP
+.B\-\-noupgrade
+Default: True
+.TP
+.B\-\-logfile
+Path to logfile
+.sp
+Default: ./lorax.log
+.TP
+.B\-\-tmp
+Top level temporary directory
+.sp
+Default: "/var/tmp"
+.TP
+.B\-\-cachedir
+DNF cache directory. Default is a temporary dir.
+.TP
+.B\-\-workdir
+Work directory, overrides \-\-tmp. Default is a temporary dir under /var/tmp
+.TP
+.B\-\-force
+Run even when the destination directory exists
+.sp
+Default: False
+.TP
+.B\-\-add\-template
+Additional template for runtime image
+.sp
+Default: []
+.TP
+.B\-\-add\-template\-var
+Set variable for runtime image template
+.sp
+Default: []
+.TP
+.B\-\-add\-arch\-template
+Additional template for architecture\-specific image
+.sp
+Default: []
+.TP
+.B\-\-add\-arch\-template\-var
+Set variable for architecture\-specific image
+.sp
+Default: []
+.TP
+.B\-\-noverify
+Do not verify the install root
+.sp
+Default: True
+.TP
+.B\-\-sharedir
+Directory containing all the templates. Overrides config file sharedir
+.TP
+.B\-\-enablerepo
+Names of repos to enable
+.sp
+Default: []
+.TP
+.B\-\-disablerepo
+Names of repos to disable
+.sp
+Default: []
+.TP
+.B\-\-rootfs\-size
+Size of root filesystem in GiB. Defaults to 2.
+.sp
+Default: 2
+.TP
+.B\-\-noverifyssl
+Do not verify SSL certificates
+.sp
+Default: False
+.TP
+.B\-\-dnfplugin
+Enable a DNF plugin by name/glob, or * to enable all of them.
+.sp
+Default: []
+.UNINDENT
+.SS dracut arguments
+.INDENT 0.0
+.TP
+.B\-\-dracut\-arg
+Argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the default. (default: )
 .UNINDENT
 .SH QUICKSTART
 .sp
@@ -209,6 +267,12 @@ override the ones in the distribution repositories.
 .sp
 Under \fB\&./results/\fP will be the release tree files: .discinfo, .treeinfo, everything that
 goes onto the boot.iso, the pxeboot directory, and the boot.iso under \fB\&./images/\fP\&.
+.SH RUNNING INSIDE OF MOCK
+.sp
+If you are using lorax with mock v1.3.4 or later you will need to pass
+\fB\-\-old\-chroot\fP to mock. Mock now defaults to using systemd\-nspawn which cannot
+create the needed loop device nodes. Passing \fB\-\-old\-chroot\fP will use the old
+system where \fB/dev/loop*\fP is setup for you.
 .SH HOW IT WORKS
 .sp
 Lorax uses \fI\%dnf\fP to install
@@ -244,8 +308,6 @@ installation. A number of template commands are used here:
 .IP \(bu 2
 \fBchmod\fP changes the file\(aqs mode.
 .IP \(bu 2
-\fBgconfset\fP runs gconfset.
-.IP \(bu 2
 \fBinstall\fP to install a file into the installroot.
 .IP \(bu 2
 \fBmkdir\fP makes a new directory.
@@ -304,8 +366,8 @@ and they will be used instead if their sort order is below all other directories
 allows multiple packages to ship lorax templates without conflict. You can (and probably
 should) select the specific template directory by passing \fB\-\-sharedir\fP to lorax.
 .SH AUTHOR
-Anaconda Team
+Weldr Team
 .SH COPYRIGHT
-2015, Red Hat, Inc.
+2018, Red Hat, Inc.
 .\" Generated by docutils manpage writer.
 .