Script to create an iocage jail on TrueNAS for the latest guacamole pkg release, including Caddy 2.x, MariaDB, and Let's Encrypt

This script will create an iocage jail on TrueNAS CORE 13.0 with the latest release of guacamole pkg, along with its dependencies. It will obtain a trusted certificate from Let's Encrypt for the system, install it, and configure it to renew automatically. It will create the database and generate a strong root password and user password for the database system. It will configure the jail to store the database outside the jail, so it will not be lost in the event you need to rebuild the jail.

This script will work with TrueNAS CORE 13.0. Due to the EOL status of FreeBSD 12.0, it is unlikely to work reliably with earlier releases of FreeNAS.

This script works best when your installation is able to obtain a certificate from Let's Encrypt. When you use it this way, Caddy is able to handle all of the TLS-related configuration for you, obtain and renew certificates automatically, etc. In order for this to happen, you must meet the two requirements below:

• First, you must own or control a real Internet domain name. This script obtains a TLS encryption certificate from Let's Encrypt, who will only issue for public domain names. Thus, domains like guacamole.local, myguac.lan, or guac.home won't work.

• Second, one of these two conditions must be met in order for Let's Encrypt to validate your control over the domain name:

  • You must be able and willing to open ports 80 and 443 from the entire Internet to the jail, and leave them open. If this applies, do it before running this script.
  • DNS hosting for the domain name needs to be with a provider that Caddy supports. At this time, only Cloudflare is supported.

Cloudflare provides DNS hosting at no cost, and it's well-supported by Caddy. Cloudflare also provides Dynamic DNS service, if your desired Dynamic DNS client supports their API. If it doesn't, DNS-O-Matic is a Dynamic DNS provider that will interface with many DNS hosts including Cloudflare, has a much simpler API that's more widely supported, and is also free of charge.

If you aren't able or willing to obtain a certificate from Let's Encrypt, this script also supports configuring Caddy with a self-signed certificate, or with no certificate (and thus no HTTPS) at all.

You will need to create

• 1 Dataset named guacamole under which you will create 1 sub-dataset named db, which will store the database. If these are not present, a directory /guacamole will be created in $POOL_PATH with the obove mentioned subdirectory. You will want to create the datasets, otherwise the directories will just be created. Datasets make it easy to do snapshots etc... e.g. /mnt/mypool/apps/guacamole/db

Download the repository to a convenient directory on your TrueNAS system by changing to that directory and running git clone https://github.com/tschettervictor/truenas-iocage-guacamole. Then change into the new truenas-iocage-guacamole directory and create a file called guacamole-config with your favorite text editor. In its minimal form, it would look like this:

JAIL_IP="192.168.1.199"
DEFAULT_GW_IP="192.168.1.1"
POOL_PATH="/mnt/tank/apps"
HOST_NAME="YOUR_FQDN"
NO_CERT=1

Many of the options are self-explanatory, and all should be adjusted to suit your needs, but only a few are mandatory. The mandatory options are:

