NAME

appjail-image — Create, list, remove, update images and much more

SYNOPSIS

appjail image export [-f] [-c algo] [-n name] [-t tag] jail

appjail image get [-eHIpt] image [keyword ...]

appjail image import [-f] [-a arch] [-b branch] [-N ajspec-name] [-n image-name] [-t tag] [method+]path

appjail image jail [-a arch] [-t tag] -i image jail [options ...]

appjail image list [-eHIpt] [-i image] [keyword ...]

appjail image remove [-a arch] [-t tag] image

appjail image update [image]

appjail image metadata del [-f|-I] [-i] [-t tag] target keyword

appjail image metadata edit [-f|-I] target

appjail image metadata get [-f|-I] [-i] [-t tag] target keyword

appjail image metadata info [image]

appjail image metadata set [-f|-I] [-t tag] target keyword[+]=value

DESCRIPTION

The appjail image utility manages AppJail images, that is, it creates them, imports them, updates them, creates jails using them, lists them, removes them, and so on.

The options are as follows:

export [-f] [-c algo] [-n name] [-t tag] jail

Create an image using a jail. The jail must be stopped before using this subcommand.

-f: Overwrite the image if it already exists.
If this parameter is not specified, this subcommand will not allow you to continue when the image has previously been exported successfully.
-c algo: Algorithm to compress the image. If none is specified, the image is not compressed. By default, the compression algorithm specified by the IMAGE_COMPRESS parameter is used.
-n name: Image name.
By default the jail name is used.
-t tag: Export the image with the specified tag.
By default, the tag specified by the IMAGE_TAG parameter is used.

get [-eHIpt] image [keyword ...]

Get information about image, that is, the keyword that represent the information to be obtained. Multiple keywords can be specified, which are displayed as a table-like interface in the order in which they are specified. If no keyword is specified, the default is name.

See KEYWORDS for a list of available keywords.

-e: Not required when using -p. The \t character is used to delimit columns, so as not to show strange values, this option shows <TAB> instead of \t in the case that a value contains the latter.
-H: Shows the name of the columns.
-I: Include empty values. By default, a minus sign is displayed when a value is empty.
-p: Columnate the list.
-t: Tabulate columns and values.

import [-f] [-a arch] [-b branch] [-N ajspec-name] [-n image-name] [-t tag] [method+]path

Import an image using an AJSPEC file.

method indicates how to get the AJSPEC file, path is used as an argument to method. See METHODS for more details.

-f: By default, an image is not re-imported if it was imported successfully and the timestamp matches the AJSPEC on the remote site, but when this parameter is specified, the process is done again regardless of the above.
-a arch: Import the image that was created for the specified architecture.
Use host (default) to use the architecture specified by the IMAGE_ARCH parameter, which is probably the same as the host. The reason for using a special keyword instead of simply using the IMAGE_ARCH parameter is for those Makejails that use an image that supports multiple architectures, but want to use the host platform instead of a hardcoded one, perhaps via an argument.
-b branch: When using a git-like method to get the appjail-ajspec(5) file, this parameter specifies the branch to use. By default no branch is specified.
-N ajspec-name: For the git and git-like methods, this parameter indicates what filename is currently used for the AJSPEC file. The default is .ajspec.
-n image-name: Image name.
If this option is not specified, the name is obtained from the AJSPEC file, but if it is not defined there, appjail image will not allow you to continue.
-t tag: Import the image with the specified tag.
By default, the tag specified by the IMAGE_TAG parameter is used.

jail [-a arch] [-t tag] -i image jail [options ...]

Create a jail using an image.

You can pass appjail-quick(1)'s options, except import+root which is already passed. In effect, this is essentially just a wrapper for that option with the portable subparameter set.

-a arch: Import the image that was created for the specified architecture.
Use host (default) to use the architecture specified by the IMAGE_ARCH parameter, which is probably the same as the host.
-t tag: Import the image with the specified tag.
-i image: Image to be imported.

list [-eHIpt] [-i image] [keyword ...]

