DOCSEARCHbyAlgolia
Submit Docs

AppJail Framework

repository·main·Indexed 42 days ago

https://github.com/dtxdf/appjail

An open-source framework written in sh(1) and C for managing FreeBSD jails. AppJail provides a unified interface to automate complex workflows including networking (NAT, VNET, Bridges), storage (ZFS/UFS), and application deployment via Makejail. It supports advanced capabilities such as OCI containers, LinuxJails, TinyJails, and dynamic DEVFS ruleset management.

Tokens
86.8K
Snippets
324
Records
417
Agent score
53%

What's inside AppJail

  1. Overview of AppJail

    main
    AppJail is an open-source BSD-3 licensed framework written in sh(1) and C. It is designed to create isolated, portable, and easy-to-deploy environments using FreeBSD jails that behave like standalone applications. It automates the FreeBSD jail workflow by providing a unified interface for managing jails, networks, and dependencies.

  2. AppJail Design Principles

    main

    Understanding these principles helps in predicting how AppJail interacts with your system:

    • Host Preservation: AppJail avoids modifying the host system (e.g., it does not automatically change rc.conf(5), sysctl.conf(5), or firewall configurations) to ensure the user remains aware of system changes.
    • Non-Interactivity: The tool is designed to be non-interactive, making it suitable for automation.
    • Scope of Control: AppJail is designed to manage jails created by itself and avoids interfering with jails created by other tools.
    • Granularity: Instead of one monolithic command, AppJail prefers combining small, specific commands. For example, appjail makejail is a high-level tool that orchestrates the underlying core commands.
    • Separation of Concerns: AppJail is not a software build tool. For building custom repositories or ports, it is recommended to use tools like poudriere or synth and then use those repositories within an AppJail environment.

  3. Key Features of AppJail

    main

    AppJail provides several advanced capabilities for managing FreeBSD environments:

    • Deployment & Management: Supports Makejail for easy application deployment, startup order control (via priorities and boot flags), and jail dependency support.
    • Networking: Supports NAT, port forwarding (port expose), IPv4/IPv6, DHCP, SLAAC, Virtual networks (multiple networks per jail), Bridge support, VNET support, and Netgraph support.
    • Storage & Filesystems: Supports UFS and ZFS, including thin and thick jails, and the ability to backup jails using tarballs or raw images (ZFS only).
    • Monitoring & Security: Includes Healthcheckers to monitor jail health and Secrets management for secure configuration injection.
    • Advanced Capabilities: Supports OCI (containers), DEVFS (dynamic device management), LinuxJails, and TinyJails (stripped-down jails for distribution).
    • Architecture: Modular structure where each command is a unique file; uses a table-like interface for many commands; and avoids databases by separating configurations into individual entities (networks, jails, etc.).

  4. Configure NAT for jails and networks with appjail-nat

    main

    The appjail-nat utility manages Network Address Translation (NAT) to allow jails or entire virtual networks to communicate with the outside world.

    There are two modes of application:

    1. Per-jail NAT: Applied to a specific jail.
    2. Per-network NAT: Applied to an entire network, affecting all jails assigned IPv4 addresses from that network's pool.

    To exclude a specific jail from a per-network NAT rule, you can apply a NO NAT rule to that jail using the add -N flag.

  5. Manage DEVFS rulesets with the devfs CLI

    main

    The devfs command is used for dynamic DEVFS ruleset management within AppJail. It allows you to assign, load, apply, and inspect DEVFS rules for specific jails. Rules are stored within the jail's configuration directory under conf/boot/devfs/ and organized by NRO (Number of Rule Object).

    Core Concepts:

    • Ruleset: A collection of DEVFS rules assigned to a jail. You can assign a specific ruleset number or let AppJail use auto to pick an available one.
    • NRO (Number of Rule Object): An identifier used to organize specific rules within a ruleset.
    • Jail Path: Rules are persisted in ${JAILDIR}/${jail_name}/conf/boot/devfs/.
    # Example: Assign a ruleset to a jail
devfs ruleset assign -r 1 myjail

# Example: Apply specific rules to a jail
devfs apply -r 1 myjail "add /dev/null"

# Example: List all DEVFS configurations for a jail
devfs list myjail

  6. Run and manage OCI-based jails

    main

    The oci command is used to interpret and manage AppJail instances based on OCI (Open Container Initiative) images. It allows you to create jails from images, execute commands within them, and manage container-specific configurations like environment variables, entrypoints, and users.

    Core Workflow

    1. Create a jail from an image: Use oci from <image> <jail> to initialize a jail.
    2. Run the container: Use oci run to start the jail with specific configurations.
    3. Execute commands: Use oci exec to run commands in an existing, running jail.
    4. Manage configuration: Use oci set-* commands to persist settings like environment variables or working directories.
    # Example: Create a jail named 'my-container' from an image
