Merge pull request #167 from Jip-Hop/develop

v1.4.0

README.md

@@ -90,13 +90,15 @@ jlmkr start myjail
 
 ### List Jails
 
+See list of jails (including running, startup state, GPU passthrough, distro, and IP).
+
 ```shell
 jlmkr list
 ```
 
 ### Execute Command in Jail
 
-You may want to execute a command inside a jail, for example from a shell script or a CRON job. The example below executes the `env` command inside the jail.
+You may want to execute a command inside a jail, for example manually from the TrueNAS shell, a shell script or a CRON job. The example below executes the `env` command inside the jail.
 
 ```shell
 jlmkr exec myjail env
@@ -118,6 +120,8 @@ Once you've created a jail, it will exist in a directory inside the `jails` dir
 
 ### Remove Jail
 
+Delete a jail and remove it's files (requires confirmation).
+
 ```shell
 jlmkr remove myjail
 ```
@@ -136,6 +140,8 @@ jlmkr restart myjail
 
 ### Jail Shell
 
+Switch into the jail's shell.
+
 ```shell
 jlmkr shell myjail
 ```
@@ -148,6 +154,8 @@ jlmkr status myjail
 
 ### Jail Logs
 
+View a jail's logs.
+
 ```shell
 jlmkr log myjail
 ```
@@ -158,17 +166,21 @@ Expert users may use the following additional commands to manage jails directly:
 
 ## Networking
 
-By default the jail will have full access to the host network. No further setup is required. You may download and install additional packages inside the jail. Note that some ports are already occupied by TrueNAS SCALE (e.g. 443 for the web interface), so your jail can't listen on these ports. This is inconvenient if you want to host some services (e.g. traefik) inside the jail. To workaround this issue when using host networking, you may disable DHCP and add several static IP addresses (Aliases) through the TrueNAS web interface. If you setup the TrueNAS web interface to only listen on one of these IP addresses, the ports on the remaining IP addresses remain available for the jail to listen on.
+By default a jails will use the same networking namespace, with access to all (physical) interfaces the TrueNAS host has access to. No further setup is required. You may download and install additional packages inside the jail. Note that some ports are already occupied by TrueNAS SCALE (e.g. 443 for the web interface), so your jail can't listen on these ports.
+
+Depending on the service this may be o.k. For example Home Assistant will bind to port 8123, leaving the 80 and 443 ports free from clashes for the TrueNAS web interface. You can then either connect to the service on 8123, or use a reverse proxy such as traefik.
+
+But clashes may happen if you want some services (e.g. traefik) inside the jail to listen on port 443. To workaround this issue when using host networking, you may disable DHCP and add several static IP addresses (Aliases) through the TrueNAS web interface. If you setup the TrueNAS web interface to only listen on one of these IP addresses, the ports on the remaining IP addresses remain available for the jail to listen on.
 
-See [Advanced Networking](./NETWORKING.md) for more.
+See [the networking docs](./docs/network.md) for more advanced options (bridge and macvlan networking).
 
 ## Docker
 
-Using the [docker config template](./templates/docker/README.md) is recommended if you want to run docker inside the jail. You may of course manually install docker inside a jail. But keep in mind that you need to add `--system-call-filter='add_key keyctl bpf'` (or disable seccomp filtering). It is [not recommended to use host networking for a jail in which you run docker](https://github.com/Jip-Hop/jailmaker/issues/119). Docker needs to manage iptables rules, which it can safely do in its own networking namespace (when using [bridge or macvlan networking](./NETWORKING.md) for the jail).
+Using the [docker config template](./templates/docker/README.md) is recommended if you want to run docker inside the jail. You may of course manually install docker inside a jail. But keep in mind that you need to add `--system-call-filter='add_key keyctl bpf'` (or disable seccomp filtering). It is [not recommended to use host networking for a jail in which you run docker](https://github.com/Jip-Hop/jailmaker/issues/119). Docker needs to manage iptables rules, which it can safely do in its own networking namespace (when using [bridge or macvlan networking](./docs/network.md) for the jail).
 
 ## Documentation
 
-Additional documentation contributed by the community can be found in [the docs directory](./docs/).
+Additional documentation can be found in [the docs directory](./docs/) (contributions are welcome!).
 
 ## Comparison
 
@@ -178,16 +190,6 @@ TODO: write comparison between systemd-nspawn (without `jailmaker`), LXC, VMs, D
 
 The rootfs image `jlmkr.py` downloads comes from the [Linux Containers Image server](https://images.linuxcontainers.org). These images are made for LXC. We can use them with systemd-nspawn too, although not all of them work properly. For example, the `alpine` image doesn't work well. If you stick with common systemd based distros (Debian, Ubuntu, Arch Linux...) you should be fine.
 
-## Tips & Tricks
-
-### Colorized bash prompt
-
-To visually distinguish between a root shell inside the jail and a root shell outside the jail, it's possible to colorize the shell prompt. When using a debian jail with the bash shell, you may run the following command to get a yellow prompt inside the jail (will be activated the next time you run `jlmkr shell myjail`):
-
-```bash
-echo "PS1='${debian_chroot:+($debian_chroot)}\[\033[01;33m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '" >> ~/.bashrc
-```
-
 ## Filing Issues and Community Support
 
 When in need of help or when you think you've found a bug in jailmaker, [please start with reading this](https://github.com/Jip-Hop/jailmaker/discussions/135).

docs/README.md

@@ -1,3 +1,5 @@
-Welcome to the jailmaker wiki!
+# Jailmaker Docs
+
+Welcome to the Jailmaker Docs!
 
 Use the sidebar to navigate the topics.

docs/basicconfig.md

@@ -1,4 +1,8 @@
-# User Management
+# Jailmaker Docs
+
+Anything described on this page is completely optional. You do NOT need to do anything of this in order to start using jailmaker.
+
+## User Management
 The root user (also known as the superuser or su) can access any file, make system changes, and lots of room for security vulnerabilities.
 For this reason you should aspire to run services as a non-root user.
 
@@ -10,28 +14,54 @@ Where username can be anything, but should reflect the service/jail's name for d
 Then a password should be created as some commands require a non-blank password to be inserted:
 `passwd USERNAME`
 
-If you want the ability to run commands as root, add the user to the sudo group
-`usermod -aG sudo USERNAME`
+If you want the ability to run commands as root, add the user to the sudo group:
+
+```sh
+usermod -aG sudo USERNAME
+```
 
 This WILL require a non-blank password, and any command run with sudo will be run as root not as the user. But it saves time compared to switching users to root to install/change things then switching back.
 
 ### Switch to user
-`su -l USERNAME`
+
+```sh
+su -l USERNAME
+```
 
 ### Put a password on Root
-While logged in as root run `passwd`
 
-# Common tweaks
+While logged in as root run `passwd`.
+
+## Common Tweaks
+
 ### Update repository list 
-`sudo apt update`
+
+```sh
+sudo apt update
+```
 
 ### Install common services 
-`sudo apt install nano wget curl git`
+
+```sh
+sudo apt install nano wget curl git
+```
 
 ### Set Static IP
-See `Networking`
 
-### Install Docker
+See [Networking](./network.md)
+
+### Colorized bash prompt
+
+To visually distinguish between a root shell inside the jail and a root shell outside the jail, it's possible to colorize the shell prompt. When using a debian jail with the bash shell, you may run the following command **inside the jail** to get a yellow prompt inside the jail (will be activated the next time you run `jlmkr shell myjail`):
+
+```bash
+echo "PS1='${debian_chroot:+($debian_chroot)}\[\033[01;33m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '" >> ~/.bashrc
 ```
+
+### Install Docker
+
+It's advised to use the [docker config template](../templates/docker/README.md). But you can install it manually like this as well:
+
+```sh
 apt install curl && cd /tmp && curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh && cd ~ && docker
 ```

docs/compatibility.md

@@ -1,12 +1,14 @@
-# TrueNAS Compatibility
+# Jailmaker Docs
+
+## TrueNAS Compatibility
 |   |   |
 |---|---|
 |TrueNAS Core|❌|
 |TrueNAS 22.12|✅|
 |TrueNAS 23.10|✅|
-|TrueNAS 24.04 nightly|✅|
+|TrueNAS 24.04|✅|
 
-# Distro Compatibility
+## Distro Compatibility
 |   |   |
 |---|---|
 |Debian 11 Bullseye|✅|