support /usr/local/etc/

print include and excluded files with --getconf, so it can be better understood which files are being include and which are not

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,29 +134,29 @@ 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.
 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

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"