238 lines
11 KiB
Markdown
238 lines
11 KiB
Markdown
# 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:
|
|
|
|
- **-f \<file\>, --file \<file\>**: Allows to specify which configuration file
|
|
to load manually. Tha option can be repeated to allows the loading of multiple
|
|
configuration file, the last overloading the previously defined ones in case of
|
|
identical variable name.
|
|
- **-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
|
|
\--check-only 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.
|
|
- **-s, --shell**: Launch a shell with entire script's environment for
|
|
debugging purpose. No action or modification is made to the system unless you
|
|
launch commands manually doing some.
|
|
- **-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
|
|
# Copyright (c) Year Your Name <your.mail@host.tld>
|
|
# ------------------------------------------------------------------------------
|
|
# <Licence header compatible with BSD-3 licence, you want to use>
|
|
# ------------------------------------------------------------------------------
|
|
# Variable list:
|
|
# * <VARNAME>: role explaination
|
|
# ------------------------------------------------------------------------------
|
|
|
|
# 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@
|
|
```
|
|
|
|
Unexported template function will work but won't be available in the integrated
|
|
debugging shell (see --shell option).
|
|
|
|
|
|
## 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
|