• JAIL_IP is the IP address for your jail. You can optionally add the netmask in CIDR notation (e.g., 192.168.1.199/24). If not specified, the netmask defaults to 24 bits. Values of less than 8 bits or more than 30 bits are invalid.
• DEFAULT_GW_IP is the address for your default gateway
• POOL_PATH is the path where the script will create the guacamole folder if the guacamole dataset was not created. It is best to create a dataset inside this path called guacamole.
• HOST_NAME is the fully-qualified domain name you want to assign to your installation. If you are planning to get a Let's Encrypt certificate (recommended), you must own (or at least control) this domain, because Let's Encrypt will test that control. If you're using a self-signed cert, or not getting a cert at all, it's only important that this hostname resolve to your jail inside your network.
• DNS_CERT, STANDALONE_CERT, SELFSIGNED_CERT, and NO_CERT determine which method will be used to generate a TLS certificate (or, in the case of NO_CERT, indicate that you don't want to use SSL at all). DNS_CERT and STANDALONE_CERT indicate use of DNS or HTTP validation for Let's Encrypt, respectively. One and only one of these must be set to 1.
• DNS_PLUGIN: If DNS_CERT is set, DNS_PLUGIN must contain the name of the DNS validation plugin you'll use with Caddy to validate domain control. At this time, the only valid value is cloudflare (but see below).
• DNS_TOKEN: If DNS_CERT is set, this must be set to a properly-scoped Cloudflare API Token. You will need to create an API token through Cloudflare's dashboard, which must have "Zone / Zone / Read" and "Zone / DNS / Edit" permissions on the zone (i.e., the domain) you're using for your installation. See this documentation for further details.
• CERT_EMAIL: If you're obtaining a cert from Let's Encrypt (i.e., either DNS_CERT or STANDALONE_CERT is set to 1), this must be set to a valid email address. You'll only receive mail there if your cert is about to expire (which should never happen), or if there are significant announcements from Let's Encrypt (which is unlikely to result in more than a few emails per year).

In addition, there are some other options which have sensible defaults, but can be adjusted if needed. These are:

• JAIL_NAME: The name of the jail, defaults to "guacamole"
• DB_PATH. This is the path to your database files. It defaults to POOL_PATH/guacamole/db
• INTERFACE: The network interface to use for the jail. Defaults to vnet0.
• JAIL_INTERFACES: Defaults to vnet0:bridge0, but you can use this option to select a different network bridge if desired. This is an advanced option; you're on your own here.
• VNET: Whether to use the iocage virtual network stack. Defaults to on.
• CERT_EMAIL is the email address Let's Encrypt will use to notify you of certificate expiration, or for occasional other important matters. This is optional. If you are using Let's Encrypt, though, it should be set to a valid address for the system admin.

If you're going to open ports 80 and 443 from the outside world to your jail, do so before running the script, and set STANDALONE_CERT to 1. If not, but you use a DNS provider that's supported by Caddy, set DNS_CERT to 1. If neither of these is true, use either NO_CERT (if you want to run without SSL at all) or SELFSIGNED_CERT (to generate a self-signed certificate--this is also the setting to use if you want to use a certificate from another source).

Also, HOST_NAME needs to resolve to your jail from inside your network. You'll probably need to configure this on your router, or on whatever other device provides DNS for your LAN. If you're unable to do so, you can edit the hosts file on your client computers to achieve this result, but consider installing something like Pi-Hole to give you control over your DNS.

Once you've downloaded the script and prepared the configuration file, run this script (script guacamole.log ./guacamole-jail.sh). The script will run for several minutes. When it finishes, your jail will be created, guacamole will be installed and configured, and you'll be shown the randomly-generated password for the default user ("guacadmin").

This configuration generated by this script will obtain certs from a non-trusted certificate authority by default. This is to prevent you from exhausting the Let's Encrypt rate limits while you're testing things out. Once you're sure things are working, you'll want to get a trusted cert instead. To do this, you can use a simple script that's included. As long as you haven't changed the default jail name, you can do this by running iocage exec guacamole /root/remove-staging.sh (if you have changed the jail name, replace "guacamole" in that command with the jail name).

This script has only been tested with Cloudflare, which works well.

Visit the Caddy download page to see the DNS authentication plugins currently available. To build Caddy with your desired plugin, use the last part of the "Package" on that page as DNS_PLUGIN in your guacamole-config file. E.g., if the package name is github.com/caddy-dns/cloudflare, you'd set DNS_PLUGIN=cloudflare. From that page, there are also links to the documentation for each plugin, which will describe what credentials are needed. If your provider needs only an API token (as is the case with Cloudflare, and apparently with DNSPod and Gandi), you'll likely be able to set DNS_TOKEN=long_api_token in the guacamole-config file and not need to do anything else. If your provider requires different credentials, you'll need to modify the Caddyfile to account for them.

• Reinstalls work as expected when the previous database is present.
• This script copies the default server.xml file with the addition of the remoteIpHeader Valve, with the value set to 127.0.0.1 This is necessary for guacamole to properly log sessions with the correct IP. If set behind another reverse proxy, this value can be changed to the proxy IP, or alternately , the Caddyfile can be edited to trust the reverse proxy. The file is at /usr/local/apache-tomcat-9.0/conf/server.xml
• Guacamole Trusted Proxy https://guacamole.apache.org/doc/gug/reverse-proxy.html
• Caddy Trusted Proxy https://caddyserver.com/docs/caddyfile/options#trusted-proxies