347 lines
10 KiB
Groff
347 lines
10 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.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
|
|
..
|
|
.TH "COMPOSER-CLI" "1" "Jun 29, 2021" "28.14.59" "Lorax"
|
|
.SH NAME
|
|
composer-cli \- Composer Cmdline Utility Documentation
|
|
.INDENT 0.0
|
|
.TP
|
|
.B Authors
|
|
Brian C. Lane <\fI\%bcl@redhat.com\fP>
|
|
.UNINDENT
|
|
.sp
|
|
\fBcomposer\-cli\fP is an interactive tool for use with a WELDR API server,
|
|
managing blueprints, exploring available packages, and building new images.
|
|
\fIlorax\-composer <lorax\-composer.html>\fP and \fIosbuild\-composer
|
|
<https://osbuild.org>\fP both implement compatible servers.
|
|
.sp
|
|
It requires server 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
|
|
.B args
|
|
.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 (overrides server API version)
|
|
.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 [\-\-size XXXX] <BLUEPRINT> <TYPE> [<IMAGE\-NAME> <PROVIDER> <PROFILE> | <IMAGE\-NAME> <PROFILE.TOML>]
|
|
Start a compose using the selected blueprint and output type. \-\-size is in MiB.
|
|
NOTE: uploading and \-\-size are only supported by osbuild\-composer.
|
|
.TP
|
|
.B compose start\-ostree [\-\-size XXXX] [\-\-parent PARENT] [\-\-ref REF] [\-\-url url] <BLUEPRINT> <TYPE> [<IMAGE\-NAME> <PROFILE.TOML>]
|
|
Start an ostree compose using the selected blueprint and output type. Optionally start an upload. This command
|
|
is only supported by osbuild\-composer. \-\-size is in MiB.
|
|
.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.
|
|
.sp
|
|
NOTE: uploading is only available as part of the compose command
|
|
using the osbuild\-composer API server.
|
|
|
|
.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\&.
|
|
.sp
|
|
The full blueprint documentation \fI\%is here\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: alibaba, ami, ext4\-filesystem, google, live\-iso,
|
|
openstack, 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 IMAGE UPLOADS
|
|
.sp
|
|
\fBcomposer\-cli\fP can upload the images to a number of services, including AWS,
|
|
OpenStack, and vSphere. The upload can be started when the build is finished
|
|
by using \fBcomposer\-cli compose start ...\fP\&. In order to access the service you need
|
|
to pass authentication details to composer\-cli using a TOML file.
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
This is only supported when running the \fBosbuild\-composer\fP API server.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH PROVIDERS
|
|
.sp
|
|
Providers are where the images are uploaded to. You
|
|
will need to gather some provider
|
|
specific information in order to authenticate with it. Please refer to the \fBosbuild\-composer\fP
|
|
documentation for the provider specific fields. You will then create a TOML file with the
|
|
name of the provider and the settings, like this:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
provider = "aws"
|
|
|
|
[settings]
|
|
aws_access_key = "AWS Access Key"
|
|
aws_bucket = "AWS Bucket"
|
|
aws_region = "AWS Region"
|
|
aws_secret_key = "AWS Secret Key"
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Save this into an \fBaws\-credentials.toml\fP file and use it when running \fBstart\fP\&.
|
|
.SS AWS
|
|
.sp
|
|
The access key and secret key can be created by going to the
|
|
\fBIAM\->Users\->Security Credentials\fP section and creating a new access key. The
|
|
secret key will only be shown when it is first created so make sure to record
|
|
it in a secure place. The region should be the region that you want to use the
|
|
AMI in, and the bucket can be an existing bucket, or a new one, following the
|
|
normal AWS bucket naming rules. It will be created if it doesn\(aqt already exist.
|
|
.sp
|
|
When uploading the image it is first uploaded to the s3 bucket, and then
|
|
converted to an AMI. If the conversion is successful the s3 object will be
|
|
deleted. If it fails, re\-trying after correcting the problem will re\-use the
|
|
object if you have not deleted it in the meantime, speeding up the process.
|
|
.SH BUILD AN IMAGE AND UPLOAD RESULTS
|
|
.sp
|
|
With the settings stored in a TOML file:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
composer\-cli compose start example\-http\-server ami "http image" aws\-settings.toml
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
It will return the UUID of the image build. Once
|
|
the build has finished successfully it will start the upload process.
|
|
.SH DEBUGGING
|
|
.sp
|
|
There are a couple of arguments that can be helpful when debugging problems.
|
|
These are only meant for debugging and should not be used to script access to
|
|
the API. If you need to do that you can communicate with it directly in the
|
|
language of your choice.
|
|
.sp
|
|
\fB\-\-json\fP will return the server\(aqs response as a nicely formatted json output
|
|
instead of printing what the command would usually print.
|
|
.sp
|
|
\fB\-\-test=1\fP will cause a compose start to start creating an image, and then
|
|
end with a failed state.
|
|
.sp
|
|
\fB\-\-test=2\fP will cause a compose to start and then end with a finished state,
|
|
without actually composing anything.
|
|
.SH AUTHOR
|
|
Weldr Team
|
|
.SH COPYRIGHT
|
|
2018-2019, Red Hat, Inc.
|
|
.\" Generated by docutils manpage writer.
|
|
.
|