{"id":24122154,"url":"https://github.com/tlinden/jaildk","last_synced_at":"2025-09-18T11:32:50.127Z","repository":{"id":48603668,"uuid":"310674658","full_name":"TLINDEN/jaildk","owner":"TLINDEN","description":"FreeBSD jail development kit","archived":false,"fork":false,"pushed_at":"2025-04-01T11:37:38.000Z","size":153,"stargazers_count":4,"open_issues_count":6,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-01T12:31:56.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TLINDEN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-06T18:22:30.000Z","updated_at":"2025-04-01T11:35:06.000Z","dependencies_parsed_at":"2024-10-16T19:18:19.422Z","dependency_job_id":null,"html_url":"https://github.com/TLINDEN/jaildk","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/TLINDEN/jaildk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fjaildk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fjaildk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fjaildk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fjaildk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TLINDEN","download_url":"https://codeload.github.com/TLINDEN/jaildk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fjaildk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275757840,"owners_count":25523110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-11T11:38:37.534Z","updated_at":"2025-09-18T11:32:50.097Z","avatar_url":"https://github.com/TLINDEN.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Actions](https://github.com/tlinden/jaildk/actions/workflows/ci.yaml/badge.svg)](https://github.com/tlinden/jaildk/actions)\n\n## jaildk - a FreeBSD jail development kit v2.0.4\n\n## Breaking Changes\n\nIt is not possible to upgrade an existing installation of jaildk using\nthe builtin `jaildk update` from version 1.x to 2.x!\n\nSo, in order to upgrade to the next major version, check out the repo and execute:\n\n```\nmake\nmake install JAILDIR=/your/jaildir\n```\n\nSee below for more details. Starting with 2.0.0 `jaildk update` can be used again.\n\nIn addition starting with 2.0.0 the commandlines of the following subcommands changed:\n\n| 1.x                                                     | 2.0.0 up                                                   |\n|---------------------------------------------------------|------------------------------------------------------------|\n| `jaildk build \u003cjail\u003e \u003cmode\u003e [-b \u003cbase\u003e] [-v \u003cversion\u003e]` | `jaildk build \u003cjail\u003e -m \u003cmode\u003e [-b \u003cbase\u003e] [-v \u003cversion\u003e]` |\n| `jaildk install \u003cjail\u003e \u003cmode\u003e [-r function]`            | `jaildk install \u003cjail\u003e -m \u003cmode\u003e [-r function]`            |\n| `rc \u003cjail\u003e \u003cmode\u003e [-r \u003crc.d script\u003e]`                   | `rc \u003cjail\u003e -m \u003cmode\u003e [-r \u003crc.d script\u003e]`                   |\n| `ipfw \u003cjail\u003e \u003cmode\u003e`                                    | `ipfw \u003cjail\u003e -m \u003cmode\u003e`                                    |\n\nSo, every subcommand supporting a  mode parameter needs that parameter\nnow specified as an argument to the `-m` parameter.\n\n## Introduction\n\nThis is  the README for the  FreeBSD jail utility `jaildk`.  It can be\nused to build, update, manage and run jails in a versioned environment.\n\nEvery jail  consists of layers of  directories mounted on top  of each\nother using  nullfs mounts. Some  of them  can be shared  among jails,\nsome are versioned. By using shared  and versioned layers of mounts it\nis easy to update jails in a  new version while the current version is\nstill running, you can switch back to an older version of a jail.\n\nMost of the layers are mounted read-only for security reasons.\n\nLet's take a look at the layers of a typical running jail built with `jaildk`:\n```\n     1  /jail/base/12.1-RELEASE-p10      /jail/run/db                       read-only\n     2  /dev/md12                        /jail/run/db/tmp\n     3  devfs                            /jail/run/db/dev\n     4  /jail/log/db-20201026            /jail/run/db/var/log\n     5  /jail/appl/db-20201026           /jail/run/db/usr/local             read-only\n     6  /jail/etc/db/etc-20201026        /jail/run/db/etc                   read-only\n     7  /jail/etc/db/local-etc-20201026  /jail/run/db/usr/local/etc         read-only\n     8  /jail/etc/db/cron-20201026       /jail/run/db/var/cron\n     9  /jail/home/db/root-20201026      /jail/run/db/root\n    10  /jail/data/db/mysql-20201026     /jail/run/db/usr/local/data/mysql\n    11  /backup/db                       /jail/run/db/var/backups\n                                                     |\n                                                     +--- root of the jail\n```\n\nAs can be easily deduced this is a database jail with the following layers:\n\n1. **base layer**: This is basically the same as a FreeBSD base, which\n   contains all biinaries, libraries and  other files required to boot\n   up a FreeBSD system. Our base  doesn't contain a kernel by default,\n   but  you could  add one,  required  if you  want to  use the  ports\n   collection and  compile `lsof` yourself.\u003cbr/\u003e\n   This  particular base  is  based on  12.1-RELEASE-p10,  that is,  I\n   created it  while I had this  release installed and running  on the\n   host system.\n2. **tmp layer**: Just a ramdisk for `/tmp`, the size can be tuned.\n3. **dev layer**: Contains /dev/null and friends, required by every jail.\n4. **log layer**:  Here  we  have our  first  versioned layer  for\n   `/var/log`. Notice how all other layers are using the same version,\n   this  is done  by purpose  (but can  be changed  if you  like). The\n   version is a jail variable (see  below) which is being used for all\n   layers.\n5. **application  layer**: As  you know if  you're using  FreeBSD, any\n   additional software,  wether installed from  a port or  as package,\n   will be  installed to  `/usr/local`.  In our  case it  contains the\n   mysql   server  software,   bash   and  a   couple  of   supporting\n   utilities. It is being mounted read-only, so no new software can be\n   installed in the running jail.  This might sound annoying at first,\n   because you  can't just install  stuff inside the jail  anytime you\n   like. But it  forces you to work more disciplined.  Once a jail has\n   been completely  built you can  be sure, all components  match with\n   each other. Read below how to install or update software in a jail.\n6. **/etc layer**: this just contains  the normal etc, it is basically\n   a stripped copy of the host `/etc`.  We do not use it at all inside\n   a  jail, but  it's required  nontheless. There  are some  exceptions\n   however, like `/etc/resolv.conf`.\n7. **/usr/local/etc layer**:  This  is the  place  we configure  all\n   aspects of the jail, all configs  reside here (like in our case the\n   mysql config). It  is also being mounted  read-only, just like\n   the etc layer.\n8. **cron layer**:  A writable mount for the crontabs  of users inside\n   the  jail.  That   way  one  can  modify   crontabs  with  `crontab\n   -e`. However, if you don't want or need this, just remove the layer\n   and add cronjobs to `/etc/crontab`.\n9. **/root layer**: most of the administrative work inside a jail must\n   be done  as the  root user and  it would  be a pity  not to  have a\n   writable  history. So,  `/root`  is mounted  writable  to add  more\n   comfort.\n10. **a data layer**: A versioned data layer which contains the binary\n    data of our mysql server. This  is very jail specific and you have\n    to add such layers yourself. Variants  of such a layer include the\n    document root of a webserver or the repositories of a git server.\n11.  **backup layer**:  Another  custom layer,  here  we've mounted  a\n    global backup directory of our host which contains all backups.\n    \nAll layers  are configured  in a `mount.conf`  file specific  for each\njail. The one for this jail looks like this:\n```\nbase/$base                    $name                       nullfs  ro\nmd                            $name/tmp                   mfs     rw,nosuid,async  500m 1777\ndev                           $name/dev                   devfs\nlog/$name-$version            $name/var/log               nullfs  rw\nappl/db-$version              $name/usr/local             nullfs  ro\netc/$name/etc-$version        $name/etc                   nullfs  ro\netc/$name/local-etc-$version  $name/usr/local/etc         nullfs  ro\netc/$name/cron-$version       $name/var/cron              nullfs  rw\nhome/$name/root-$version      $name/root                  nullfs  rw\ndata/$name/mysql-$version     $name/usr/local/data/mysql  nullfs  rw\n/backup/db                    $name/var/backups           nullfs  rw\n```\n\nNow, as you can see, we're  using variables here. Those are defined in\nthe  `jail.conf` (not  to  be confused  with  `/etc/jail.conf` on  the\nhost!):\n```\nname=db\nversion=20201026\nbase=12.1-RELEASE-p10\n```\n\nYou might wonder  how the other aspects of a  jail are configured like\nip  addresses, routing,  jail  parameters, sysctls  etc. Well,  that's\nbeyond the  purpose of  `jaildk`.  You just  use the  standard FreeBSD\nmechanism for these things,  that is `/ect/rc.conf`, `/etc/jail.conf`,\n`service  jail ...`,  `jexec`,  etc. However,  `jaildk` provides  some\nhandy wrappers to make live easier.\n\nFor an overview of the provided commands, here's the usage screen:\n```\nUsage: ./jaildk \u003ccommand\u003e \u003ccommand-args\u003e\n\nBuilding Jails:\nbase -b \u003cname\u003e [-w] [-s \u003cscript\u003e]                 - build a new base\nbuild \u003cjail\u003e -m \u003cmode\u003e [-b \u003cbase\u003e] [-v \u003cversion\u003e] - install a build chroot of a jail\ncreate                                            - create a new jail from a template\nclone -s \u003csrc\u003e -d \u003cdst\u003e [-o \u003cv\u003e] [-n \u003cv\u003e]         - clone an existing jail or jail version\nfetchports [-v \u003cversion\u003e]                         - fetch current port collection\n\n(Un)installing Jails:\ninstall \u003cjail\u003e -m \u003cmode\u003e [-r function]            - install a jail (prepare mounts, devfs etc)\nuninstall \u003cjail\u003e [-w]                             - uninstall a jail\nremove \u003cjail\u003e                                     - remove a jail or a jail version\nreinstall \u003cjail\u003e [-b \u003cbase\u003e] [-v \u003cversion\u003e]       - stop, remove, install and start a jail, if\n                                                    -b and/or -v is set, update the jail config\nprune [-b | -a | -j \u003cjail\u003e                        - display unused directories\n\nMaintaining Jails:\nstart \u003cjail\u003e                                      - start a jail\nstop \u003cjail\u003e                                       - stop a jail\nrestart \u003cjail\u003e                                    - restart a jail\nstatus [\u003cjail\u003e] [-v]                              - display status of jails or \u003cjail\u003e\nrc \u003cjail\u003e -m \u003cmode\u003e [-r \u003crc.d script\u003e]            - execute an rc-script inside a jail\nipfw \u003cjail\u003e -m \u003cmode\u003e                             - add or remove ipfw rules\n\nManaging Jails:\nlogin \u003cjail\u003e [\u003cuser\u003e]                             - login into a jail\nblogin \u003cjail\u003e                                     - chroot into a build jail\n\nTransferring Jails:\nfreeze \u003cjail\u003e [-a -b -v \u003cversion\u003e]                - freeze (build an image of) a jail\nthaw \u003cimage\u003e                                      - thaw (install) an image of a jail\n\nGetting help and internals:\ncompletion                                        - print completion code. to use execute in a bash:\n                                                    source \u003c(jaildk completion)\nhelp \u003ccommand\u003e                                    - request help on \u003ccommand\u003e\nversion                                           - print program version\nupdate [-f]                                       - update jaildk from git repository\n```\n\n## Installation\n\nClone this repository to your FreeBSD server and execute the following command:\n```\nmake\nmake install\n```\n\nThis will create the directory structure required for the tool itself,\ncreate a  template jail and build  a base directory. The  default base\ndirectory is `/jail`. You can modify this by issuing:\n```\nmake install JAILDIR=/another/dir\n```\n\nBe aware,  that the `jaildk` script  itself will only be  installed to\n`$JAILDIR/bin/jaildk`.  Either put  this directory  into your  `$PATH`\nvariable or create a symlink to the script in some bin dir.\n\n## Bash Completion\n\nIf you want to use `jaildk` with bash completion, put this line into your `.bashrc`:\n```\nsource \u003c(jaildk completion)\n```\n\n## Basic usage\n\nLet's say you installed *jaildk* into `/jail` and you want to create a\nnew jail with  the name 'myjail' and the ip  address '172.16.1.1'.\n\nThe following steps need to be done:\n\n### Configure /etc/jail.conf\n\nCreate the file `/etc/jail.conf` with the following innitial contents:\n```\n* {\n    exec.start = \"/bin/sh /etc/rc\";\n    exec.stop = \"/bin/sh /etc/rc.shutdown\";\n    allow.raw_sockets = \"false\";\n    sysvmsg = \"new\";\n    sysvsem = \"new\";\n    sysvshm = \"new\";\n    host.hostname = $name;\n    path = \"/jail/run/$name\"; \n    exec.prestart = \"/jail/bin/jaildk install $name start\";\n    exec.clean = \"true\";\n}\n\nmyjail {\n    ip4.addr = \"172.16.1.1\";\n}\n```\n\nRefer to [jail(8)](https://www.freebsd.org/cgi/man.cgi?query=jail\u0026sektion=8) for more possible settings.\n\n### Configure /etc/rc.conf\n\nNext add the following lines to your `/etc/rc.conf`:\n```\nifconfig_em0_alias0=\"inet 172.16.1.1/32\"\njail_enable=\"YES\"\n```\n\nYou may need to replace the interface name `em0` with the one in use on your system.\nYou might need to restart the interface to apply the alias: `/etc/rc.d/netif restart`.\n\n### Create the jail\n```\n# jaildk create myjail\n\n- cpdup -x /jail/log/.template-20201106 /jail/test/log/myjail-20201106\n- cpdup -x /jail/home/.template/root-20201106 /jail/test/home/myjail/root-20201106\n- cpdup -x /jail/etc/.template/etc-20201106 /jail/test/etc/myjail/etc-20201106\n- cpdup -x /jail/etc/.template/local-etc-20201106 /jail/test/etc/myjail/local-etc-20201106\n/jail/data/.template/www doesn't exist, ignored\n/jail/data/.template/spool doesn't exist, ignored\n- cp -pRp /jail/etc/.template/mount.conf /jail/test/etc/.template/ports.conf /jail/test/etc/.template/mtree.conf /jail/test/etc/myjail/\ncp: /jail/etc/.template/ports.conf: No such file or directory\nCreating /jail/etc/.template/jail.conf\nCreating run and build dirs\n- mkdir -p /jail/run/myjail\n- mkdir -p /jail/build/myjail\nDONE.\nConsider adding the jail myjail to /etc/jail.conf!\n\nTo mount the build chroot of the new jail, execute:\njaildk build myjail\n\nTo login into the build chroot\njaildk blogin myjail\n\nTo mount the production chroot of the new jail, execute:\njaildk install myjail\n\nTo login into the build chroot\njaildk login myjail\n\nTo start the jail, execute:\njaildk start myjail\n```\n\n### Mount the build chroot of the jail\n\n```\n# jaildk build myjail\n\nInstalling jail myjail\nmount - mount -t nullfs -o rw /jail/base/12.1-RELEASE-p10 /jail/build/myjail\nmount - mdmfs -o rw,nosuid,async -s 128m -p 1777 md /jail/build/myjail/tmp\nmount - mount -t devfs dev /jail/build/myjail/dev\nmount - mount -t nullfs -o rw /jail/log/myjail-20201106 /jail/build/myjail/var/log\nmount - mount -t nullfs -o rw /jail/appl/default-20201106 /jail/build/myjail/usr/local\nmount - mount -t nullfs -o rw /jail/etc/myjail/etc-20201106 /jail/build/myjail/etc\nmount - mount -t nullfs -o rw /jail/etc/myjail/local-etc-20201106 /jail/build/myjail/usr/local/etc\nmount - mount -t nullfs -o rw /jail/home/myjail/root-20201106 /jail/build/myjail/root\n```\n\n### Chroot into the build dir and install software\n\n```\njaildk blogin myjail\npkg install bash nginx curl ...\nvi /usr/local/etc/rc.conf\nvi /usr/local/etc/nginx/nginx.conf\n```\n\nSince  the build  chroot  is  writable you  can  install packages  and\nconfigure everything as needed.\n\n### Using the ports collection\n\nThere might be cases when using pre build binary packages are not your\nthing. In such a case you want to use the [FreeBSD Ports Collection](https://www.freebsd.org/ports/).\n\n*jaildk* supports this, here are the steps required:\n\n#### Create a buildbase\n\nA  normal base  directory cannot  be  used with  the ports  collection\nbecause  jaildk removes  libraries and  binaries for  security reasons\nfrom normal bases. To create a build base, execute:\n\n`jaildk base -b 12-RELEASE-build -w`\n\nNext, add  the following entry  to the  configuration of you  jail. To\nstay with our example, edit `/jail/etc/myjail/jail.conf` and add:\n\n`buildbase=12-RELEASE-build`\n\nThen install the build jail as usual:\n\n`jaildk build myjail`\n\nInstall the current ports collection:\n\n`jaildk fetch`\n\nIn case the  ports version created does not match  the version of your\njail, you need  to configure the different ports version  in your jail\nconfig `/jail/etc/myjail/jail.conf` like this:\n\n`ports=20201127`\n\nNow you can enter the build jail and install ports the traditional way:\n\n```\njaildk blogin myjail\ncd /usr/ports/shells/bash\nmake config-recursive install clean\n```\n\n### When done, install and start the jail\n\n```\n# jaildk install myjail \nInstalling jail myjail\nmount - mount -t nullfs -o ro /jail/base/12.1-RELEASE-p10 /jail/run/myjail\nmount - mdmfs -o rw,nosuid,async -s 128m -p 1777 md /jail/run/myjail/tmp\nmount - mount -t devfs dev /jail/run/myjail/dev\nmount - mount -t nullfs -o rw /jail/log/myjail-20201106 /jail/run/myjail/var/log\nmount - mount -t nullfs -o ro /jail/appl/default-20201106 /jail/run/myjail/usr/local\nmount - mount -t nullfs -o ro /jail/etc/myjail/etc-20201106 /jail/run/myjail/etc\nmount - mount -t nullfs -o ro /jail/etc/myjail/local-etc-20201106 /jail/run/myjail/usr/local/etc\nmount - mount -t nullfs -o rw /jail/home/myjail/root-20201106 /jail/run/myjail/root\n\n# jaildk start myjail\nJail myjail start:\nStarting jails: myjail.\n\n# jaildk status myjail\nJail scipown status:\n JID             IP Address      Hostname                      Path\n myjail          172.16.1.1      myjail                        /jail/run/myjail\nJail myjail rc status:\nsyslogd is running as pid 28180.\ncron is running as pid 52130.\nphp_fpm is running as pid 45558.\nnginx is running as pid 63975.\n===\u003e fcgiwrap profile: mediawiki\nfcgiwrap is running as pid 37682.\n```\n\n### Login into the running jail for administration\n```\n# jaildk login myjail\n```\n\nYou can use this to login into a database or execute commands inside the jail.\n\n\n### Updating a jail\n\nThe very first thing to do is to update the host system using `freebsd-update`.\n\nNext create a new base version:\n```\njaildk base -b `uname -r`\n```\nBut of course you can update a jail with the current base as well.\n\nNow you can clone of your jail with a new version:\n```\njaildk clone -s myjail -d myjail -o 20201106 -n 20210422\n```\n\nMount the build chroot for the new version:\n```\njaildk build myjail -m start -b `uname -r` -v 20210422\n```\n\nAnd finally chroot into the new jail and update it:\n```\njaildk blogin myjail\npkg update\n...\n```\n\nThe  last step  is  to remove  the current  running  jail, change  the\nversion in `etc/myjail.conf`, install and  start the new version. This\ncan be easily done with the following command:\n```\njaildk reinstall myjail -b `uname -r` -v 20210422\n```\n\nThis command also creates a copy of the current jail.conf.\n\nIf  there's anything  wrong you  can always  go back  to the  previous\nversion using the following command (using the previous base and version):\n```\njaildk reinstall myjail -b 12.2-RELEASE-p1 -v 20201106\n```\n\n## Advanced Features\n\nJaildk also  offers some advanced features  like automatically setting\nup and deleting ipfw rules or freezing  and thawing a jail (to make it\neasily portable).\n\n### Using the IPFW\n\nTo use  the IPFW on your  host you first  have to enable ipfw  in your\nhosts rc.conf  `firewall_enable=\"YES\"`.  You probably want  to set the\ndefault    firewalling-type    there    aswell,    check    out    the\n[FreeBSD handbook](https://www.freebsd.org/doc/handbook/firewalls-ipfw.html)\nfor further information.\n\nOnce enabled you also need to start ipfw by executing the rc script:\n\n`/etc/rc.d/ipfw start`.\n\nBe aware that inter-jail communication  is transfered via the loopback\ninterface (normally lo0) for which there  is a high priority allow any\nto any rule by default:\n\n`allow ip from any to any via lo`\n\nIn order  to control the  inter-jail communication you have  to delete\nthis rule first.\n\nIf an  ipfw.conf exists  for a jail  (e.g. /jail/etc/myjail/ipfw.conf)\nthe rules inside that config file are added when starting, and deleted\nwhen stopping  the jail.   E.g. allowing  HTTP/HTTPS traffic  for that\njail (webserver):\n\n`allow tcp from any to $ip setup keep-state`\n\nAs  demonstrated   in  the  previous   rule  `$ip`  is   reserved  and\nautomatically  replaced  with  the  jails   own  ip  (as  reported  by\n`jls`). The same  applies to the ipv6 address which  will be available\nas variable `$ip6`.  Also, all variables in the  jails `jail.conf` can\nbe used.\n\nIn order to make  these ipfw rules available on boot,  you need to add\nthe  following line  to `/etc/jail.conf`  in the  section of  the jail\nwhich uses custom ipfw rules:\n\n`exec.prestart = \"/jail/bin/jaildk ipfw $name\"`\n\nBe aware, that  the ipfw module will  only be executed if  the jail is\nrunning so  that we  can properly  determine the  ip addresses  of the\nrunning jail. **Note**: this might change in the future.\n\n### Using pf\n\nBeside                ipfw,               Free                supports\n[pf](https://www.freebsd.org/doc/de_DE.ISO8859-1/books/handbook/firewalls-pf.html)\nas well.  You  can use pf with `jaildk`.  Unlike  the ipfw module (see\nabove) it is a normal `install` module. That is it can be installed or\nreloaded before the jail is running (i.e. like the mount module).\n\nIn order to use `pf` with a jail, enable and configure it according to\nthe  FreeBSD  handbook linked  above.  It  is recommended  to  include\ngeneral block, scrup, state rules,  communication to and fro localhost\netc and just leave everything which is related to your jail.\n\nJust so that you know how such a global `/etc/pf.conf` file might look\nlike, here's a simple one:\n```shell\n# variables\next        = \"em0\"\nme         = \"your ipv4 address here\"\nme5        = \"your ipv6 address here/64\"\nloginports = \"{ 22, 5222, 443 }\"\nicmp_types = \"echoreq\"\n\n# tables. look at the contents of a table:\n#    pfctl -t bad_hosts -T show\n# remove an entry from a table:\n#    pfctl -t bad_hosts -T delete $ip\ntable \u003cbad_hosts\u003e persist\n\n# default policy\nset block-policy drop\n\n# optimize according to rfc's\nset optimization aggressive\n\n# normalisation\nscrub in all\nantispoof for $ext\n\n# allow localhost\npass quick on $local\n\n# additional default block rules w/ logging. to view the log:\n#    tcpdump -n -e -ttt -r /var/log/pflog\n# to view live log:\n#    tcpdump -n -e -ttt -i pflog0\nblock in log on $ext\nblock in log on $ext inet6\n\n# whoever makes it into those tables: you loose\nblock quick from \u003cbad_hosts\u003e\n\n# allow outgoing established sessions\npass out keep state\npass out inet6 keep state\n\n# allow troubleshooting\npass in on $ext inet proto icmp all icmp-type $icmp_types keep state\npass in on $ext inet proto udp from any to any port 33433 \u003e\u003c 33626 keep state\n\n# allow all icmpv6\npass in quick inet6 proto icmp6 all keep state\n\n# allow login but punish offenders\nblock quick from \u003cbad*hosts\u003e\npass in quick on $ext inet proto tcp from any to $me port $loginports \\\n     flags S/SAFR keep state \\\n     (max-src-conn-rate 10/60, \\\n      overload \u003cbad*hosts\u003e flush global) label ServicesTCP\npass in quick on $ext inet6 proto tcp from any to $me6 port $loginports \\\n     flags S/SAFR keep state \\\n     (max-src-conn-rate 10/60, \\\n     overload \u003cbad_hosts\u003e flush global) label ServicesTCP\n```\n\nInstall the ruleset with `service pf start`.\n\nNow that everything is prepared you can create a `/jail/etc/myjail/pf.conf` file for your\njail. Here's an  example I use for a webserver  jail, which includes a\ngit server:\n```shell\nip         = \"jail ip4 addr\"\nip6        = \"jail ip6 addr\"\nloginports = \"{ 22 }\"\nprodports  = \"{ 80, 443 }\"\next        = \"em0\"\n\n# dynamic block list\ntable \u003cblocked\u003e\n\n# restrict foreigners\nblock quick from \u003cblocked\u003e\npass in quick on $ext inet proto tcp from any to $ip port $loginports \\\n     flags S/SAFR keep state \\\n     (max-src-conn-rate 10/60, \\\n      overload \u003cblocked\u003e flush global) label ServicesTCP\n\n# allow production traffic v4\npass in quick on $ext proto tcp from any to $ip port $prodports keep state\n\n# allow production traffic v6\npass in quick inet6 proto tcp from any to $ip6 port $prodports keep state\n```\n\nThat's it already. Now install the jail as usual. You can also install\nthe pf ruleset for the jail separately:\n\n`jaildk install myjail -m start -r pf`\n\nTo take look at the rules, execute:\n\n`jaildk install myjail -m status -r pf`\n\nYou can of  course manipulate the ruleset  manually. `jaildk` installs\nrulesets  into  a jail  specific  anchor  using the  following  naming\nscheme: `/jail/\u003cjail name\u003e`. So, for example to view the rules, execute:\n\n`pfctl  -a /jail/myjail -s rules`\n\nManipulate a jail specific table:\n\n`pfctl  -a /jail/myjail -t blocked -T show`\n\n## Generating pf rule sets\n\nIt is also possible to let jaildk generate the pf rule sets from the\njail config. You can generate `map`s and `rule`s. Maps will be used\nfor mapping ipv4 connections and rules primarily for ipv6.\n\nA map is defined by a name. You can define many maps. Example:\n\n```toml\nmap_prom_exposed_port=\"9100\"\nmap_prom_exposed_ip=\"172.16.1.1\"\nmap_prom_allow_from=\"10.2.3.4\" # optional, default: any allowed\n```\n\nThen you reference the maps like this:\n\n```toml\nmaps=\"prom web git\"\n```\n\nYou can also specify the ip address used to connect to the outside:\n\n```toml\nmasq_ip=\"172.16.1.1\"\n```\n\nRules are being used for incoming ipv6 traffic, which is being routed\nonly. The semtantics are the same:\n\n```toml\nrules=\"web git\"\n\nrule_web_proto=\"tcp\"\nrule_web_port=\"{80,443}\"\n\nrule_git_proto=\"tcp\"\nrule_git_port=\"22\"\n```\n\n## Getting help\n\nAlthough I'm happy to hear from jaildk users in private email,\nthat's the best way for me to forget to do something.\n\nIn order to report a bug, unexpected behavior, feature requests\nor to submit a patch, please open an issue on github:\nhttps://github.com/TLINDEN/jaildk/issues.\n\n## Copyright and license\n\nThis software is licensed under the BSD license.\n\n## Authors\n\nT.v.Dein \u003ctom AT vondein DOT org\u003e\n\nF.Sass (Culsu)\n\n## Project homepage\n\nhttps://github.com/TLINDEN/jaildk\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fjaildk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlinden%2Fjaildk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fjaildk/lists"}