v3.3.0

Changes between 3.2.0 and 3.3.0

• Added: stop_env option in quick:
  • Documented: stop_env option in appjail-quick(1).
• Added: run_env option in quick:
  • Documented: run_env option in appjail-quick(1).
• Added: start_env option in quick:
  • Documented: start_env option in appjail-quick(1).
• Added: LABEL instruction in Makejails:
  • Documented: LABEL instruction in appjail-makejail(5).
• Added: label option in quick:
  • Documented: label option in appjail-quick(1).
• Added: label command.
• Enclose arguments in angle brackets:
  • To improve readability and facilitate differentiation between parameters, command switches and arguments, the latter are enclosed in angle brackets.
• Added: appjail_dns_extra parameter to concatenate hosts(5)-like files.
• Added: table library:
  • This library provides functions to beautifully print a table. Commands that print their values in table format will use this library to have less complexity and abstracting some things.
• Added: patreon.
• Added: man pages:
  • appjail(1).
  • appjail-ajspec(5).
  • appjail-apply(1).
  • appjail-checkOld(1).
  • appjail-cmd(1).
  • appjail-cpuset(1).
  • appjail.conf(5).
  • appjail-config(1).
  • appjail-deleteOld(1).
  • appjail-devfs(1).
  • appjail-disable(1).
  • appjail-dns(8).
  • appjail-ephemeral(7).
  • appjail-enable(1).
  • appjail-enabled(1).
  • appjail-etcupdate(1).
  • appjail-expose(1).
  • appjail-fetch(1).
  • appjail-fstab(1).
  • appjail-healthcheck(1).
  • appjail-help(1).
  • appjail-image(1).
  • appjail-initscript(5).
  • appjail-jail(1).
  • appjail-limits(1).
  • appjail-label(1).
  • appjail-login(1).
  • appjail-logs(1).
  • appjail-makejail(1).
  • appjail-makejail(5).
  • appjail-nat(1).
  • appjail-network(1).
  • appjail-pkg(1).
  • appjail-quick(1).
  • appjail-restart(1).
  • appjail-rstop(1).
  • appjail-run(1).
  • appjail-service(1).
  • appjail-start(1).
  • appjail-startup(1).
  • appjail-status(1).
  • appjail-stop(1).
  • appjail-sysrc(1).
  • appjail-template(5).
  • appjail-tutorial(7).
  • appjail-update(1).
  • appjail-upgrade(1).
  • appjail-usage(1).
  • appjail-user(8).
  • appjail-volume(1).
  • appjail-version(1).
  • appjail-zfs(1).