Similar to get but shows each keyword for each image in a nice table.

-e, -H, -I, -p, -t: All of these options perform the opposite task of the options described in get.
-i image: Only show information for image.

remove [-a arch] [-t tag] image

Remove image.

When using ZFS as the backend file system, this subcommand will recursively remove all datasets including all references, such as clones. Be careful.

If -a is specified, images matching arch are removed, and if -t is specified, images matching tag are removed. Both can be supplied to match exactly. If none is specified, all images matching image are removed.

update [image]

Update all images or, if image is specified, only that one is updated.

metadata del [-f|-I] [-i] [-t tag] target keyword

Remove keyword from target.

See KEYWORDS for a list of available keywords.

[-f|-I]: Treat target as a file (-f) or as an image (-I).
-i: Don't complain when keyword does not exist.
-t tag: Image tag.

metadata edit [-f|-I] target

The program specified by the EDITOR environment variable is open to edit the AJSPEC file.

You should edit the AJSPEC file using metadata set and metadata del unless you know what you are doing.

metadata get [-f|-I] [-i] [-t tag] target keyword

Get the keyword value from target.

See KEYWORDS for a list of available keywords.

[-f|-I]: Treat target as a file (-f) or as an image (-I).
-i: Don't complain when keyword does not exist.
-t tag: Image tag.

metadata info [image]

Get information in a human-readable format from all images or just image.

metadata set [-f|-I] [-t tag] target keyword[+]=value

Configure a new or existing keyword.

If + is provided, value will be appended instead of replacing the entire value. Not all keywords accept this type of insertion.

See KEYWORDS for a list of available keywords.

[-f|-I]: Treat target as a file (-f) or as an image (-I).
-t tag: Image tag.

KEYWORDS

get, list

name: Image name.
has_metadata: Shows 1 if the image has the AJSPEC file, 0 if it does not.

metadata del, metadata get, metadata set

arch

Image architectures.

Valid are:

append: Yes

name

Image name.

Valid names are ^[a-zA-Z0-9_][a-zA-Z0-9_-]*$

append: No

tags

Image tags.

Valid tags are ^[a-zA-Z0-9_][a-zA-Z0-9._-]*$

append: Yes

timestamp:arch

Unix date on which the image is supposed to have been created or modified.

append: No

maintainer

The person or entity who is in charge of the image and everything related to it, preferably in a format such as ‘maintainer-name <email-address>’.

append: Yes

comment

One-line description.

append: No

url

Home page.

append: No

description

Long description.

append: Yes

sum:arch

Checksum.

append: No

source:arch

Sites where the image can be downloaded.

append: Yes

size:arch

Image size.

append: No

maintenance

Brief description of why this image cannot be imported.

append: No

entrypoint

Indicates the method that was used to obtain the AJSPEC file.

append: No

ajspec

AJSPEC filename.

append: No

metadata get

timestamp-human:arch: Display timestamp in a human-readable form.

METHODS

cmd: Use the output of a command as an AJSPEC file.
git: Use the AJSPEC file found in a git(1) repository.
fetch: The program specified in the IMAGE_FETCH_CMD parameter is used to get the AJSPEC file.
file: Default. Use a file on the local file system.
gh|github: Wrapper for the git method but using https://github.com/ as URL prefix.
gh-ssh|github-ssh: Wrapper for the git method but using git@github.com: as URL prefix.
gl|gitlab: Wrapper for the git method but using https://gitlab.com/ as URL prefix.
gl-ssh|gitlab-ssh: Wrapper for the git method but using git@gitlab.com: as URL prefix.
reproduce: Build a project using appjail-reproduce and use the generated appjail-ajspec(5) file. Useful for when you don't want to rely on the server to download the image.
This method accepts the appjail-reproduce syntax, so you can build a specific tag and/or for a specific architecture.

EXIT STATUS

The appjail image utility exits 0 on success, and >0 if an error occurs.

AUTHORS

Jesús Daniel Colmenares Oviedo <DtxdF@disroot.org>