From 45c829a4b01ce74104d8aad1796d70b4ec982d68 Mon Sep 17 00:00:00 2001 From: kjeld Schouten-Lebbing Date: Mon, 20 Jul 2020 15:31:31 +0200 Subject: [PATCH] migrate content to new wiki --- content/config options.md | 49 +++++++++++++++++++++ content/development/functions.md | 37 ++++++++++++++++ content/development/linked_configs.md | 19 +++++++++ content/index.md | 5 +++ content/migration/v1.1.x to v1.2.x.md | 61 +++++++++++++++++++++++++++ content/plugins/General | 5 +++ 6 files changed, 176 insertions(+) create mode 100644 content/config options.md create mode 100644 content/development/functions.md create mode 100644 content/development/linked_configs.md create mode 100644 content/migration/v1.1.x to v1.2.x.md create mode 100644 content/plugins/General diff --git a/content/config options.md b/content/config options.md new file mode 100644 index 00000000..9b55155f --- /dev/null +++ b/content/config options.md @@ -0,0 +1,49 @@ +## Config Options + +There are a lot of possibly configuration options in config.yml. +For jail specific config options, please see the wiki documentation for your specific jail. This page only list general and global config options, that are the same for every jail. + +## Global config options + +Global options apply to every jail. Use and change with caution. + +### dataset + +All config options under "dataset" change dataset creation and linking. The indentation and "dataset" flag are not optional. +All Datasets are auto-created if they do not exist already, no need to worry about creating them! + +- config: The dataset that is going to contain the persistant data for every jail. For example: Nextcloud user files for nextcloud or the actual database for mariadb. +- iocage: The dataset containing the iocage config. In FreeNAS often `poolname/iocage` +- media: The dataset that is going to contain all media files for plex, Sonarr, Radarr etc. Such as movies and music. Music, Movie etc. sub-datasets are auto-created. +- downloads: The dataset containging temporary download files. These are moved to media when finished. complete, incomplete etc. sub-datasets are auto-created. + +## jails +All config options under "jails" change default jail settings that are the same for every created jail. The indentation and "jails" flag are not optional. +- version: the current to-be-installed version for jails +- pkgs: packages that are installed to all created jails + +## (hidden) Auto created datasets + +Some datasets are auto created and can not be changed from the config file. This is done to ease troubleshooting. + +- `media/music` created as a sub-dataset of media, contains music +- `media/movies` created as a sub-dataset of media, contains movies +- `media/shows` created as a sub-dataset of media, contains tv-shows +- `downloads/complete` created as a sub-dataset of downloads, contains completed downloads +- `downloads/incomplete` created as a sub-dataset of downloads, contains not-yet-completed downloads + +## General config options + +### Networking + +Please be aware that dhcp is not actively supported, many of the jails depend on having a fixed IP-adress in the config file. +Some also depend on other jails having a fixed IP in the config file. Use of DHCP is on your own risk and might not work. + +- ip4_addr: To set a static IP (recommended), enter the desired ip address here. Leave blank (or remove the line) for DHCP. +- gateway: Set the gateway IP for static IP setup. Leave blank (or remove the line) for DHCP. + +### Advanced +- interfaces: Set the "interfaces" flag for iocage. Example: `vnet0:bridge0` (optional) +- dhcp: Set to "on" to force DHCP (not required for DHCP, see above) +- pkgs: Override the to-be-install packages for this jail (might break now or break updates) +- custom_iocage: Adds additional custom options to iocage create (NOT actively supported, use on your own risk) \ No newline at end of file diff --git a/content/development/functions.md b/content/development/functions.md new file mode 100644 index 00000000..5315938a --- /dev/null +++ b/content/development/functions.md @@ -0,0 +1,37 @@ +# Custom Functions + +## Intro + +With Jailman we have a number of functions that are custom. This document lists them and explains their use. Currently all custom functions are inculded in ./includes/global.sh + +## parse_yaml +This functions parses the yml config files. It does not support lists however and we highly advice not using indentations other than 2 spaces either. +It's only input is a yml file and it should be called as the argument of an eval statement. + +## gitupdate +This function triggers an update based on the branch it is given. +Currently only called in jailman.sh and it is fed the remote/branch combo it is currently on. + +## jailcreate +This function creates the actual jail based on a plugin. +It takes the jail name, looks up the plugin and proceeds accordingly. +It also creates things like basic mount points and such. while also checking if all required vars are filled. + +Currently only used in jailman.sh + +## initplugin +This function turns all config.yml variables for the jail inputed as $1 into local variables. This is not required (as variables are also available as `${!jail_$1_varname}`), but makes it easier for less experienced plugin creators to start working with Jailman +It takes only the Jailname as input. + +## exitplugin +This script does the "success" processing for an installation. It takes the name of the jail and a message (preferable a connection instruction), creates the "INSTALLED" file, does the last checks and outputs the successmessages +No additional scripting besides `echo`'s should be done after executing this script. + +## createmount +This function creates a dataset and mounts said dataset to a specific folder in a jail, while also creating required subfolders if needed. +It's easier to use and update than mounting folders manually, so it's the only allowed way to do so, unless very specific config is required (such as database datasets) +It has the following input options: +# $1 = jail name +# $2 = Dataset +# $3 = Target mountpoint +# $4 = fstab prefernces diff --git a/content/development/linked_configs.md b/content/development/linked_configs.md new file mode 100644 index 00000000..2239ad85 --- /dev/null +++ b/content/development/linked_configs.md @@ -0,0 +1,19 @@ +# Linking Jail Configs + +## Intro +To keep things simple, you can easily link jail configs together, for example you can make the settings of your MariaDB jail accessable to your nextcloud jail. +This can be done using a variable with the name: `link_$Name`, where $Name is just a description and the value in config.yml would be the actual jail to connect to. + +For example: +`link_testjail: thisismytestjail` + +Would link "thisismytestjail" to your current jail. + +## using linked jails + +Once setup one can reach all the variables of the linked jail using the following syntax: +`link_$Name_$variable` + +For example if we want the ipv4 address of the jail we linked earlier, during the install of another jail, we would do: +`link_testjail_ip4_addr` + diff --git a/content/index.md b/content/index.md index e69de29b..f2dbf1aa 100644 --- a/content/index.md +++ b/content/index.md @@ -0,0 +1,5 @@ +# Introduction +Welcome to Jailam. An open source effort to create an easy management tool for Freenas Jails. + +As this project is in its early stages, this wiki will serve the purpose of providing a foundation and a almost (not) up-to-date scripting reference to the underlying structure of jailman. + diff --git a/content/migration/v1.1.x to v1.2.x.md b/content/migration/v1.1.x to v1.2.x.md new file mode 100644 index 00000000..c00c76b3 --- /dev/null +++ b/content/migration/v1.1.x to v1.2.x.md @@ -0,0 +1,61 @@ +## v1.1.x to v1.2.x + +With v1.2 we made it possible to run multiple jails of the same type. +This is done by seperating jails (your individual installs) from plugins (our designs). + +Due to this change, the config file has been changed and thus you need to adapt your config file. + + +### Jails + +All your jails need to be indented by 2 spaces under a main group "jails" like this: + +` +jail: + plex: + plugin: plex + ip4_addr: 192.168.1.99/24 + gateway: 192.168.1.1 + beta: false +` + +Also note: +Where previously we used `plex: plex`, we can now just use `plex:` + +### plugins + +Every jail now requires a plugin to be defined. for example: +v1.1.x +` + +plex: plex + ip4_addr: 192.168.1.99/24 + gateway: 192.168.1.1 + plexpass: false +` + +In v1.2.x becomes: +` +jail: + plex: + plugin: plex + ip4_addr: 192.168.1.99/24 + gateway: 192.168.1.1 + beta: false +` + +### Plex + +Due to community feedback in v1.2.x "plexpass" has been renamed to "beta". + +### pkgs + +pkgs are removed from jail config in v1.2.x and are now part of the plugin. This way we can keep them up-to-date for you. + +### Documentation + +All jails now have wiki documentation pages and all basic jail values have been documented + +### Other changes + +Some other minor changes in config file values have been done, please refer to the example document and compare your config to the example \ No newline at end of file diff --git a/content/plugins/General b/content/plugins/General new file mode 100644 index 00000000..f12d6cb1 --- /dev/null +++ b/content/plugins/General @@ -0,0 +1,5 @@ +## General Info + +Blueprints are the blueprint on which your created jails are going to be based. + +More info TBD