appjail oci from nginx:latest my-container

# Example: Run the jail with a specific environment variable
appjail oci run -e DEBUG=true nginx:latest my-container

# Example: Execute a command in a running jail
appjail oci exec -u root my-container ls -la /app

  7. Manage dynamic DEVFS rules for jails with appjail-devfs

    main

    The appjail-devfs utility allows you to dynamically manage device access (DEVFS) inside jails without manually modifying /etc/devfs.rules or reloading the devfs rc script. This is the "modern way" to manage devices in AppJail, often used alongside appjail-quick with the -s device option.

    Rulesets are assigned numbers based on the algorithm defined by the DEVFS_ASSIGN_ALGO parameter. You can assign a ruleset to a jail, configure specific rules, and apply them to the jail's /dev directory immediately.

  8. Use appjail-fetch to create releases

    main

    The appjail fetch utility is used to create release directories that serve as the foundation for jails. These releases can be created using various methods: bootstrapping Debian via debootstrap, using FreeBSD components via www or pkgbase, building from the FreeBSD source tree via src, or creating empty/local directories.

    When no command is specified, the utility defaults to the method defined by the DEFAULT_FETCH_METHOD parameter.

  9. Manage secrets for jails with appjail-secrets

    main

    The appjail secrets command allows you to manage sensitive data (passwords, SSH keys, TLS keys, etc.) that should only be accessible to authorized jails in a read-only mode with restricted permissions.

    Secrets are stored on disk in an encrypted form and are decrypted into a memory-backed filesystem (using mdmfs) so that jails can access them via nullfs mounts. This in-memory filesystem is not swap-backed, meaning secrets remain in memory until a reboot or explicit unmount.

    Key Configuration:

    • SECRETS_MDMFS_SIZE: Set this in appjail.conf to define the size of the in-memory filesystem. It is highly recommended to set this to a realistic value.
    • SECRETS_BACKEND: Defines the encryption backend. Note that changing this does not re-encrypt existing data (except for age and rage which share a directory).

  10. Manage jail fstab configuration with appjail-fstab

    main

    The fstab command is used to manage the static file system information (fstab) for AppJail jails. It allows you to compile, list, get, set, mount, and unmount file systems that are part of a jail's configuration.

    Configuration is stored in the jail's directory under conf/boot/fstab/ as a series of numbered entries (NROs).

    usage: fstab [all [-e]|jail <jail>] compile
       fstab [all [-e]|jail <jail>] get [-eHIpt] -n <nro> [<keyword> ...]
       fstab [all [-e]|jail <jail>] [list] [-eHIpt] [-n <nro>] [<keyword> ...]
       fstab [all [-e]|jail <jail>] mounted
       fstab [all [-e]|jail <jail>] mount [<args> ...]
       fstab [all [-e]|jail <jail>] remove [all|nro <nro>]
       fstab [all [-e]|jail <jail>] set -d <device> -m <mountpoint> [-E|-e] [-p] [-D <dump>] [-N <name>] [-n [auto|<nro>]] [-o <options>] [-P <pass>] [-t <type>]
       fstab [all [-e]|jail <jail>] umount <args> ...

  11. Use appjail-config to manipulate templates

    main

    The appjail-config utility is used to add, delete, get, or check parameters and columns within an AppJail template. It is designed to be highly scriptable for automating template management.

    Most commands support the following targeting options:

    • -j <jail>: Use the template associated with a specific jail.
    • -t <template>: Use a specific template file (defaults to . if not specified).

    Common workflows include checking template syntax, editing templates via an environment-defined editor, or programmatically setting/getting parameter values.

  12. What is a Makejail and how does it work?

    main

    A Makejail is a text file that automates the creation of an AppJail by generating an InitScript and a BuildScript.

    Key Concepts:

    • Processing: Makejails are processed line by line. Comments and empty lines are removed. If an INCLUDE instruction is present, the specified Makejail is included into a single, temporary Makejail before execution.
    • Stages: Makejails are divided into stages using the STAGE instruction. The default stage is build. Stages can be changed to switch between different functional contexts (e.g., cmd, start).
    • Tokenizer: The CMD instruction uses the AppJail tokenizer, which allows it to execute shell strings while maintaining compatibility with characters like &, ', and \e to emulate sh behavior. However, users must ensure syntax is valid for the tokenizer to avoid Tokenizer: ERROR messages.
    • Execution Context: Most instructions (like CMD, RUN, COPY) execute within the jail environment, not on the host machine.