• Added: script to install the bleeding-edge version much easier.
• Added: support for exposing a range of ports.
• Fixed: error handling when obtaining the ruleset number in appjail start.
• Fixed: bug that marks an already created jail as dirty.
• Improved: message when RUNAS utility does not exist (#5).
• Added: DEFAULT_VIRTUALNET_MTU option:
  • In some environments (tested in one of mine) the MTU is very low (in my case 576) and some applications can break by not setting a correct MTU (tested with certbot), so it is necessary to set the MTU correctly for a Virtual Network.
• Improved: Slogan:
  • Center text.
  • Reduce text size.
• Improved: ImagoType.

Full Changelog: v3.2.0...v3.3.0

v3.2.0

Changes between 3.1.0 and 3.2.0

• Check status code of wait(2) in cmd_edit.c.
• Added: zfs.dataset in parameters.c (thanks @netchild).
• Fixed: parse of environment variables when its value is empty.
• Fixed: undefined variable NETWORK_GENERIC_BRG in network (The variable NETWORK_GENERIC_BRG is required for the detach command, as this variable is not defined, the command fails.).

Full Changelog: v3.1.0...v3.2.0

v3.1.0

Changes between 3.0.0 and 3.1.0

• Added: {nullfs|<pseudofs>}:reverse feature.
• Improved: AppJail image:
  • Add Imagetype.
  • Improve Slogan.
• Improved: creation of a bridge (A lock file is used to ensure that the bridge is not attempted to be created by two or more processes at the same time.).
• Fixed: bottleneck in repeat (sleep(1) command is now started after a command failure instead of executing on the first try. This ensures that the command exits as quickly as possible instead of waiting for the sleep(1) time and the command time.).

Full Changelog: v3.0.0...v3.1.0

v3.0.0

Highlights

VolumeFS

VolumeFS is another pseudo-file system implemented in AppJail to take advantage of what PseudoFS or NullFS does. The idea with this feature is to abstract more things. For example, if a user wants to use an application that uses php-fpm or apache and the application needs to have such files or directories with a specific owner or group or even file mode the user needs to create them on the host or jail and issue some commands wasting some initial time configuring the application instead of just using it. Worse, the application directory may be in a different directory depending on whether you use apache or php-fpm. Take a look at the following Makejail that take advantage of volumes: https://github.com/AppJail-makejails/dasherr#volumes

VolumeFS solves the above, the user does not have to worry about which directory to use, which file mode and which owner and group. The user only has to worry about the volume name. See the following example using appjail-director:

appjail-director.yml

options:
  - virtualnet: ':<random> default'
  - nat:

services:
  adminerevo:
    makejail: gh+AppJail-makejails/adminerevo
    name: adminerevo
    options:
      - expose: '8080:80'
    arguments:
      - adminerevo_design: 'pepa-linha'
      - adminerevo_plugins: 'login-password-less'
      - adminerevo_tag: '14.0-php82-apache'
    volumes:
      - adminerevo-plugins-file: adminerevo-plugins-file

default_volume_type: '<volumefs>'

volumes:
  adminerevo-plugins-file:
    device: .volumes/plugins.php
    options: ro

.env:

DIRECTOR_PROJECT=adminerevo

.volumes/:

tree .volumes/
.volumes/
└── plugins.php

1 directory, 1 file

plugins.php:

<?php

// See https://www.adminer.org/en/plugins/

$plugins = array(
    new AdminerLoginPasswordLess(password_hash(".", PASSWORD_DEFAULT)),
);

The user just has to run appjail-director up and adminerevo will be deployed.

Documentation: https://appjail.readthedocs.io/en/latest/fs-mgmt/#volumefs

Dynamic Environment Variables

Passing environment variables from the command line allows us to create applications with less effort in many cases, also this honors what many projects expect: configuring them through environment variables. Currently, there are some Makejails in the Centralized Repository that take advantage of this feature:

• PostgreSQL: https://github.com/AppJail-makejails/postgres
• RustyPaste: https://github.com/AppJail-makejails/rustypaste
• Gitea: https://github.com/AppJail-makejails/gitea
• MeTube: https://github.com/AppJail-makejails/metube
• InvenTree: https://github.com/AppJail-makejails/inventree

In the near future, for new Makejails, environment variables will be taken into account.

Changes between 2.10.0 and 3.0.0

• Improved: RC scripts: appjail-natnet & appjail:
  • Changed: nohup(1) to daemon(8).
  • Use only daemon(8) when starting. Running commands in background when the system is stopping, i.e. when shutdown(8) is executed may cause some problems such as leaving some processes as zombies.
• BREAKING-CHANGE: Added: VOLUME support:
  • Added: VOLUME instruction.
  • Added: volume command.
  • Added: volume option in quick.
  • Added: lib_check_volumename function in check_func.
• BREAKING-CHANGE: Escape harmful characters in ENV (ENV accepts a variety of special characters because since its creation appjail, i.e. appjail makejail lacks a way to pass environment variables dynamically. Currently, this responsibility is appjail makejail -V. This change breaks Makejails that depend on variables created by, for example, ARG).
• Added: support for escaping line-continuation.
• Added: -V parameter in {run|start|stop}.
• Disable random colors when ENABLE_COLORS is set to 0.
• Fixed: COLOR_DEFAULT (COLOR_DEFAULT does not reset the bold escape sequence).
• Added: -V in {enable|disable|enabled} ... {start|stop|run}.
• Fixed: ADD returns 0 when it should not (pipefail is set only to this instruction to get the correct return code because if the tarball fetch fails, this does not imply that tar(1) fails).

Breaking Changes

• Volumes represent a breaking-change because ./conf/volumes/ is added to the include/exclude list when importing/exporting an image. If the image does not have such a directory (i.e. an image created with an older version of AppJail), tar(1) will fail. To fix this problem, the image must be rebuilt. All Makejails in the Centralized Repository were rebuilt.

• The harmful escape characters in ENV represent a breaking change because an older Makejail can use, for example, the dollar sign to use a variable created by, for example, ARG. If ENV uses the dollar sign, it is used in the jail environment, not in the host environment. Some other characters are escaped to avoid command execution. The main motivation for this change is to take advantage of the -V parameter in most commands to pass environment variables dynamically. If we do not take advantage of this parameter, we need to define parameter by parameter. See this real example: AppJail-makejails/metube@9eb349f

  With the -V parameter a Makejail is much easier to write as you can see, since we don't need to define ARG for each environment variable that uses upstream.

Full Changelog: v2.10.0...v3.0.0

v2.10.0

Changes between 2.9.0 and 2.10.0

• Added: support for dynamic versioning.
• Display the process to be killed in kill_child.sh.
• Kill unused processes after stopping AppJail in start|stop (If AppJail is killed when the corresponding signal is received, a jail(8) process can be left, so after AppJail exits the jail(8) process is killed.).
• Make local the config variable in kill_child.sh.
• Fixed: typo executed -> execute in atexit.
• Restore signals after execute atexit commands.
• Improved: signal handling (Signals are handled asynchronously, so a blocking command can be terminated without hanging up. Now more signals are handled (SIGHUP SIGINT SIGQUIT SIGQUIT SIGQUIT SIGQUIT SIGTERM SIGXCPU SIGXFSZ SIGXFSZ SIGXFSZ EXIT) and others are ignored (SIGALRM SIGVTALRM SIGPROF SIGUSR1 SIGUSR2). And also all processes created by the parent process are terminated recursively after executing atexit.).
• Added: missing license header in ajdns.sh.
• Added: cpignore file to gitignore.
• Ignore SIGINT for initscripts and the buildscript (The child processes are terminated successfully, but in an interactive session (using AppJail on a console) a CTRL-C (so a SIGINT) can close child processes like the buildscript or an initscript (both are really a sh(1) script). To work around this, SIGINT is ignored, but all other signals are not, so kill_tree.sh of the parent process will terminate the remaining processes afterwards.).
• Added: --tmp parameter to git method in Makejail.
• Make local the gitdir variable in makejail.
• Added: pkg option in quick.
• Mark the jail as clean once its execution has been completed in quick.
• Issue a warning when the jail will use a dirty release directory.
• Changed: the debugging level of the message that appears before removing the jail.

Full Changelog: v2.9.0...v2.10.0

v2.9.0

Highlights

Read the Docs

The documentation has been moved to Read the Docs. The format is better, beautiful and easily readable and shows all the features that AppJail offers you.

Some sections have been written for newbies to using AppJail, I hope this helps a lot:

• Getting Started: https://appjail.readthedocs.io/en/latest/getting-started/
• Configuring AppJail: https://appjail.readthedocs.io/en/latest/configure/

Documentation: https://appjail.readthedocs.io/

PseudoFS

The purpose of this handy feature is to allow you to easily separate the data that should persist when removing the jail. For example, imagine you import an image and it comes with /usr/local/www/apache24/data/wp-content indicating a WordPress installation. Such files and subdirectories will be removed with the jail data and other things it contains. For this data to persist, you must move them to the host and mount them using mount_nullfs(8). You will probably need to stop the jail before moving the files as some applications may not be able to run correctly.

This pseudo-filesystem does this. It moves the data from the jail to the host when you run appjail fstab jail ... compile and mounts that file or directory using mount_nullfs(8), so that when you remove the jail, your data is safe.

# mkdir -p /tmp/var_tmp
# ls /tmp/var_tmp
# appjail fstab jail jtest set -d /tmp/var_tmp -m /var/tmp -t '<pseudofs>'
# appjail fstab jail jtest
NRO  ENABLED  NAME  DEVICE        MOUNTPOINT  TYPE        OPTIONS  DUMP  PASS
0    1        -     /tmp/var_tmp  /var/tmp    <pseudofs>  rw       0     0
# appjail restart jtest
...
[00:00:10] [ debug ] [jtest] Moving /usr/local/appjail/jails/jtest/jail//var/tmp/vi.recover -> /tmp/var_tmp/vi.recover ...
...
# appjail fstab jail jtest mounted
/usr/local/appjail/releases/amd64/13.2-RELEASE/default/release -> /usr/local/appjail/jails/jtest/jail/.appjail
/tmp/var_tmp -> /usr/local/appjail/jails/jtest/jail/var/tmp
devfs -> /usr/local/appjail/jails/jtest/jail/dev
# ls /tmp/var_tmp
vi.recover/

PseudoFS: https://appjail.readthedocs.io/en/latest/fs-mgmt/#pseudofs

Dynamic DEVFS Ruleset Management

The traditional approach requires you to first edit /etc/devfs.rules, write some DEVFS rules, reload with service devfs restart and set devfs_ruleset in your jail configuration file. AppJail supports this approach, but now you can use a modern way: let AppJail control the loading of your rulesets. You can define them using appjail quick or the DEVICE statement in your Makejail.

# appjail quick jtest \
    overwrite=force \
    start \
    device='include $devfsrules_hide_all' \
    device='include $devfsrules_unhide_basic' \
    device='include $devfsrules_unhide_login'
...
# appjail devfs list jtest
NRO  ENABLED  NAME  RULE
0    1        -     include $devfsrules_hide_all
1    1        -     include $devfsrules_unhide_basic
2    1        -     include $devfsrules_unhide_login

DEVFS: https://appjail.readthedocs.io/en/latest/DEVFS/

Source Tree

AppJail can now build the entire FreeBSD source tree for better customization, performance and more.

# appjail fetch src
[00:00:02] [ info  ] Build log will be releases/default/build/2023-10-12_06h18m40s.log
[00:00:02] [ info  ] Starting installworld with 8 jobs ...
[00:03:57] [ info  ] installworld finished!
[00:03:57] [ info  ] Starting distrib-dirs ...
[00:04:02] [ info  ] distrib-dirs finished!
[00:04:02] [ info  ] Starting distribution ...
[00:04:36] [ info  ] distribution finished!
[00:04:36] [ info  ] Starting delete-old delete-old-libs ...
[00:05:28] [ info  ] delete-old delete-old-libs finished!

Source Tree: https://appjail.readthedocs.io/en/latest/source-tree/

Acknowledgments:

• @netchild

Apply Makejails

Maybe you have a jail already created to which you want to make some changes, but simply running a Makejail is not useful for your case since it will be recreated, so you create a script in the language of your choice, but you realize that you need to write more things than simply creating a Makejail. The solution to this problem is to apply a Makejail to an existing jail to take advantage of the Makejail instructions.

Makejail.apply:

STAGE apply

PKG telegram-desktop \
    xpdf \
    librewolf
    mesa-dri

To apply this Makejail just execute appjail apply.

appjail apply xrdp Makejail.apply

Applying Makejails: https://appjail.readthedocs.io/en/latest/makejails/apply/

Acknowledgments:

• @alonsobsd

Fair Image Bandwidth

To achieve greater fairness between the bandwidth of the nodes hosting the images, a randomized approach is used.

Shorter domain names

# ping -c4 redis
PING redis (10.42.0.16): 56 data bytes
64 bytes from 10.42.0.16: icmp_seq=0 ttl=64 time=0.244 ms
64 bytes from 10.42.0.16: icmp_seq=1 ttl=64 time=0.154 ms
64 bytes from 10.42.0.16: icmp_seq=2 ttl=64 time=0.216 ms
64 bytes from 10.42.0.16: icmp_seq=3 ttl=64 time=0.189 ms

--- redis ping statistics ---
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.154/0.201/0.244/0.033 ms

DNS#using-shorter-domain-names: https://appjail.readthedocs.io/en/latest/networking/DNS/#using-shorter-domain-names

Changes between 2.8.0 and 2.9.0

• Added: version_extra keyword in appjail jail list.
• Migrated: https://appjail.readthedocs.io
• Added DEVFS support:
  • .gitignore:
    • Added: find-number-from-start.
    • Added: find-smallest-missing-number.
  • etc/rc.d/appjail:
    • Added: devfs in REQUIRE.
  • Added: fnfs algorithm.
  • Added: fsmn algorithm.
  • Added: devfs command.
  • Added: device option in appjail quick.
  • Added: DEVICE instruction in appjail makejail.
  • Added: devfs_ruleset keyword in appjail jail list.
  • Added DEVFS support in appjail start.
  • Added: lib_check_varname function in share/lib/check_func.
  • Added: devfs library.
  • Added: select library.
  • Added: load-devfs-rules script.
  • Added: DEVFS_ASSIGN_ALGO option in AppJail configuration file.
  • Added: DEVFS_FNFS option in AppJail configuration file.
• Fixed: lib_repeat:
  • Fixed: exit status (it returns 0 instead of the correct exit status).
  • Fixed: check for when the output is empty or not.
• Fixed: usage limits remove keyword.
• Fixed: typo limits -> limits_usage.
• Added: IMAGE_DOWNLOAD_METHOD option in AppJail configuration file (This option is implemented to solve a problem, namely fairness when downloading an image between multiple sources. The random option is set by default as it appears to be fair, but more methods may be implemented in the future if this assumption is not accurate.).
• Replaced: shell process with exec in share/appjail/scripts/ajuser.sh and share/appjail/scripts/runas.sh.
• Fixed: functions and modules that may hang (These functions naively pass an argument to grep(1) relying on the -F flag to compare each entry. The problem is that if the user passes an invalid entry as -a, problems such as hangings or the like may occur. To fix this, simply add -- before the pattern to told to getopt(3) to stop processing further options.):
  • appjail fetch.
  • appjail login.
  • lib_check_signal.
  • lib_check_rctl*.
  • lib_check_path_traversal*.
• Fixed: limits stats (it shows duplicate entries).
• Added: support for applying Makejails.
• Fixed: lib_check_func (lib_check_func may return 0 even if its argument is not a function but a program, which may lead to execute it instead of the intended function.).
• Fixed: current directory when executing initscripts (When executing an initscript, the current directory should be the last current directory when processing the main Makejail, but it is the current directory where the initscript is located, which can break stages using some instructions like COPY or CMD --local. The build stage is not affected since it does not use initscripts.).
• Removed: extra new line in share/appjail/scripts/run_jail.sh.
• Added: Shorten Domain Names feature.
• Added: JOBS option in AppJail configuration file.
• Deprecated: appjail fstab jail ... -p flag.
• Added: etcupdate command.
• Added: appjail checkOld command.
• Fixed: appjail update jail parameters.
• Added: appjail deleteOld command
• Added: appjail fetch src command.
• Added: release option in appjail quick.
• Removed: unused parameters in appjail update release.
• Limited: depth of search in appjail fetch list.
• Added: more checks for when errors occur after creating directories in a thinjail.
• Ignored: files that do not exist when creating a thinjail.
• Optimized: appjail jail list (Getting jail information in parallel is better and improves performance than doing it sequentially).
• Fixed: syntax order in appjail fetch.
• Implemented: PseudoFS.
• Added: support for files when using nullfs filesystem.
• Added: etc/rc.d/appjail-dns to uninstall target.

Full Changelog: v2.8.0...v2.9.0

v2.8.0

Changes between 2.7.1 and 2.8.0

• Added: support for unprivileged users in the main script (Now an unprivileged user can run appjail without running appjail-user and this is the recommended way.).
• Fixed: template_isvar() as it incorrectly detects a parameter as a variable.
• Fixed: test_param() as it returns false when a character is a space.
• Fixed: typo update -y -> update in PKG.
• Fixed: instruction order that does not require a specific order.
• Fixed: execution of the OPTION instruction when there are no options.

Full Changelog: v2.7.1...v2.8.0

v2.7.1

Changes between 2.7.0 and 2.7.1

• Hotfix: Load rc config before checking values (When the user defines a custom rc value in their rc.conf file, it is not honored for some operations, instead the default values are used, which is not the intention in this case.).

Full Changelog: v2.7.0...v2.7.1

v2.7.0

Changes between 2.6.0 and 2.7.0

• Fixed: <defunct> process in appjail-dns (When sending a SIGTERM signal to appjail-dns, there will be one process left, that process is the sleep(1) command, which results in a minute or a little more waiting for this process to finish. To fix this, when sending a SIGTERM signal to appjail-dns, a SIGTERM signal is sent to the sleep(1) command.).
• Fixed: exit status of the start stage (The start stage may return a non-zero exit status indicating an error or whatever it means and the start command will return 0 which in almost all situations is not the intent.).
• Fixed: pkg all (Add a missing shift command to fix pkg all as its arguments were passed to pkg(8).).
• Added: special keyword <random> to virtualnet:interface.
• Added: special keyword <name> to virtualnet:interface.
• Create the mount point when using the -p parameter in fstab set.
• Fixed: incorrect data type in fstab:dump and fstab:pass.
• Incremented: priority after running OPTION.
• Make empty some global variables when running makejail.
• Added: -V parameter in makejail.
• Improved: DNS support.
• Added: input file when showing the importing message.
• Moved: message when importing after creating the empty jail.
• Fixed: typos in Build Arguments.
• Removed: obsolete documentation for Build Arguments (The example shown in Build Arguments is no longer correct as the official Makejail for Python has been changed.).
• Added: IMAGE_ENTRYPOINT option
• Fixed: share/appjail/lib/replace:lib_replace: escape [&#]
• Adapted: EXEC to use global makejails
• Added: GLOBAL instruction

Full Changelog: v2.6.0...v2.7.0

v2.6.0

Changes between 2.5.2 and 2.6.0

• Added: force, recursive and force+recursive flags to overwrite the jail in appjail quick.
• Added: -g parameter to appjail logs remove to enable shell glob patterns.
• Added: --clean parameter in PKG.
• Added: Images to Features.
• Added: warning for when removing installed images and Makejails in README.
• Added: option for update all installed Makejails.
• Added: more information to update Makejails manually.
• Improved: killing processes in appjail healthcheck and appjail startup (Simply killing a process is not technically correct because the process after a while may be another process created by another process and not by AppJail, so errors may occur. To fix this, only processes created by AppJail will be killed, this is done by comparing the parent pid with the parent pid of the process we want to kill.).
• Fixed: overwriting the main log file (the main log file is overwritten every time any appjail's rc script is called, to avoid this, the log file is created only when it does not exist).
• Added: NETWORKING keyword to appjail rc script (to ensure basic network services are running, including general network configuration NETWORKING has been added to REQUIRE).
• Added: escape command substitution beginning with dollar sign.
• Added: escape common characters in EXEC.
• Removed: slash character from escape list in OPTION.
• Added: escape slash character in some commands (escaping the slash character in some commands is necessary because it has a special meaning for the tokenizer).
• Fixed: typo ${optarg} -> ${arg} in EXEC.
• Added: FROM instruction.
• Added: appjail image command.
• Removed: new line in lib_strlen (the number of bytes in the lib_strlen's argument is incorrect as the new line is counted).
• Added: portable option in the import+root installation method.
• Added: conflicts for installation methods in appjail quick.
• Fixed: typo ${fetch_args} -> ${fetch_cmd} in appjail makejail.
• Added: portable option in the export+root installation method.
• Fixed: typos when displaying errors after creating a directory / dataset.
• Fixed: typo appjail-user logs -> appjail logs in Logs.
• Added: support for appjail network in appjail quick.
• Added: auto-create command in appjail network.
• Added: --before-include and --after-include parameters in EXEC.
• Added: -a and -B parameters in appjail makejail (useful for Makejail builders since parameters can be included in the Makejail file after or before the Makejail's builder is included.).
• Created: sponsorship.
• Documented: missing -a and -v parameters in appjail fetch destroy.
• Documented: missing healthcheckers subtype log.
• Added: appjail logs remove all command.
• Added: support for appjail logs to remove a bunch of logs.
• Obsolete: appjail config.

Full Changelog: v2.5.2...v2.6.0