diff --git a/auto-generated-man-pages/onionjuggler.conf.5 b/auto-generated-man-pages/onionjuggler.conf.5 index 5633d3e..06319b7 100644 --- a/auto-generated-man-pages/onionjuggler.conf.5 +++ b/auto-generated-man-pages/onionjuggler.conf.5 @@ -1,62 +1,127 @@ .\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "ONIONJUGGLER.CONF" "5" "2022-08-29" "onionjuggler.conf 0.0.1" "Tor's System Manager Manual" +.TH "ONIONJUGGLER.CONF" "5" "2022-09-15" "onionjuggler.conf 0.0.1" "Tor's System Manager Manual" .hy .SH NAME .PP onionjuggler.conf - Configuration file for OnionJuggler .SH DESCRIPTION .PP -\f[B]onionjuggler.conf\f[R] is the configuration for OnionJuggler. +\f[B]onionjuggler\f[R] environment is easily customizable to any +Unix-like operating system due to be written in POSIX compliant +Shellscript and every tor directory can be chosen via variables. +.PP The default configuration file \f[I]/etc/onionjuggler/onionjuggler.conf\f[R] is replaced on every -upgrade user should assign variables inside -_/etc/onionjuggler/conf.d/*.conf_, files in this directory are parsed in -lexical order and overwrite the default configuration. +upgrade, so changes to this file are not persisted. +Because of this, it is advised not to edit this file. +This is the first configuration to file to be read and has the lowest +priority. +.PP +Files in \f[I]/etc/onionjuggler/conf.d/*.conf\f[R] are reserved to +packages that want to customize onionjuggler without overwriting the +main configuration file to avoid conflicts. +Users should avoid customizing files in this directory because it may +conflict or take lower precedence that files shipped by a package. .PP -The configuration file is parsed by the shell and interpreted as -variables. -When assigning a value to a variable, use double quotes to avoid word -splitting: \f[B]variable\f[R]=\f[I]\[dq]value\[dq]\f[R]. +The file \f[I]/usr/local/etc/onionjuggler/onionjuggler.conf\f[R] and +files in \f[I]/usr/local/etc/onionjuggler/conf.d/*.conf\f[R] are +reserved exclusively to the local administrator. +Any other entity must not write files to this directory. +These are the last files to be read and have the highest priority. +.PP +It is recommended to prefix all filenames in the \f[I]conf.d\f[R] +directory with a two-digit number and a dash, to simplify ordering of +the files and overrided default files with user defined setting using a +higher prefix number compared to the one shipped by the system. .PP Variables set to and empty string, either \f[I]var=\f[R] or -\f[I]var=\[dq]\[dq]\f[R], will run with default values. +\f[I]var=\[dq]\[dq]\f[R], will run with default values, that may not be +suitable for every system, so enforce the desired values by assigning +every configuration option. +.PP +Before running any script for the first time after changing a +configuration option, it is recommended to run the onionjuggler script +with the option \f[I]--getconf\f[R], as it will print what the +onionjuggler program read as options. +.SS Order configuration files are sourced: +.IP \[bu] 2 +/etc/onionjuggler/onionjuggler.conf +.PD 0 +.P +.PD +.IP \[bu] 2 +/etc/onionjuggler/conf.d/*.conf +.PD 0 +.P +.PD +.IP \[bu] 2 +/usr/local/etc/onionjuggler/onionjuggler.conf +.PD 0 +.P +.PD +.IP \[bu] 2 +/usr/local/etc/onionjuggler/conf.d/*.conf +.SS Rules for sourcing files: +.IP \[bu] 2 +when inside the \f[I]conf.d\f[R] directories, source files in lexical +order +.PD 0 +.P +.PD +.IP \[bu] 2 +file names must end with the \[aq].conf\[aq] extension +.SS Rules for writing the configuration files: +.IP \[bu] 2 +must be POSIX compliant Shellscript, else the source will fail +.PD 0 +.P +.PD +.IP \[bu] 2 +assign all variables to the desired values, else default values will be +used +.PD 0 +.P +.PD +.IP \[bu] 2 +variables should use double quotes to avoid unwanted expansions .SH OPTIONS .SS SYSTEM .TP \f[B]operating_system\f[R] Set operating system. -Recognized values: debian, tails, anon-gateway, anon-workstation, -fedora, arch, openbsd. +Recognized values: \f[I]debian\f[R], \f[I]tails\f[R], +\f[I]anon-gateway\f[R], \f[I]anon-workstation\f[R], \f[I]fedora\f[R], +\f[I]arch\f[R], \f[I]openbsd\f[R]. .TP \f[B]onionjuggler_plugin\f[R] Only allow specified plugins to run, if empty, allow every plugin. -(Default: all plugins). +(Default: \f[B]all plugins\f[R]). .TP \f[B]openssl_cmd\f[R] The OpenSSL command to create the certificate and private keys for Client Authorization using the x25519 algorithm. It must be the orignal OpenSSL v1.1 or later, not LibreSSL, as the latter does not support the aforementioned algorithm. -(Default: openssl). +(Default: \f[B]openssl\f[R]). .TP \f[B]webserver\f[R] Webserver to serve a website. Compatible with \f[I]nginx\f[R] and \f[I]apache2\f[R]. -(Default: nginx). +(Default: \f[B]nginx\f[R]). .TP \f[B]webserver_conf_dir\f[R] Webserver configuration directory of the virtual hosts. -(Default: /etc/nginx). +(Default: \f[B]/etc/${webserver}\f[R]). .TP \f[B]website_dir\f[R] Specify the directory to check for website folders. -(Default: /var/www). +(Default: \f[B]/var/www\f[R]). .TP \f[B]dialog_box\f[R] Terminal User Interface dialog box. Compatible with \f[I]dialog\f[R] and \f[I]whiptail\f[R]. -(Default: dialog). +(Default: \f[B]dialog\f[R]). .SS TOR DAEMON .TP \f[B]daemon_control\f[R] @@ -69,21 +134,21 @@ init), \f[I]rcctl\f[R] or \f[I]/etc/rc.d\f[R] (OpenRC), \f[I]sv\f[R] \f[B]tor_daemon\f[R] The tor service name. Common names are \f[I]tor\[at]default\f[R] and \f[I]tor\f[R]. -(Default: tor\[at]default) +(Default: \f[B]tor\[at]default\f[R]) .TP \f[B]tor_user\f[R] The tor user that runs the tor process. Common usernames are \f[I]debian-tor\f[R], \f[I]tor\f[R], *_tor* -(Default: debian-tor). +(Default: \f[B]debian-tor\f[R]). .TP \f[B]tor_conf_user_group\f[R] The /etc directory group owner. Normally \f[I]root\f[R] or \f[I]wheel\f[R]. -(Default: root:root) +(Default: \f[B]root:root\f[R]) .TP \f[B]tor_conf_dir\f[R] Base folder of torrc configuration. -(Default: /etc/tor). +(Default: \f[B]/etc/tor\f[R]). .TP \f[B]tor_conf\f[R] The tor configuration file that will be modified. @@ -91,7 +156,7 @@ It is recommended to a set a separate configuration file to be managed by onionjuggler, one that is included by tor, as there could be some unpredicated issues if the file is modified manually. Read about \f[I]%include\f[R] on the \f[I]torrc(1)\f[R] man. -(Default: /etc/tor/torrc). +(Default: \f[B]${tor_conf_dir}/torrc\f[R]). .TP \f[B]tor_main_torrc_conf\f[R] The main tor configuration file that tor reads. @@ -100,7 +165,7 @@ FILE\f[R] or \f[I]--torrc-file FILE\f[R]. This file won\[aq]t be modified unless it is set as value to the \f[B]tor_conf\f[R] option, its purpose is to fully verify the tor configuration. -(Default: /etc/tor/torrc). +(Default: \f[B]${tor_conf_dir}/torrc\f[R]). .TP \f[B]tor_defaults_torrc_conf\f[R] The tor defaults configuration file that tor reads. @@ -109,7 +174,7 @@ It is the file specified to the tor daemon with the option This file won\[aq]t be modified unless it is set as value to the \f[B]tor_conf\f[R] option, its purpose is to fully verify the tor configuration. -(Default: /etc/tor/torrc-defaults). +(Default: \f[B]${tor_conf}-defaults\f[R]). .TP \f[B]tor_data_dir\f[R] Specify the DataDirectory for tor. @@ -118,21 +183,24 @@ Specify the DataDirectory for tor. \f[B]tor_data_dir_services\f[R] Specify the HiddenServiceDir base directory, onion sevices data will be created inside this directory. -(Default: /var/lib/tor/services). +(Default: \f[B]${tor_data_dir}/services\f[R]). .TP \f[B]tor_data_dir_auth\f[R] Specify the ClientOnionAuthDir. -(Default: /var/lib/tor/onion_auth). +(Default: \f[B]${tor_data_dir}/onion_auth\f[R]). .SH FILES .TP \f[B]/etc/onionjuggler/onionjuggler.conf\f[R] -Default system configuration file. -Replaced on every upgrade. +Default configuration file. .TP \f[B]/etc/onionjuggler/conf.d/*.conf\f[R] -User configuration file. -Create files in the \f[I]conf.d\f[R] directory with the extension -\f[I].conf\f[R]. +Packers configuration directory. +.TP +\f[B]/usr/local/etc/onionjuggler/onionjuggler.conf\f[R] +Local administrator default configuration file. +.TP +\f[B]/usr/local/etc/onionjuggler/conf.d/*.conf\f[R] +Local administrador configuration directory. .SH EXAMPLES .IP \[bu] 2 \f[B]tor_user\f[R]=tor diff --git a/etc/onionjuggler/sample.conf b/etc/onionjuggler/sample.conf index 645a91c..90e4a7e 100644 --- a/etc/onionjuggler/sample.conf +++ b/etc/onionjuggler/sample.conf @@ -74,29 +74,29 @@ tor_conf_user_group="root:root" ## Base folder of torrc configuration. (Default: /etc/tor). tor_conf_dir="/etc/tor" ## -## The torrc that will be modified. (Default: /etc/tor/torrc). +## The torrc that will be modified. (Default: ${tor_conf_dir}/torrc). tor_conf="${tor_conf_dir}/torrc" ## ## The main torrc tor will read. ## The defaults torrc. Useful to fully read all configuration optons and fully ## verify tor configuration. This file won't be modified unless it is set ## to the variable tor_conf. -## (Default: /etc/tor/torrc). +## (Default: ${tor_conf_dir}/torrc). tor_main_torrc_conf="${tor_conf_dir}/torrc" ## ## The defaults torrc. Useful to fully read all configuration optons and fully ## verify tor configuration. This file won't be modified unless it is set ## to the variable tor_conf. -## (Default: /etc/tor/torrc-defaults). -tor_defaults_torrc_conf="${tor_conf_dir}/torrc-defaults" +## (Default: ${tor_conf}-defaults). +tor_defaults_torrc_conf="${tor_conf}-defaults" ## ## Specify the DataDirectory for tor. (Default: /var/lib/tor). tor_data_dir="/var/lib/tor" ## ## Specify the HiddenServiceDir base directory, onion sevices data -## will be created inside this directory. (Default: /var/lib/tor/services). +## will be created inside this directory. (Default: ${tor_data_dir}/services). tor_data_dir_services="${tor_data_dir}/services" ## -## Specify the ClientOnionAuthDir. (Default: /var/lib/tor/onion_auth). +## Specify the ClientOnionAuthDir. (Default: ${tor_data_dir}/onion_auth). tor_data_dir_auth="${tor_data_dir}/onion_auth" diff --git a/man/onionjuggler.conf.5.md b/man/onionjuggler.conf.5.md index f50fed5..6788b79 100644 --- a/man/onionjuggler.conf.5.md +++ b/man/onionjuggler.conf.5.md @@ -9,11 +9,57 @@ onionjuggler.conf - Configuration file for OnionJuggler # DESCRIPTION -**onionjuggler.conf** is the configuration for OnionJuggler. The default configuration file */etc/onionjuggler/onionjuggler.conf* is replaced on every upgrade user should assign variables inside _/etc/onionjuggler/conf.d/*.conf_, files in this directory are parsed in lexical order and overwrite the default configuration. +**onionjuggler** environment is easily customizable to any Unix-like operating +system due to be written in POSIX compliant Shellscript and every tor +directory can be chosen via variables. -The configuration file is parsed by the shell and interpreted as variables. When assigning a value to a variable, use double quotes to avoid word splitting: **variable**=*"value"*. +The default configuration file _/etc/onionjuggler/onionjuggler.conf_ is +replaced on every upgrade, so changes to this file are not persisted. +Because of this, it is advised not to edit this file. This is the first +configuration to file to be read and has the lowest priority. + +Files in _/etc/onionjuggler/conf.d/\*.conf_ are reserved to packages that +want to customize onionjuggler without overwriting the main configuration file +to avoid conflicts. Users should avoid customizing files in this directory +because it may conflict or take lower precedence that files shipped by a +package. + +The file _/usr/local/etc/onionjuggler/onionjuggler.conf_ and files in +_/usr/local/etc/onionjuggler/conf.d/\*.conf_ are reserved exclusively to the +local administrator. Any other entity must not write files to this directory. +These are the last files to be read and have the highest priority. + +It is recommended to prefix all filenames in the _conf.d_ +directory with a two-digit number and a dash, to simplify ordering of the files +and overrided default files with user defined setting using a higher prefix +number compared to the one shipped by the system. + +Variables set to and empty string, either *var=* or *var=""*, will run with +default values, that may not be suitable for every system, so enforce the +desired values by assigning every configuration option. + +Before running any script for the first time after changing a configuration +option, it is recommended to run the onionjuggler script with the option +_--getconf_, as it will print what the onionjuggler program read as options. + +### Order configuration files are sourced: + +- /etc/onionjuggler/onionjuggler.conf\ +- /etc/onionjuggler/conf.d/\*.conf\ +- /usr/local/etc/onionjuggler/onionjuggler.conf\ +- /usr/local/etc/onionjuggler/conf.d/\*.conf + +### Rules for sourcing files: + +- when inside the _conf.d_ directories, source files in lexical order\ +- file names must end with the '.conf' extension + +### Rules for writing the configuration files: + +- must be POSIX compliant Shellscript, else the source will fail\ +- assign all variables to the desired values, else default values will be used\ +- variables should use double quotes to avoid unwanted expansions -Variables set to and empty string, either *var=* or *var=""*, will run with default values. # OPTIONS @@ -21,31 +67,31 @@ Variables set to and empty string, either *var=* or *var=""*, will run with defa **operating_system** -: Set operating system. Recognized values: debian, tails, anon-gateway, anon-workstation, fedora, arch, openbsd. +: Set operating system. Recognized values: *debian*, *tails*, *anon-gateway*, *anon-workstation*, *fedora*, *arch*, *openbsd*. **onionjuggler_plugin** -: Only allow specified plugins to run, if empty, allow every plugin. (Default: all plugins). +: Only allow specified plugins to run, if empty, allow every plugin. (Default: **all plugins**). **openssl_cmd** -: The OpenSSL command to create the certificate and private keys for Client Authorization using the x25519 algorithm. It must be the orignal OpenSSL v1.1 or later, not LibreSSL, as the latter does not support the aforementioned algorithm. (Default: openssl). +: The OpenSSL command to create the certificate and private keys for Client Authorization using the x25519 algorithm. It must be the orignal OpenSSL v1.1 or later, not LibreSSL, as the latter does not support the aforementioned algorithm. (Default: **openssl**). **webserver** -: Webserver to serve a website. Compatible with *nginx* and *apache2*. (Default: nginx). +: Webserver to serve a website. Compatible with *nginx* and *apache2*. (Default: **nginx**). **webserver_conf_dir** -: Webserver configuration directory of the virtual hosts. (Default: /etc/nginx). +: Webserver configuration directory of the virtual hosts. (Default: **/etc/${webserver}**). **website_dir** -: Specify the directory to check for website folders. (Default: /var/www). +: Specify the directory to check for website folders. (Default: **/var/www**). **dialog_box** -: Terminal User Interface dialog box. Compatible with *dialog* and *whiptail*. (Default: dialog). +: Terminal User Interface dialog box. Compatible with *dialog* and *whiptail*. (Default: **dialog**). ## TOR DAEMON @@ -56,31 +102,31 @@ Variables set to and empty string, either *var=* or *var=""*, will run with defa **tor_daemon** -: The tor service name. Common names are *tor@default* and *tor*. (Default: tor@default) +: The tor service name. Common names are *tor@default* and *tor*. (Default: **tor@default**) **tor_user** -: The tor user that runs the tor process. Common usernames are *debian-tor*, *tor*, *_tor* (Default: debian-tor). +: The tor user that runs the tor process. Common usernames are *debian-tor*, *tor*, *_tor* (Default: **debian-tor**). **tor_conf_user_group** -: The /etc directory group owner. Normally *root* or *wheel*. (Default: root:root) +: The /etc directory group owner. Normally *root* or *wheel*. (Default: **root:root**) **tor_conf_dir** -: Base folder of torrc configuration. (Default: /etc/tor). +: Base folder of torrc configuration. (Default: **/etc/tor**). **tor_conf** -: The tor configuration file that will be modified. It is recommended to a set a separate configuration file to be managed by onionjuggler, one that is included by tor, as there could be some unpredicated issues if the file is modified manually. Read about _%include_ on the _torrc(1)_ man. (Default: /etc/tor/torrc). +: The tor configuration file that will be modified. It is recommended to a set a separate configuration file to be managed by onionjuggler, one that is included by tor, as there could be some unpredicated issues if the file is modified manually. Read about _%include_ on the _torrc(1)_ man. (Default: **${tor_conf_dir}/torrc**). **tor_main_torrc_conf** -: The main tor configuration file that tor reads. It is the file specified to the tor daemon with the option _-f FILE_ or _--torrc-file FILE_. This file won't be modified unless it is set as value to the **tor_conf** option, its purpose is to fully verify the tor configuration. (Default: /etc/tor/torrc). +: The main tor configuration file that tor reads. It is the file specified to the tor daemon with the option _-f FILE_ or _--torrc-file FILE_. This file won't be modified unless it is set as value to the **tor_conf** option, its purpose is to fully verify the tor configuration. (Default: **${tor_conf_dir}/torrc**). **tor_defaults_torrc_conf** -: The tor defaults configuration file that tor reads. It is the file specified to the tor daemon with the option _--defaults-torrc FILE_. This file won't be modified unless it is set as value to the **tor_conf** option, its purpose is to fully verify the tor configuration. (Default: /etc/tor/torrc-defaults). +: The tor defaults configuration file that tor reads. It is the file specified to the tor daemon with the option _--defaults-torrc FILE_. This file won't be modified unless it is set as value to the **tor_conf** option, its purpose is to fully verify the tor configuration. (Default: **${tor_conf}-defaults**). **tor_data_dir** @@ -88,22 +134,30 @@ Variables set to and empty string, either *var=* or *var=""*, will run with defa **tor_data_dir_services** -: Specify the HiddenServiceDir base directory, onion sevices data will be created inside this directory. (Default: /var/lib/tor/services). +: Specify the HiddenServiceDir base directory, onion sevices data will be created inside this directory. (Default: **${tor_data_dir}/services**). **tor_data_dir_auth** -: Specify the ClientOnionAuthDir. (Default: /var/lib/tor/onion_auth). +: Specify the ClientOnionAuthDir. (Default: **${tor_data_dir}/onion_auth**). # FILES **/etc/onionjuggler/onionjuggler.conf** -: Default system configuration file. Replaced on every upgrade. +: Default configuration file. **/etc/onionjuggler/conf.d/\*.conf** -: User configuration file. Create files in the _conf.d_ directory with the extension _.conf_. +: Packers configuration directory. + +**/usr/local/etc/onionjuggler/onionjuggler.conf** + +: Local administrator default configuration file. + +**/usr/local/etc/onionjuggler/conf.d/\*.conf** + +: Local administrador configuration directory. # EXAMPLES diff --git a/usr/share/onionjuggler/defaults.sh b/usr/share/onionjuggler/defaults.sh index f7342ad..96f223a 100755 --- a/usr/share/onionjuggler/defaults.sh +++ b/usr/share/onionjuggler/defaults.sh @@ -133,10 +133,16 @@ error_msg(){ notice "${red}ERROR: ${1}${nocolor}" 1>&2; exit 1; } ## helper for --getconf get_conf_values(){ - for key in operating_system onionjuggler_plugin openssl_cmd webserver webserver_conf_dir website_dir dialog \ - daemon_control tor_daemon tor_user tor_conf_user_group tor_conf_dir tor_conf tor_main_torrc_conf tor_defaults_torrc_conf tor_data_dir tor_data_dir_services tor_data_dir_auth; do + for key in onionjuggler_conf_included onionjuggler_conf_excluded \ + operating_system onionjuggler_plugin openssl_cmd \ + webserver webserver_conf_dir website_dir dialog \ + daemon_control tor_daemon tor_user tor_conf_user_group \ + tor_conf_dir tor_conf tor_main_torrc_conf \ + tor_defaults_torrc_conf tor_data_dir tor_data_dir_services \ + tor_data_dir_auth + do eval val='$'"${key}" - test -n "${val}" && printf '%s\n' "${key}=\"${val}\"" + printf '%s\n' "${key}=\"${val}\"" done } @@ -150,6 +156,7 @@ set_default_conf_values(){ : "${webserver:="nginx"}" : "${webserver_conf_dir:="/etc/${webserver}"}" : "${website_dir:="/var/www"}"; website_dir="${website_dir%*/}" + : "${dialog:="dialog"}" ## tor defaults : "${daemon_control:="systemctl"}"; daemon_control="${daemon_control%*/}" @@ -171,10 +178,38 @@ set_default_conf_values(){ ## 3. set default values for empty variables source_conf(){ test -f /etc/onionjuggler/onionjuggler.conf || error_msg "Default configuration file not found: /etc/onionjuggler/onionjuggler.conf" - for file in /etc/onionjuggler/onionjuggler.conf /etc/onionjuggler/conf.d/*; do + for file in \ + /etc/onionjuggler/onionjuggler.conf \ + /etc/onionjuggler/conf.d/* \ + /usr/local/etc/onionjuggler/onionjuggler.conf \ + /usr/local/etc/onionjuggler/conf.d/* + do file_name="${file##*/}" file_suffix="${file_name##*.}" - [ "${file}" != "*" ] && [ "${file_suffix}" = "conf" ] && . "${file}" + ## the '*' means the glob was not expanded because there are no files + #[ "${file}" != "*" ] && continue + if [ "${file_name}" != "*" ]; then + ## only source files ending with ".conf" + ## else add to the list of excluded files + if [ "${file_suffix}" = "conf" ]; then + ## only try to source files that can be read + ## else add to the list of excluded files + if test -r "${file}"; then + . "${file}" + onionjuggler_conf_included="${onionjuggler_conf_included} ${file}" + elif ! test -f "${file}"; then + ## assign nothing, file doesn't exist or is not a regular file + ## this happens with /usr/local/etc/onionjuggler/onionjuggler.conf + ## in the case it doesn't exist, just to avoid it beind added to the + ## excluded list + true + else + onionjuggler_conf_excluded="${onionjuggler_conf_excluded} ${file}" + fi + else + onionjuggler_conf_excluded="${onionjuggler_conf_excluded} ${file}" + fi + fi done set_default_conf_values }