├── .gitignore ├── LICENSE ├── README.md └── heimdall-jail.sh /.gitignore: -------------------------------------------------------------------------------- 1 | heimdall-config 2 | *.log 3 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 2-Clause License 2 | 3 | Copyright (c) 2019, Dan Brown 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | 2. Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 20 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 25 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # freenas-iocage-heimdall 2 | Script to create a FreeNAS jail and install [Heimdall Dashboard](https://heimdall.site/) in it 3 | 4 | # Installation 5 | Change to a convenient directory, clone the repository using `git clone https://github.com/danb35/freenas-iocage-heimdall`, change to the freenas-iocage-heimdall directory, and create a configuration file called `heimdall-config` with your favorite text editor (if you don't have a favorite text editor, `nano` is a good choice--run `nano heimdall-config`). Then run the script with `script heimdall.log ./heimdall-jail.sh`. 6 | 7 | ## Configuration options 8 | In its minimal form, the configuration file would look like this: 9 | ``` 10 | JAIL_IP="192.168.1.78" 11 | DEFAULT_GW_IP="192.168.1.1" 12 | POOL_PATH="/mnt/tank" 13 | ``` 14 | 15 | * JAIL_IP: The IP address to assign the jail. You may optionally specify a netmask in CIDR notion. If none is specified, the default is /24. Values of less than 8 bits or more than 30 bits will also result in a 24-bit netmask. 16 | * DEFAULT_GW_IP: The IP address of your default gateway. 17 | * POOL_PATH: The path to your main data pool (e.g., `/mnt/tank`). The Caddyfile and Heimdall installation files (i.e., the web pages themselves) will be stored there, in $POOL_PATH/apps/heimdall. If you have more than one pool, choose the one you want to use for this purpose. 18 | * FILE: Optional. The filename to download, which identifies the version of Heimdall to download. Default is 2.6.1. To check for a more recent release, see the [Heimdall release page](https://github.com/linuxserver/Heimdall/releases). If a more recent version has been released, set this variable to the full file name of the download, e.g., `FILE="v2.6.4.tar.gz"`. 19 | * JAIL_NAME: Optional. The name of the jail. If not given, will default to "heimdall". 20 | 21 | ## Post-install configuration 22 | This script uses the [Caddy](https://caddyserver.com/) web server, which supports automatic HTTPS, reverse proxying, and many other powerful features. It is configured using a Caddyfile, which is stored at `/usr/local/www/Caddyfile` in your jail, and under `/apps/heimdall/` on your main data pool. You can edit it as desired to enable these or other features. For further information, see [my Caddy script](https://github.com/danb35/freenas-iocage-caddy), specifically the included `Caddyfile.example`, or the [Caddy docs](https://caddyserver.com/docs/caddyfile). 23 | 24 | This script installs Caddy from the FreeBSD binary package, which does not include any [DNS validation plugins](https://caddyserver.com/download). If you need to use these, you'll need to build Caddy from source. The tools to do this are installed in the jail. To build Caddy, run these commands: 25 | ``` 26 | go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest 27 | cp /root/go/bin/xcaddy /usr/local/bin/xcaddy 28 | xcaddy build --output /usr/local/bin/caddy --with github.com/caddy-dns/${DNS_PLUGIN} 29 | ``` 30 | ...with `${DNS_PLUGIN}` representing the name of the plugin, listed on the page linked above. You'll then need to modify your configuration as described in the Caddy docs. 31 | 32 | ## Self-signed or local CA 33 | If you're using self-signed certs, or a local certificate authority, for any of your local resources, you'll need to add the relevant root certificate to the trust store for your jail, or Heimdall won't be able to communicate securely with those resources. To do this, 34 | 35 | * Enter the jail with `iocage console heimdall` 36 | * Place a copy of the cert in `/usr/share/certs/trusted/(descriptive cert name).pem`. 37 | * `cd /etc/ssl/certs` 38 | * `openssl x509 -noout -hash -in /usr/share/certs/trusted/(descriptive cert name).pem` 39 | * This will return a hash value like `e94f1467` 40 | * `ln -s /usr/share/certs/trusted/(descriptive cert name).pem (hash value).0` 41 | * Exit and restart the jail 42 | 43 | # Support 44 | Questions and discussion should be directed to https://forums.truenas.com/t/scripted-heimdall-dashboard-installation/2771 45 | -------------------------------------------------------------------------------- /heimdall-jail.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Install Heimdall Dashboard (https://github.com/linuxserver/Heimdall) 4 | # in a FreeNAS jail 5 | 6 | # https://forum.freenas-community.org/t/install-heimdall-dashboard-in-a-jail-script-freenas-11-2/35 7 | 8 | # Check for root privileges 9 | if ! [ $(id -u) = 0 ]; then 10 | echo "This script must be run with root privileges" 11 | exit 1 12 | fi 13 | 14 | ##### 15 | # 16 | # General configuration 17 | # 18 | ##### 19 | 20 | # Initialize defaults 21 | JAIL_NAME="heimdall" 22 | JAIL_IP="" 23 | DEFAULT_GW_IP="" 24 | POOL_PATH="" 25 | FILE="v2.6.1.tar.gz" 26 | DNS_PLUGIN="" 27 | CONFIG_NAME="heimdall-config" 28 | 29 | # Check for heimdall-config and set configuration 30 | SCRIPT=$(readlink -f "$0") 31 | SCRIPTPATH=$(dirname "${SCRIPT}") 32 | if ! [ -e "${SCRIPTPATH}"/"${CONFIG_NAME}" ]; then 33 | echo "${SCRIPTPATH}/${CONFIG_NAME} must exist." 34 | exit 1 35 | fi 36 | . "${SCRIPTPATH}"/"${CONFIG_NAME}" 37 | 38 | # Error checking and config sanity check 39 | if [ -z "${JAIL_IP}" ]; then 40 | echo 'Configuration error: JAIL_IP must be set' 41 | exit 1 42 | fi 43 | if [ -z "${DEFAULT_GW_IP}" ]; then 44 | echo 'Configuration error: DEFAULT_GW_IP must be set' 45 | exit 1 46 | fi 47 | if [ -z "${POOL_PATH}" ]; then 48 | echo 'Configuration error: POOL_PATH must be set' 49 | exit 1 50 | fi 51 | 52 | # Extract IP and netmask, sanity check netmask 53 | IP=$(echo ${JAIL_IP} | cut -f1 -d/) 54 | NETMASK=$(echo ${JAIL_IP} | cut -f2 -d/) 55 | if [ "${NETMASK}" = "${IP}" ] 56 | then 57 | NETMASK="24" 58 | fi 59 | if [ "${NETMASK}" -lt 8 ] || [ "${NETMASK}" -gt 30 ] 60 | then 61 | NETMASK="24" 62 | fi 63 | 64 | RELEASE=$(freebsd-version | cut -d - -f -1)"-RELEASE" 65 | # If release is 13.1-RELEASE, change to 13.2-RELEASE 66 | if [ "${RELEASE}" = "13.1-RELEASE" ]; then 67 | RELEASE="13.2-RELEASE" 68 | fi 69 | 70 | mountpoint=$(zfs get -H -o value mountpoint $(iocage get -p)/iocage) 71 | 72 | # Create the jail, pre-installing needed packages 73 | cat <<__EOF__ >/tmp/pkg.json 74 | { 75 | "pkgs":[ 76 | "nano", 77 | "caddy", 78 | "php82", 79 | "php82-mbstring", 80 | "php82-zip", 81 | "php82-tokenizer", 82 | "php82-pdo", 83 | "php82-pdo_sqlite", 84 | "php82-filter", 85 | "php82-xml", 86 | "php82-ctype", 87 | "php82-dom", 88 | "php82-fileinfo", 89 | "sqlite3", 90 | "php82-session", 91 | "go", 92 | "git" 93 | ] 94 | } 95 | __EOF__ 96 | 97 | if ! iocage create --name "${JAIL_NAME}" -p /tmp/pkg.json -r "${RELEASE}" \ 98 | ip4_addr="vnet0|${IP}/${NETMASK}" defaultrouter="${DEFAULT_GW_IP}" boot="on" \ 99 | host_hostname="${JAIL_NAME}" vnet="on" 100 | then 101 | echo "Failed to create jail" 102 | exit 1 103 | fi 104 | rm /tmp/pkg.json 105 | 106 | # Store Caddyfile and data outside the jail 107 | mkdir -p "${POOL_PATH}"/apps/heimdall 108 | iocage exec "${JAIL_NAME}" mkdir -p /usr/local/www/ 109 | iocage fstab -a "${JAIL_NAME}" "${POOL_PATH}"/apps/heimdall /usr/local/www nullfs rw 0 0 110 | 111 | # Create Caddyfile 112 | cat <<__EOF__ >"${mountpoint}"/jails/"${JAIL_NAME}"/root/usr/local/www/Caddyfile 113 | :80 { 114 | encode gzip 115 | 116 | log { 117 | output file /var/log/heimdall_access.log 118 | } 119 | 120 | root * /usr/local/www/html/public 121 | file_server 122 | 123 | php_fastcgi 127.0.0.1:9000 124 | 125 | # Add reverse proxy directives here if desired 126 | 127 | } 128 | __EOF__ 129 | 130 | # Download and install Heimdall 131 | iocage exec "${JAIL_NAME}" mkdir -p /usr/local/www/html 132 | iocage exec "${JAIL_NAME}" fetch -o /tmp https://github.com/linuxserver/Heimdall/archive/"${FILE}" 133 | iocage exec "${JAIL_NAME}" tar zxf /tmp/"${FILE}" --strip 1 -C /usr/local/www/html/ 134 | iocage exec "${JAIL_NAME}" mkdir -p /usr/local/www/html/storage/app/public/icons 135 | iocage exec "${JAIL_NAME}" sh -c 'find /usr/local/www/ -type d -print0 | xargs -0 chmod 2775' 136 | iocage exec "${JAIL_NAME}" touch /usr/local/www/html/database/app.sqlite 137 | iocage exec "${JAIL_NAME}" chmod 664 /usr/local/www/html/database/app.sqlite 138 | iocage exec "${JAIL_NAME}" chown -R www:www /usr/local/www/html/ 139 | iocage exec "${JAIL_NAME}" sysrc php_fpm_enable=YES 140 | iocage exec "${JAIL_NAME}" sysrc caddy_enable=YES 141 | iocage exec "${JAIL_NAME}" sysrc caddy_config=/usr/local/www/Caddyfile 142 | iocage exec "${JAIL_NAME}" cp /usr/local/www/html/.env.example /usr/local/www/html/.env 143 | iocage exec "${JAIL_NAME}" sh -c 'cd /usr/local/www/html/ && php artisan key:generate' 144 | iocage exec "${JAIL_NAME}" service php-fpm start 145 | iocage exec "${JAIL_NAME}" service caddy start 146 | --------------------------------------------------------------------------------