init.sh/README.md

# init.sh
**init.sh** is an automated configurator for system administrators. It's fully
written using Bash scripting and aims to be platform independent. Nevertheless,
it's requirements turns it naturally to Linux systems. It have long been tested
using Debian GNU/Linux, Devuan and different flavor of Ubuntu.

## Getting started
You should consider reading that document entirely before use. If you need
to create additional modules to meet your needs, consider reading the
[Developer's guide](./doc/dev.md).

Please also consider that your needs might meet the needs of someone else, thus
it would be a good idea to submit your module to init.sh source base.

## Design
**init.sh** relies on three different elements to work:

- the init.sh script, which provide a simple framework and libraries to do
simple taks and embed system dependent functions to provide system independent
function calls.
- modules that actually do the job, as possible on a system independant way
through the use of the framework and consisting on very small and simple tasks.
- multilevel configuration files, being simply Bash variables declaration.

Additionally some module might be ran regularly so it could be integrated in a
cron-like service.

### Command line

The **init.sh** script allows some command line parameters and some environement
variables to change it's behaviour.

The parameters are:

- **-m \<list\>, --module \<list\>**: Allows to manually give a module list and
overide the *MODULE_LIST* variable declaration. The list is a comma separated
module name. If that option is provided, the module list is mandatory.
- **-c, --check-only**: Do not launch any actions, only the checks are launched.
In that situation, no change should be done to the system.
- **-j, --jump**: Jump the checks and goes directly to system transformation.
That option should only be run after successfull checks (eg. after using the
\--checkonly option).
- **-k, --keep-going**: The scripts will try to continue even if errors occurs.
Thus some unrecoverable errors might stop the script anyway if it's not allowing
it to work. Please use with care as it might leads to unexpected results.
- **-r, --resume**: Restart an interrupted process with the last executed module
that failed.
- **-R, --no-root-check**: Disable checks on root rights (or the 0 UID).
- **-h, --help**: Display informations on command line usage.
- **-l, --logfile**: Specify a custom name for the logfile. Standard logfile is
named init-hostname-date-time.log in the log subdirectory. That file can also
be customized using the LOGFILE environement variable.
- **-v, --version**: Display version information, including available module
list and their version.

### Loading order and process

The first thing the script do is loading its libraries contained in the "lib"
directory. Any file situated in that directory ending with the .sh extention
will be loaded in alphabetical order. For that reason, error management
functions are placed in a file called aaa_error.sh, so it can be loaded first
and catch errors that could occurs while loading library files. In the opposite
the zzz_main_fct.sh file have to be loaded last, because it's widely using
previously declared libraries.

After that, a basic command line parameter treatment is done. That allows the
use of --version and --help options in user space. Those options just display
informations and don't require any superuser rights and exit at that point of
execution. Everything after that will require administrator rights and the
script will exit with error at that point if not superuser.

Next will be the log file creation and the loading of configuration files. At
this point a deeper analysis of command line option will be done, triggering
errors in case of unconsistency or incompatible options.

Finally checking processes are launched in their declaration order (cf.
configuration file). If no error occurs and after a confirmation prompt, final
treatment processes, those that actually makes changes, are launched.

Without the --keep-going option any error will imediatelly stop execution. Some
errors that could make the script impossible to execute will stop execution,
even if the --keep-going option is provided.

### Main configuration file

The main configuration file can be two different file. Either it's completely
generic and will be named **init.conf.sh** in the "conf" directory, either it
will be named after the current hostname of the computer in that same "conf"
directory. Please remember that the actual name will be used until the end of
the execution of init.sh. If one of your module change the hostname, the new
name can only be took into account after a new execution of init.sh.

Most of the variable you can declare to configure your host depends on the
module you will use. Please refer to module header to see what's available for
your use case.

After a module version upgrade you should check again headers as variable name
or stucture might change. A variable ca also be deleted, new variables could
appears, and so on.

It is heavily recommended to use includes technique to shorten your
configuration file and make a file for your organisation and an other one
for the Linux distribution you use. Remember that the declaration order matters,
so you can declare something on your organisation configuration file and
superseed it in your host configuration file. The only limit will be Bash
capabilities in terms of variable manipulation.

### Naming conventions

Because of internal mechanics the dash character is forbidden in module names.
Thus Bash language also forbid that character in variable name.

An other limit is, even if digits are allowed in module names and variable, they
can't be used as a leading character or worse the full name being only made of
digits. You can use as many digits you want in names but with at least a leading
alphabetical (or underscore) character, whatever the case of that character will
be.

You can use upper case and lower case as you wish, with underscore character,
even as leading character. Any other special character than alphanumerical or
underscore is completely forbidden.

Any submitted module to the central repository will have module name in lower
case with underscore to separate words and ease reading, and variable name upper
case with the same underscore as word separator.

### Basic module structure

Please note that modules are not supposed to contain any specific code for a
platform or a distribution even if nothing block you doing so. It is highly
recommended to use configurations files to introduce any platform dependent
code. Additionally, it will be possible to create system dependent modules using
naming convention in the style module_name.debian.x86_64.sh (awaited for version
2 of init.sh).

In the following exemple @template@ have to be replaced with the name of your
module with the filename @template@.sh. You can automatically create your new
module with the following command:

```shell
sed -e "s/@template@/module_name/g" -e "/^# .*/d" -e "s/^##/# /" template > \
    module_name.sh 
```

Versionning modules is up to you but the recommended behavior follows somme
standard rules. Considering a numbering as x.y.z:

- x might be incremented in case of major change, rewriting or deferent approach
on the way to have the job done, used variable could massively change ;
- y might be incremented in case simple functionnality addition or basic
improvements, existing variable might not change but new ones could appears ;
- z might be incremented only when correcting problems and/or bugs (+n fix => +n
to increment), variable should not change unless this is the only way to fix a
problem.

Unless only configuration files have been changed, any change in the code
implies an increment of a version number in the code **and** a git commit.

```shell
# Description @template@ module

# Module version
export VER_@template@="0.0.1"

# Module main code
@template@()
{
    # Code
}

# Pre-run checks code
precheck_@template@()
{
    # Code
}

# Any public fonction have to be exported
export -f @template@
export -f precheck_@template@
```
## Error code table

The following table is giving a list of error code with explanation:

| Code      | Meaning                             |
|:----------|:------------------------------------|
| 0         | No error                            |
| 1         | Command line syntax error           |
| 2         | Misuse of Bash builtin              |
| 3         | Missing library file or function    |
| 4         | No root rights                      |
| 5         | Malformed module list               |
| 6         | Unable to find configuration        |
| 7         | Misuse of script internal function  |
| 11        | Bad function call                   |
| 12        | Error copying files                 |
| 13        | Bad target filesystem               |
| 50..100   | Error in module execution           |
| 126       | Command exists but not executable   |
| 127       | Command not found                   |
| 128       | Abortion due to external cause      |
| 150..200  | Error in module checks              |
| 255       | Exit status out of range            |

Additionaly to exit codes, the script will try to produce a call stack to help
you in the debugging process. If you find a bug outside modules or in the basic
provided module, please contact the author. Of course, if you also have a patch,
your mail will be even more welcomed!

## Contact and more information

Everything except configuration files are licensed under BSD-3 license. Please
check licence file.

Please check [https://www.geoffray-levasseur.org/init](https://www.geoffray-levasseur.org/init)

You can mail author to fatalerrors \<at\> geoffray-levasseur \<dot\> org