FreeBSD Manual Pages
APPJAIL-MAKEJAIL(5) File Formats Manual APPJAIL-MAKEJAIL(5) NAME appjail-makejail -- Automate the steps of creating a jail DESCRIPTION Makejail is a simple text file that automates the steps of creating a jail, generate an InitScript and a BuildScript. Makejails are processed line by line, removing comments, empty lines and including the Makejails specified by INCLUDE (if any) in a single, temporary Makejail that is responsible for executing the rest of the supported instructions. See INCLUDE for more details. Makejail files are divided in stages that can be changed using the STAGE instruction, which are actually functions as described in appjail-initscript(5), except the build stage which is not used by InitScript, but is used by the BuildScript. See appjail-makejail(1) for more details. INSTRUCTIONS ADD [--verbose] url [destination] Download and extract a tarball file from url to the jail directory or destination, a path relative to the jail directory, using the program specified by the MAKEJAIL_ADD_FETCH_CMD parameter. Use --verbose to produce a verbose output when extracting the tarball using tar(1). WORKDIR can affect this instruction. ARG name[[?]=[default-value]] Create arguments as specified by appjail-initscript(5). If no de- fault value is specified, the arguments become non-optional unless ? is used. When ? is used, the user can set a parameter to an empty value. You don't need the argument value enclosed in double quotes even when it has spaces. See CMD for how arguments are passed to the process. CLEAR [entrypoint|user|workdir|stage] Clear the value previously set by one of the following instruc- tions: ENTRYPOINT, USER, WORKDIR or STAGE. In the case of the STAGE instruction, all commands written up to this instruction and in the current stage are removed. CMD --chroot command [args ...] CMD --jaildir command [args ...] CMD [--jexec] [--noclean] [--juser username|--huser username] command [args ...] CMD --local command [args ...] CMD --local-jaildir command [args ...] CMD --local-rootdir command [args ...] This instruction uses the AppJail tokenizer best described in appjail-template(5) to execute a string with sh(1) instructions. This instruction keeps the ", ', and \ characters in the string to better emulate the behavior of sh(1). Internally, ARG and VAR (it doesn't do this by default, but does it with one of its parameters) can create variables that are passed via environment variables to the sh(1) process. OPTION overwrite OPTION start ARG name=DtxdF CMD echo "Hello, ${name}" This instruction has the advantage that it can execute virtually any shell command. CMD cd /usr/local/etc/opensearch/opensearch-security; for i in $(ls *.sample) ; do cp -p "$i" $(echo $i | sed "s|.sample||g"); done All of the above commands will be executed on the jail, not on the host, even the embedded shell commands. Remember that this command uses the AppJail tokenizer, so you can- not use an invalid (but accepted by sh(1)) shell command. For ex- ample, if you run echo "\" in a shell script, you will get the er- ror "Syntax error: Unterminated quoted string" but if you run it in a Makejail you will get "Tokenizer: ERROR [ret:-4, errno:0] <Invalid syntax (WDERRS).>." --chroot is equivalent to appjail-cmd(1) chroot. --jaildir is equivalent to appjail-cmd(1) jaildir. --jexec --noclean is equivalent to appjail-cmd(1) jexec -l. --jexec --juser is equivalent to appjail-cmd(1) jexec -U. --jexec --huser is equivalent to appjail-cmd(1) jexec -u. --local runs a command from the host but using the local directory which may be different. See INCLUDE for more details. --local-jaildir is equivalent to appjail-cmd(1) local -j. --local-rootdir is equivalent to appjail-cmd(1) local -r. COPY [--glob|--glob-left|--glob-right] [--verbose] [--jail jail] source [destination] Copy a file from the host to the jail or destination, a path rela- tive to the jail directory. WORKDIR can affect this instruction. Use --jail to copy source from another jail. Using --glob, --glob-left, --glob-right is equivalent to *source*, *source and source*, but you can't use such expressions in source. Increase the verbosity using --verbose. Note that this instruction copies the file or directory as is, that is, metadata such as file mode, uid, gid, etc., are pre- served. DESTROY [--force] [--with-all-dependents] jail Stop and destroy jail. --force is equivalent to appjail-jail(1) destroy -f. --with-all-dependents is equivalent to appjail-jail(1) destroy -R. DEVICE rulespec ... Apply (see appjail-devfs(1) apply) and add (see appjail-devfs(1) set) a new DEVFS rule. ENTRYPOINT program When running a program using RUN, the program specified by this instruction is used implicitly, for example: ENTRYPOINT python3.10 RUN script.py ENV name[=value] Environment variables used by RUN. Additional environment vari- ables can be passed using the -V parameter supported by appjail-apply(1), appjail-makejail(1), appjail-start(1), appjail-stop(1) and appjail-run(1). EXEC [--continue-with-errors] [--verbose] [[--after-include makejail] ...] [[--arg parameter[=value]] ...] [[--before-include makejail] ...] [[--build-arg parameter[=value]] ...] [[--option option] ...] --file makejail --name name Run a Makejail. --continue-with-errors is equivalent to appjail-makejail(1) -e. --verbose is equivalent to appjail-makejail(1) -v. --after-include is equivalent to appjail-makejail(1) -a. --arg is equivalent to passing arguments as you normally do from command-line but without double dashes. --before-include is equivalent to appjail-makejail(1) -B. --option is equivalent to appjail-makejail(1) -o. --file is equivalent to appjail-makejail(1) -f. --name is equivalent to appjail-makejail(1) -j. --file, --after-include and --before-include can use a temporary Makejail defined by GLOBAL. FROM [--ajspec name] [--entrypoint [entrypoint|none]] [--platform platform] image[:tag] Import an image to create a jail. --ajspec is equivalent to appjail-image(1) import -N. If --entrypoint is not specified, this instruction does what IMAGE_ENTRYPOINT describes. If set to none, it is assumed that the image is currently installed, so this instruction will not attempt to download it. See appjail-image(1) import for more details. --platform is equivalent to appjail-image(1) import -a. image is equivalent to appjail-image(1) import -n. tag is equivalent to appjail-image(1) import -t. If not defined, the tag specified by the IMAGE_TAG parameter is used. GLOBAL :name: [instruction [args ...]] Create a temporary Makejail that can be executed by EXEC. This instruction is intended for those who want to build, from another jail, an application that generates an executable that is copied by the main Makejail and used by the main jail, although this in- struction can be used for much more, for example deploying multi- ple jails whose services are used by the main jail. However, noth- ing prevents you from creating another Makejail file and configur- ing the EXEC instruction to use it. Note that since the Makejail generated by this instruction is a temporary file, any reference to a file is relative to that direc- tory since INCLUDE works this way. # Correct GLOBAL :darkhttpd: INCLUDE gh+AppJail-makejails/darkhttpd GLOBAL :darkhttpd: COPY --verbose "${APPJAIL_PWD}/usr/" usr # Wrong GLOBAL :darkhttpd: INCLUDE gh+AppJail-makejails/darkhttpd GLOBAL :darkhttpd: COPY --verbose usr INCLUDE [method+]path [args ...] This is the first instruction executed, which includes a Makejail file, removes empty lines and comments, changes the current direc- tory to the directory where the included Makejail is located, and restores the previous stage after reading the last included Make- jail. After doing all this, internally a single Makejail file will be written with all the instructions from all the other Makejails (except the INCLUDE instructions, of course) which is finally exe- cuted. The following Makejails ilustrate the above description: a.makejail: OPTION start OPTION overwrite INCLUDE b.makejail CMD echo "I'm a in the build stage." b.makejail: STAGE cmd CMD echo "I'm b in the cmd stage." The resulting Makejail will be: OPTION start OPTION overwrite STAGE cmd CMD echo "I'm b in the cmd stage." STAGE build CMD echo "I'm a in the build stage." To illustrate how INCLUDE changes the current directory, the fol- lowing examples are useful: A/Makejail: OPTION start OPTION overwrite CMD echo "I'm A in the build stage." INCLUDE ../B/Makejail CMD echo "I'm A in the build stage again." B/Makejail: STAGE cmd CMD echo "I'm B in the cmd stage." INCLUDE ../C/Makejail C/Makejail: STAGE build CMD echo "I'm C in the build stage." CMD mkdir -p /usr/local/etc COPY config.conf /usr/local/etc CMD cat /usr/local/etc/config.conf STAGE start CMD echo "I'm C in the start stage." After including all Makejails in a single Makejail: RAW cd -- "/tmp/n/A" # Makejail: /tmp/n/A/Makejail OPTION start OPTION overwrite CMD echo "I'm A in the build stage." RAW cd -- "/tmp/n/B" # Makejail: /tmp/n/B/Makejail STAGE cmd CMD echo "I'm B in the cmd stage." STAGE build RAW cd -- "/tmp/n/C" # Makejail: /tmp/n/C/Makejail CMD echo "I'm C in the build stage." CMD mkdir -p /usr/local/etc COPY config.conf /usr/local/etc CMD cat /usr/local/etc/config.conf STAGE start CMD echo "I'm C in the stage stage." STAGE cmd STAGE build RAW cd -- "/tmp/n/A" # Makejail: /tmp/n/A/Makejail CMD echo "I'm A in the build stage again." Some STAGE instructions seem unnecessary, but are relevant in some cases, for example: A/Makejail: OPTION overwrite OPTION start CMD echo "I'm A before include B." INCLUDE ../B/Makejail CMD echo "I'm A after include B." B/Makejail: STAGE start CMD echo "I'm B in the start stage." The resulting Makejail will be as follows: RAW cd -- "/tmp/c/A" # Makejail: /tmp/c/A/Makejail OPTION overwrite OPTION start CMD echo "I'm A before include B." RAW cd -- "/tmp/c/B" # Makejail: /tmp/c/B/Makejail STAGE start CMD echo "I'm B in the start stage." STAGE build RAW cd -- "/tmp/c/A" # Makejail: /tmp/c/A/Makejail CMD echo "I'm A after include B." The previous example illustrates the importance of restoring the stage so as not to execute instructions at a different stage than intended. A Makejail can be included in several ways, depending on the method used: file+makejail Include a Makejail file from the local file system. This is the default method. Note that you must set this method explicitly when the path- name has a + sign. cmd+command [args ...] Use the output of a command as the Makejail file. git+url [--baseurl url] [--cachedir] [--file makejail] [--global|--local [--cachedir directory]|--tmp] Clone a git(1) repository. With --global, the git(1) reposi- tory is cloned to the global cache directory defined by GLOBAL_GIT_CACHEDIR, with --local, the git(1) repository is cloned to the local cache directory defined by the --cachedir parameter, and with --tmp the git(1) repository is cloned as a temporary directory. After the git(1) repository is cloned, the Makejail specified by --file, which by default is Makejail, is executed. --basedir is intended for other git-like methods. This instruction requires that devel/git be installed before use. fetch+url Use the program specified by MAKEJAIL_FETCH_CMD to download the Makejail file. gh+username/reponame github+username/reponame Wrapper for the git method but with --basedir set to https://github.com/. gh-ssh+username/reponame github-ssh+username/reponame Wrapper for the git method but with --basedir set to git@github.com:. gl+username/reponame gitlab+username/reponame Wrapper for the git method but with --basedir set to https://gitlab.com/. gl-ssh+username/reponame gitlab-ssh+username/reponame Wrapper for the git method but with --basedir set to git@gitlab:. LABEL key[=value] Add a new label to the jail. MOUNT --nopersist device mountpoint [type] [options] [dump] [pass] MOUNT [--nomount] [--nro [auto|nro]] device mountpoint [type] [options] [dump] [pass] Mount file systems inside the jail. This instruction simulates an fstab(5) entry as you can see, but unlike it only device and mountpoint are required, and the others, type (default: nullfs), options (default: rw), dump (default: 0) and pass (default: 0) are optional. If --nopersist is specified, mount(8) is used instead of appjail-fstab(1), that is, the mount point will not persist on re- boot and must be unmounted before the jail is stopped. By default, appjail-fstab(1) entries are compiled and mounted un- less --nomount is specified. This option is recommended when you specify multiple entries: you can gain performance by specifying this option except for the last entry. You can specify the identifier using --nro, but it is recommended to keep it as is, that is, auto, which is the default value. PKG [--chroot|--jexec [--jail]|--local] package ... PKG [--chroot|--jexec [--jail]|--local] --remove package ... PKG [--chroot|--jexec [--jail]|--local] --autoremove PKG [--chroot|--jexec [--jail]|--local] --clean PKG [--chroot|--jexec [--jail]|--local] --update PKG [--chroot|--jexec [--jail]|--local] --upgrade Manipulate packages. --chroot is equivalent to appjail-pkg(1) chroot. This option can only be used for thick and thin jails, but the latter requires the jail to be started. --jexec (default) is equivalent to appjail-pkg(1) jail. --jail is equivalent to appjail-pkg(1) jail -j. --local, run pkg(8) on the host instead of inside the jail. --remove, removes one or more packages instead of installing them. --autoremove, removes orphaned or unused packages. --clean, clean the local cache of fetched remote packages. --update, update the package list. --upgrade, perform upgrades of package software distributions. RAW [code] Remember that an InitScript is sh(1) code and is generated by Makejails, so in many cases it is very useful for writing code that is processed as is, such as conditionals, loops, etc., how- ever some instructions cannot be used for these purposes. See "NON-CONDITIONAL INSTRUCTIONS" for details. REPLACE file keyword [value] [output] Replace a given keyword (without being enclosed in %{ and }) with a value (or empty, if not defined) in a file. Keywords begin with the % character and then the keyword name enclosed in curly braces. Use % twice to escape, for example %%{KEYWORD} will be converted to %{KEYWORD}, but will not be replaced by any value. A different file can be used as output for the replaced keywords. RUN [--maintain-env] [--noclean] [--juser username|--huser username] [command [args ...]] The RUN instruction executes a program, but unlike CMD, it cannot execute sh(1) code, it cannot execute interactive programs like Python, it cannot use variables created by ARG or VAR but it can use environment variables created by ENV, and instructions such as USER, WORKDIR, and ENTRYPOINT affect this instruction. If --maintain-env is specified, leave the environment unchanged instead of simulating a full login. The rest of the parameters have the same meaning as CMD --jexec. SERVICE args ... Manipulate services. See appjail-service(1). SET [--mark] [--column column] [--row row] parameter[=value] Use appjail-config(1) to edit the template used by the jail. If --mark is specified, the given parameter is marked as required. --column and --row can be specified to edit a specific parameter; However, if --column is set to a number greater than 1, appjail-config(1) setColumn is used instead of appjail-config(1) set. STAGE stage Change the current stage. The default stage is build. SYSRC [--jail|--local] name[[+|-]=value] ... Safely edit system rc files within a jail. --jail is equivalent to appjail-sysrc(1) jail. --local is equivalent to appjail-sysrc(1) local. It is only rec- ommended to use this parameter with thick jails instead of thin jails, as it may not work correctly with the latter. UMOUNT mountpoint Unmount a mounted file system. USER user The user to run RUN as. Unlike other instructions, this one cannot use shell variables. VAR [--make-arg-env] [--noexpand] name[=default-value] Create or set a variable. If --make-arg-env is specified, the variable is available to CMD. If --noexpand the $ character is escaped. Useful for "BUILD ARGUMENTS". WORKDIR directory Create a new directory and use it as the working directory by ADD, COPY, and RUN. Unlike other instructions, this one cannot use shell variables. LOGIN [--user username] Log into the jail. --user is equivalent to appjail-login(1) -u. OPTION option appjail-quick(1)'s options. You don't need the option value enclosed in double quotes even when it has spaces. RESTART Restart the jail using appjail-restart(1). START Start the jail using appjail-start(1). STOP Stop the jail using appjail-stop(1). VOLUME [--group gid] [--mountpoint mountpoint] [--owner owner] [--perm mode] [--type type] volume Create a new volume. --group is equivalent to appjail-volume(1) add -g. --mountpoint is equivalent to appjail-volume(1) add -m. --owner is equivalent to appjail-volume(1) add -o. --perm is equivalent to appjail-volume(1) add -p. --type is equivalent to appjail-volume(1) add -t. NON-CONDITIONAL INSTRUCTIONS The following instructions cannot be used conditionally because they change the behavior of the resulting InitScript or BuildScript and do not generate code, or generate code that can only be used on specific lines: ARG CLEAR ENTRYPOINT ENV GLOBAL INCLUDE STAGE USER VAR: This instruction generates code that can be used conditionally, but if you use --make-arg-env, there is a side effect: even if you use this instruction conditionally, the environment variables will be available to CMD. OPTION INSTRUCTIONS THAT DO NOT USE THE TOKENIZER The following instructions do not use the tokenizer, so they are parsed using their own methods: ARG ENV ENTRYPOINT GLOBAL RAW USER UMOUNT WORKDIR OPTION BUILD STAGE INSTRUCTIONS The following instructions are valid only in the build stage: FROM LOGIN OPTION RESTART START STOP BUILD ARGUMENTS Unlike arguments created by ARG that can only be used for the current stage, build arguments are overridden regardless of the stage. They work similarly to the REPLACE instruction, but are a little "smarter." However, note that build arguments are not intended to replace ARG: they cannot be used conditionally, for example. Although you can build ARG and build arguments to get the best of both worlds. %{name[:|!][value]} - %{ } - Beginning and end of a build argument. If % is used twice, the first % will be removed and the rest of the string will be kept as is. - name - Argument name. By convention, in uppercase. - :|! - Use : to use value as the default value and make the build argument optional, or ! to use value as the description shown when the user doesn't set a value. - value - Default value or description. Two notes to keep in mind: if you plan to declare build arguments that use other build arguments, you must escape the } character using \. The other note is that you must first declare build arguments that use other build arguments before the latter are defined: %{PYTHON_EXECUTABLE:python%{PYTHON_MAJOR.%{PYTHON_MINOR} %{PYTHON_MAJOR:3} %{PYTHON_MINOR:9} This is because the processing is sequential and recursive: - CMD %{PYTHON_EXECUTABLE} - CMD python%{PYTHON_MAJOR}.%{PYTHON_MINOR} - CMD python3.%{PYTHON_MINOR} - CMD python3.9 To get the best of both worlds, we can use VAR and build arguments in a Makejail, but note that VAR should have to set the --noexpand parameter to avoid the special meaning of the dollar sign: VAR --noexpand python_major=%{PYTHON_MAJOR} VAR --noexpand python_minor=%{PYTHON_MINOR} RAW if ! echo "${python_major}" | grep -Eq '^[23]$'; then RAW echo "MAJOR VALID VERSIONS: 2, 3" >&2 RAW exit 1 RAW fi RAW if ! echo "${python_minor}" | grep -Eq '^(7|8|9|10|11)$'; then RAW echo "MINOR VALID VERSIONS: 7, 8, 9, 10, 11" >&2 RAW exit 1 RAW fi RAW if [ ${python_major} -eq 2 ]; then RAW if [ ${python_minor} -ne 7 ]; then RAW echo "MINOR VALID VERSION FOR 2: 7" >&2 RAW exit 1 RAW fi RAW fi PKG python${python_major}${python_minor} ENVIRONMENT APPJAIL_PWD appjail-makejail(1), when processing the INCLUDE instruction, changes the current directory, so PWD does not reflect the cur- rent directory. Only available in the build stage. SEE ALSO appjail-config(1) appjail-image(1) appjail-makejail(1) appjail-service(1) appjail-sysrc(1) appjail-quick(1) appjail-initscript(5) appjail-template(5) AUTHORS Jess Daniel Colmenares Oviedo <DtxdF@disroot.org> FreeBSD Ports 14.quarterly April 21, 2024 APPJAIL-MAKEJAIL(5)
NAME | DESCRIPTION | INSTRUCTIONS | NON-CONDITIONAL INSTRUCTIONS | INSTRUCTIONS THAT DO NOT USE THE TOKENIZER | BUILD STAGE INSTRUCTIONS | BUILD ARGUMENTS | ENVIRONMENT | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=appjail-makejail&sektion=5&manpath=FreeBSD+Ports+14.3.quarterly>