From 8e602caa8a61e6e00781c9b03c356f8ebcbc1b27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Daniel=20Colmenares=20Oviedo?= Date: Fri, 4 Sep 2026 19:08:04 -0400 Subject: [PATCH] feat: Use appjail-template(5) for allow.* parameters Currently, `allow.*` parameters are only set in a `Makejail`, which is used exclusively by Director. If a user deploys an OCI container using `appjail oci run` (CLI), the service may fail to start or may not work as expected due to the absence of the `allow.*` parameters. `allow.*` parameters are set using the `SET` instruction in a `Makejail`, but an easier way is through an `appjail-template(5)`, which can be used by both Director and the CLI, allowing the same template to be reused. --- dbuild/docs.py | 7 +-- dbuild/templates/Makejail.j2 | 4 +- dbuild/templates/README.j2 | 62 ++++++++++++++++++----- dbuild/templates/README.mkdocs.j2 | 8 +-- dbuild/templates/appjail-director.yml.j2 | 5 +- dbuild/templates/appjail-template.conf.j2 | 9 ++++ docs/dbuild.1 | 2 +- 7 files changed, 73 insertions(+), 24 deletions(-) create mode 100644 dbuild/templates/appjail-template.conf.j2 diff --git a/dbuild/docs.py b/dbuild/docs.py index fa1b23b..4655271 100644 --- a/dbuild/docs.py +++ b/dbuild/docs.py @@ -495,7 +495,7 @@ def generate_appjail_files( *, image_ref: str | None = None, ) -> Path: - """Render appjail-director.yml, .env, and Makejail into *dest_dir*. + """Render appjail-director.yml, .env, Makejail and template.conf into *dest_dir*. Per-file override: if ``.daemonless/appjail/`` exists it is copied as-is; otherwise the bundled template is rendered. @@ -527,8 +527,9 @@ def generate_appjail_files( files = { "appjail-director.yml": "appjail-director.yml.j2", - ".env": "appjail.env.j2", - "Makejail": "Makejail.j2", + ".env": "appjail.env.j2", + "Makejail": "Makejail.j2", + "template.conf": "appjail-template.conf.j2", } for filename, template_name in files.items(): diff --git a/dbuild/templates/Makejail.j2 b/dbuild/templates/Makejail.j2 index 0cfb56c..a985aa1 100644 --- a/dbuild/templates/Makejail.j2 +++ b/dbuild/templates/Makejail.j2 @@ -3,8 +3,6 @@ {%- set _reg = reg_var if reg_var is defined else registry -%} ARG tag={{ image_tag | default(default_tag) }} +OPTION container=boot OPTION overwrite=force OPTION from={{ image_ref | default(_reg + "/" + name + ":${tag}") }} -{%- for opt in jail_allow %} -SET {{ opt }}=1 -{%- endfor %} diff --git a/dbuild/templates/README.j2 b/dbuild/templates/README.j2 index 2d334b0..11b7372 100644 --- a/dbuild/templates/README.j2 +++ b/dbuild/templates/README.j2 @@ -73,6 +73,15 @@ services: restart: always {%- endmacro %} +{%- macro appjail_note_expose_ports() -%} +{%- if ports %} +> [!WARNING] +> Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network. +> +> To avoid exposing ports, just remove the `expose` option in your `appjail-director.yml` or from your command-line arguments. +{%- endif %} +{%- endmacro %} + {%- macro appjail_director_snippet(override_port=None) -%} {%- if render_mode == "mkdocs" %} ``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename=".env" } @@ -86,6 +95,12 @@ services: ``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename="Makejail" } {% include 'Makejail.j2' %} ``` +{%- if jail_allow -%} +{{ '\n' }} +``` { data-zip-bundle="{{ name }}-appjail" data-zip-filename="template.conf" } +{% include 'appjail-template.conf.j2' %} +``` +{%- endif %} {%- else -%} **.env**: @@ -104,6 +119,14 @@ services: ``` {% include 'Makejail.j2' %} ``` +{%- if jail_allow -%} +{{ '\n' }} +**template.conf**: + +``` +{% include 'appjail-template.conf.j2' %} +``` +{%- endif %} {%- endif %} {%- endmacro %} @@ -136,10 +159,15 @@ podman run -d --name {{ name }} \ {%- endmacro %} {%- macro appjail_snippet(override_port=None) -%} +{%- if render_mode == "mkdocs" %} +```bash { data-zip-bundle="{{ name }}-appjail-cli" data-zip-filename="run.sh" } +{%- else %} +```bash +{%- endif %} {%- if image_class == "service" -%} -appjail oci run -Pd \ +{{ '\n' }}appjail oci run -Pd \ {%- else %} -appjail oci run \ +{{ '\n' }}appjail oci run \ -o ephemeral \ {%- endif %} -o overwrite=force \ @@ -152,6 +180,9 @@ appjail oci run \ -o virtualnet=": default" \ -o nat \ {%- endif %} +{%- if jail_allow -%} +{{ '\n' }} -o template=template.conf \ +{%- endif %} {%- for p in ports %} {%- if loop.first %} -o expose="{{ override_port if override_port else port_var }}:{{ p.target }} proto:{{ p.protocol }}" \ @@ -166,6 +197,19 @@ appjail oci run \ -o fstab="{{ vol_src(v) }} {{ v.path }} " \{{ " # optional" if v.optional else "" }} {%- endfor %} {{ reg_var }}/{{ name }}:latest {{ name }} +``` +{%- if jail_allow -%} +{{ '\n' }} +**template.conf**: + +{%- if render_mode == "mkdocs" %} +``` { data-zip-bundle="{{ name }}-appjail-cli" data-zip-filename="template.conf" } +{%- else %} +``` +{%- endif %} +{% include 'appjail-template.conf.j2' %} +``` +{%- endif %} {%- endmacro %} {#- Bastille OCI (experimental). Bastille shares the host network stack @@ -436,10 +480,7 @@ Save as `compose.yaml`, then run `podman-compose up -d`. Save the files above, then run `appjail-director up`. -{%- if ports %} - -**Note**: Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the IPv4 address assigned by the virtual network. -{%- endif %} +{{ appjail_note_expose_ports() }} {%- endif %} {%- endif %} @@ -458,16 +499,11 @@ Save as `run.sh`, then run `sh run.sh`. ### AppJail -```bash {{ appjail_snippet() }} -``` -Save as `run.sh`, then run `sh run.sh`. - -{%- if ports %} +Save the files above, then run `sh run.sh`. -**Note**: Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the IPv4 address assigned by the virtual network. -{%- endif %} +{{ appjail_note_expose_ports() }} {%- endif %} {%- if bastille_enabled %} diff --git a/dbuild/templates/README.mkdocs.j2 b/dbuild/templates/README.mkdocs.j2 index 5f282cf..751871d 100644 --- a/dbuild/templates/README.mkdocs.j2 +++ b/dbuild/templates/README.mkdocs.j2 @@ -117,6 +117,10 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu {% if appjail_enabled %} === ":appjail-appjail: AppJail" +{% if ports %} + !!! warning + Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network. +{% endif %} {% if image_class == "service" %} === ":material-file-document-outline: Director" @@ -128,11 +132,9 @@ Before deploying, ensure your host environment is ready. See the [Quick Start Gu {% endif %} === ":material-console: CLI" - ```bash { data-zip-bundle="{{ name }}-appjail-cli" data-zip-filename="run.sh" } {{ appjail_snippet(port_var) | indent(8) }} - ``` - Save as `run.sh`, then run `sh run.sh`. + Save the files above, then run `sh run.sh`. {% endif %} {% if bastille_tab %} === ":bastille-bastille: Bastille" diff --git a/dbuild/templates/appjail-director.yml.j2 b/dbuild/templates/appjail-director.yml.j2 index 27b27ba..ddccc0c 100644 --- a/dbuild/templates/appjail-director.yml.j2 +++ b/dbuild/templates/appjail-director.yml.j2 @@ -13,7 +13,7 @@ services: {{ name }}: name: {{ name | replace("-", "_") }} options: - - container: 'boot args:--pull' + - container: 'args:--pull' {%- for p in ports %} {%- if loop.first %} - expose: '{{ override_port if override_port else port_var }}:{{ p.target }} proto:{{ p.protocol }}' @@ -32,6 +32,9 @@ services: {%- endif %} {%- endfor %} {%- endif %} +{%- if jail_allow %} + - template: !ENV '${PWD}/template.conf' +{%- endif %} {%- if env %} oci: diff --git a/dbuild/templates/appjail-template.conf.j2 b/dbuild/templates/appjail-template.conf.j2 new file mode 100644 index 0000000..3e75739 --- /dev/null +++ b/dbuild/templates/appjail-template.conf.j2 @@ -0,0 +1,9 @@ +# template.conf + +exec.start: "/bin/sh /etc/rc" +exec.stop: "/bin/sh /etc/rc.shutdown jail" +mount.devfs +persist +{%- for opt in jail_allow %} +{{ opt }} +{%- endfor %} diff --git a/docs/dbuild.1 b/docs/dbuild.1 index 5471012..7ddc324 100644 --- a/docs/dbuild.1 +++ b/docs/dbuild.1 @@ -1,4 +1,4 @@ -.TH DBUILD 1 "2026-09-03" "dbuild 1.9.14" "User Commands" +.TH DBUILD 1 "2026-09-04" "dbuild 1.9.14" "User Commands" .SH NAME dbuild \- FreeBSD OCI container image build tool .SH SYNOPSIS