fatalerrors/init.sh
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: orthography and grammar fixed, added table of content

Browse Source
This commit is contained in:
levasseur
2021-09-24 12:07:35 +02:00
parent f53b7c8f6f
commit 1154fa5800
2 changed files with 107 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
README.md
View File

@@ -1,10 +1,22 @@
# init.sh # init.sh
**init.sh** is an automated configurator for system administrators. It's fully **init.sh** is an automated configurator for system administrators. It's fully
written using Bash scripting and aims to be platform independent. Nevertheless, 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 its requirements turn it naturally to Linux systems. It has long been tested
using Debian GNU/Linux, Devuan and different flavors of Ubuntu. using Debian GNU/Linux, Devuan and different flavors of Ubuntu.
## Getting started ## Table of content
* [1. Getting started](#1-getting-started)
* [2. Design](#2-design)
+ [2.1. Command line](#21-command-line)
+ [2.2. Loading order and process](#22-loading-order-and-process)
+ [2.3. Main configuration file](#23-main-configuration-file)
+ [2.4. Naming conventions](#24-naming-conventions)
+ [2.5. Basic module structure](#25-basic-module-structure)
* [3. Error code table](#3-error-code-table)
* [4. Contact and more information](#4-contact-and-more-information)
## 1. Getting started
You should consider reading that document entirely before use. If you need You should consider reading that document entirely before use. If you need
to create additional modules to meet your needs, consider reading the to create additional modules to meet your needs, consider reading the
[Developer's guide](./doc/dev.md). [Developer's guide](./doc/dev.md).
@@ -12,119 +24,120 @@ to create additional modules to meet your needs, consider reading the
Please also consider that your needs might meet the needs of someone else, thus 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. it would be a good idea to submit your module to init.sh source base.
## Design ## 2. Design
**init.sh** relies on three different elements to work: **init.sh** relies on three different elements to work:
- the init.sh script, which provide a simple framework and libraries to do - the init.sh script, which provide a simple framework and libraries to do
simple taks and embed system dependent functions to provide system independent simple tasks and embed system dependent functions to provide system independent
function calls. function calls.
- modules that actually do the job, as possible on a system independant way - modules that actually do the job, as possible on a system independent way
through the use of the framework and consisting on very small and simple tasks. through the use of the framework and consisting of very small and simple tasks.
- multilevel configuration files, being simply Bash variables declaration. - multilevel configuration files, being simply Bash variables declaration.
Additionally some module might be ran regularly so it could be integrated in a Additionally, some module might be run regularly, so it could be integrated in a
cron-like service. cron-like service.
### Command line ### 2.1. Command line
The **init.sh** script allows some command line parameters and some environement The **init.sh** script allows some command line parameters and some environment
variables to change it's behaviour. variables to change its behavior.
The parameters are: The parameters are:
- **-f \<file\>, --file \<file\>**: Allows to specify which configuration file - **-f \<file\>, --file \<file\>**: Allows specifying which configuration file
to load manually. Tha option can be repeated to allows the loading of multiple to load manually. That option can be repeated to allow the loading of multiple
configuration file, the last overloading the previously defined ones in case of configuration file, the last overloading the previously defined ones in case of
identical variable name. identical variable name.
- **-m \<list\>, --module \<list\>**: Allows to manually give a module list and - **-m \<list\>, --module \<list\>**: Allows to manually give a module list and
overide the *MODULE_LIST* variable declaration. The list is a comma separated override the *MODULE_LIST* variable declaration. The list is a comma separated
module name. If that option is provided, the module list is mandatory. 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. - **-c, --check-only**: Do not launch any actions, only the checks are launched.
In that situation, no change should be done to the system. In that situation, no change should be done to the system.
- **-j, --jump**: Jump the checks and goes directly to system transformation. - **-j, --jump**: Jump the checks and goes directly to system transformation.
That option should only be run after successfull checks (eg. after using the That option should only be run after successful checks (e.g. after using the
\--check-only option). \--check-only option).
- **-k, --keep-going**: The scripts will try to continue even if errors occurs. - **-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 Thus, some unrecoverable errors might stop the script anyway if it's not
it to work. Please use with care as it might leads to unexpected results. allowing it to work. Please use with care as it might lead to unexpected
results.
- **-r, --resume**: Restart an interrupted process with the last executed module - **-r, --resume**: Restart an interrupted process with the last executed module
that failed. that failed.
- **-R, --no-root-check**: Disable checks on root rights (or the 0 UID). - **-R, --no-root-check**: Disable checks on root rights (or the 0 UID).
- **-h, --help**: Display informations on command line usage. - **-h, --help**: Display information on command line usage.
- **-s, --shell**: Launch a shell with entire script's environment for - **-s, --shell**: Launch a shell with entire script's environment for
debugging purpose. No action or modification is made to the system unless you debugging purpose. No action or modification is made to the system unless you
launch commands manually doing some. launch commands manually doing some.
- **-l, --logfile**: Specify a custom name for the logfile. Standard logfile is - **-l, --logfile**: Specify a custom name for the log file. Standard log file
named init-hostname-date-time.log in the log subdirectory. That file can also is named init-hostname-date-time.log in the log subdirectory. That file can also
be customized using the LOGFILE environement variable. be customized using the LOGFILE environment variable.
- **-v, --version**: Display version information, including available module - **-v, --version**: Display version information, including available module
list and their version. list and their version.
The options cannot be concatenated like most of Unix binaries allows. For The options cannot be concatenated like most of Unix binaries allows. For
exemple you cannot write "*-rR*", you have to write "*-r -R*". example you cannot write "*-rR*", you have to write "*-r -R*".
### Loading order and process ### 2.2. Loading order and process
The first thing the script do is loading its libraries contained in the "*lib*" 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 directory. Any file situated in that directory ending with the .sh extension
will be loaded in alphabetical order. For that reason, error management 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 functions are placed in a file called aaa_error.sh, so it can be loaded first
and catch errors that could occurs while loading others library files. In the and catch errors that could occur while loading other library files. In the
opposite the zzz_main_fct.sh file have to be loaded last, because it's widely opposite the zzz_main_fct.sh file have to be loaded last, because it's widely
using previously declared libraries. using previously declared libraries.
After that, a basic command line parameter treatment is done. That allows the 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 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 information and don't require any superuser rights and exit at that point of
execution. Everything after that will require administrator rights and the execution. Everything after that will require administrator rights and the
script will exit with error at that point if not superuser. 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 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 this point a deeper analysis of command line option will be done, triggering
errors in case of unconsistency or incompatible options. errors in case of inconsistency or incompatible options.
Finally checking processes are launched in their declaration order (cf. Finally, checking processes are launched in their declaration order (cf.
configuration file). If no error occurs and after a confirmation prompt, final configuration file). If no error occurs and after a confirmation prompt, final
treatment processes, those that actually makes changes, are launched. treatment processes, those that actually makes changes, are launched.
Without the *--keep-going* option any error will imediatelly stop execution. Without the *--keep-going* option, any error will immediately stop execution.
Some errors that could make the script impossible to execute will stop Some errors that could make the script impossible to execute will stop
execution, even if the *--keep-going* option is provided. execution, even if the *--keep-going* option is provided.
### Main configuration file ### 2.3. Main configuration file
The main configuration file can be two different file. Either it's completely The main configuration file can be two different files. Either it's completely
generic and will be named **init.conf.sh** in the "conf" directory, either it 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" 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 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 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. name can only be taken into account after a new execution of init.sh.
Most of the variable you can declare to configure your host depends on the 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 module you will use. Please refer to module header to see what's available for
your use case. your use case.
After a module version upgrade you should check again headers as variable name After a module version upgrade, you should check again headers as variable name
or stucture might change. A variable can also be deleted, new variables could or structure might change. A variable can also be deleted, new variables could
appears, and so on. appears, and so on.
It is heavily recommended to use includes technique to shorten your It is heavily recommended to use includes technique to shorten your
configuration file and make a file for your organisation and an other one configuration file and make a file for your organization and another one
for the Linux distribution you use. Remember that the declaration order matters, for the Linux distribution you use. Remember that the declaration order matters,
so you can declare something on your organisation configuration file and so you can declare something on your organization configuration file and
superseed it in your host configuration file. The only limit will be Bash supersede it in your host configuration file. The only limit will be Bash
capabilities in terms of variable manipulation. capabilities in terms of variable manipulation.
### Naming conventions ### 2.4. Naming conventions
Because of internal mechanics the dash character is forbidden in module names. Because of internal mechanics, the dash character is forbidden in module names.
Thus Bash language also forbid that character in variable name. Thus, Bash language also forbid that character in variable name.
Another limit is, even if digits are allowed in module names and variable, they Another 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 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 digits. You can use as many digits you want in names, but with at least a
alphabetical (or underscore) character, whatever the case of that character will leading alphabetical (or underscore) character, whatever the case of that
be. character will be.
You can use upper case and lower case as you wish, with underscore character, 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 even as leading character. Any other special character than alphanumerical or
@@ -134,16 +147,16 @@ 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 underscore to separate words and ease reading, and variable name upper
case with the same underscore as word separator. case with the same underscore as word separator.
### Basic module structure ### 2.5. Basic module structure
Please note that modules are not supposed to contain any specific code for a 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 platform or a distribution, even if nothing block you doing so. It is highly
recommended to use configurations files to introduce any platform dependent recommended to use configurations files to introduce any platform dependent
code. Additionally, it will be possible to create system dependent modules using 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 naming convention in the style module_name.debian.x86_64.sh (awaited for version
2 of init.sh). 2 of init.sh).
In the following exemple @template@ have to be replaced with the name of your In the following example, @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 filename @template@.sh. You can automatically create your new
module with the following command: module with the following command:
@@ -152,14 +165,15 @@ sed -e "s/@template@/module_name/g" -e "/^# .*/d" -e "s/^##/# /" template > \
module_name.sh module_name.sh
``` ```
Versionning modules is up to you but the recommended behavior follows somme Versioning modules is up to you, but the recommended behavior follows some
standard rules. Considering a numbering as x.y.z: standard rules. Considering a numbering as x.y.z:
- x might be incremented in case of major change, rewriting or deferent approach - x might be incremented in case of major change, rewriting or different
on the way to have the job done, used variable could massively change ; approach on the way to have the job done, the used variable could massively
- y might be incremented in case simple functionnality addition or basic change;
improvements, existing variable might not change but new ones could appears ; - y might be incremented in case of simple functionality addition or basic
- z might be incremented only when correcting problems and/or bugs (+n fix => +n improvements, existing variable might not change, but new ones could appear;
- 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 to increment), variable should not change unless this is the only way to fix a
problem. problem.
@@ -201,7 +215,7 @@ Unexported template function will work but won't be available in the integrated
debugging shell (see --shell option). debugging shell (see --shell option).
## Error code table ## 3. Error code table
The following table is giving a list of error code with explanation: The following table is giving a list of error code with explanation:
@@ -209,7 +223,7 @@ The following table is giving a list of error code with explanation:
|:----------|:------------------------------------| |:----------|:------------------------------------|
| 0 | No error | | 0 | No error |
| 1 | Command line syntax error | | 1 | Command line syntax error |
| 2 | Misuse of Bash builtin | | 2 | Misuse of Bash built-in |
| 3 | Missing library file or function | | 3 | Missing library file or function |
| 4 | No root rights | | 4 | No root rights |
| 5 | Malformed module list | | 5 | Malformed module list |
@@ -225,15 +239,15 @@ The following table is giving a list of error code with explanation:
| 150..200 | Error in module checks | | 150..200 | Error in module checks |
| 255 | Exit status out of range | | 255 | Exit status out of range |
Additionaly to exit codes, the script will try to produce a call stack to help Additionally 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 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, provided module, please contact the author. Of course, if you also have a patch,
your mail will be even more welcomed! your mail will be even more welcomed!
## Contact and more information ## 4. Contact and more information
Everything except configuration files are licensed under BSD-3 license. Please Everything except configuration files are licensed under BSD-3 license. Please
check licence file. check license file.
Please check [https://www.geoffray-levasseur.org/init](https://www.geoffray-levasseur.org/init) Please check [https://www.geoffray-levasseur.org/init](https://www.geoffray-levasseur.org/init)

65
doc/dev.md
View File

@@ -1,76 +1,77 @@
# init.sh developper's reference # init.sh developer's reference
## 1. Getting started ## 1. Getting started
This is a developper's reference. It's not intended to be a manual, but a This is a developer's reference. It's not intended to be a manual, but a
reference for all internal functions, so you can easily build your own modules. reference for all internal functions, so you can easily build your own modules.
This suppose you already read the [Readme file](../README.md). Creating modules This supposes you already read the [README file](../README.md). Creating modules
will also requires some good knowledge of Bash programming. will also require some good knowledge of Bash programming.
## 2. The aaa_error.sh file ## 2. The aaa_error.sh file
### 2.1. Functions ### 2.1. Functions
#### 2.1.1. check_root #### 2.1.1. check_root
Check if user is root. If user is not root, script execution is interupted and Check if user is root. If the user is not root, script execution is interrupted
exit with error. and exit with error.
This function have no parameter. This function has no parameter.
If the variable NO_ROOT_CHECK is set to true the function always exit without If the variable NO_ROOT_CHECK is set to true, the function always exit without
error and no check is done. error and no check is done.
#### 2.1.2. die [--force] \<exitcode\> #### 2.1.2. die [--force] \<exitcode\>
Trigger an error, print a back trace and exit the script, unless KEEPGOING Trigger an error, print a back trace and exit the script, unless KEEPGOING
variable is set to true. In that situation we just display a warning. variable is set to true. In that situation, we just display a warning.
If the parameter *--force* is given, we exit even if the KEEPGOING variable is If the parameter *--force* is given, we exit even if the KEEPGOING variable is
set to true. set to true.
#### 2.1.3. noerror [--noout] \<command\> #### 2.1.3. noerror [--noout] \<command\>
Allow the execution of a command bypassing the error management system. The Allow the execution of a command bypassing the error management system. The
purpose is to allow execution of test returning normally a non zero value purpose is to allow execution of tests returning normally a non-zero value
without triggering an error and the exit comming with. without triggering an error and the exit coming with.
If the first parameter is *--noout* any outputs on standard and error console If the first parameter is *--noout* any outputs on standard and error console
are disabled. The other parameters is the raw command line to execute. are disabled. The other parameters are the raw command line to execute.
In any case the function echoes the error code returned by the executed command. In any case, the function echoes the error code returned by the executed
command.
### 2.2. Other functionnalities ### 2.2. Other functionalities
The simple integration of aaa_error.sh file into a script, will change the The simple integration of aaa_error.sh file into a script, will change the
entire script behaviour regarding errors. The following Bash signals will be entire script behavior regarding errors. The following Bash signals will be
trapped: trapped:
- **ERR**: The ERR signal is triggered every time Bash encounter an error or if - **ERR**: The ERR signal is triggered every time Bash encounters an error or
a command return a non zero value. The function called on that signal will stop if a command return a non-zero value. The function called on that signal will
execution of the script displaying an error message with error code and a stop execution of the script, displaying an error message with error code and a
backtrace to help identify the error origin. Because of this behaviour, the back trace to help identify the error origin. Because of this behavior, the
function superseed the internal "**errexit**" Bash configuration switch, unless function supersedes the internal "**errexit**" Bash configuration switch, unless
the *noerror* function is used. the *noerror* function is used.
- **SIGINT**: That signal is trigerred when Ctrl + C is pressed by the user. - **SIGINT**: That signal is triggered when Ctrl + C is pressed by the user.
That signal will be interpreted only if the command being executed when the That signal will be interpreted only if the command being executed when the
event occurs is a Bash internal. If an executable program receive the signal it event occurs is a Bash internal. If an executable program receive the signal it
will be interpreted with its own mechanisms, generally resulting in an execution will be interpreted with its own mechanisms, generally resulting in an execution
error that will trigger an **ERR** signal as described above. The script will error that will trigger an **ERR** signal as described above. The script will
exit after cleanup when that signal is trapped. exit after cleanup when that signal is trapped.
- **SIGTERM**: That signal is typically the result of an external kill of the - **SIGTERM**: That signal is typically the result of an external kill of the
bash process running the script. The kill signal can comes from the kernel or bash process running the script. The kill signal can come from the kernel or
through the use of a *kill* command. The script will exit after cleanup. through the use of a *kill* command. The script will exit after cleanup.
## 3. The display.sh file ## 3. The display.sh file
### 3.1. Functions ### 3.1. Functions
#### 3.1.1. prnt [I|W|E|m] \<message\> #### 3.1.1. prnt [I|W|E|m] \<message\>
Print a message with timestamp and header. The header depends on first parameter Print a message with timestamp and header. The header depends on first parameter
will be collored and have a fixed length so the messages will always be alligned. will be colored and have a fixed length, so the messages will always be aligned.
The first parameter is the header type, having those possible values: The first parameter is the header type, having those possible values:
- **I**: Display an informative message in green - **I**: Display an informative message in green
- **W**: Display a warning in yellow - **W**: Display a warning in yellow
- **E**: Display an error in red - **E**: Display an error in red
- **m**: Display a message without header but alligned - **m**: Display a message without header but aligned
- Anything else will be treated as the message and will loose alignment. - Anything else will be treated as the message and will lose alignment.
Second parameter is the message to display. The second parameter is the message to display.
### 3.2. Other functionnalities ### 3.2. Other functionalities
Using that script will declare many easy to remember variables containing Bash Using that script will declare some easy to remember variables containing Bash
color codes: color codes:
- Standard codes depending on your environment: DEFAULTFG, - Standard codes depending on your environment: DEFAULTFG,
@@ -86,7 +87,7 @@ color codes :
- High intensity backgrounds: On_IBlack, On_IRed, On_IGreen, On_IYellow, - High intensity backgrounds: On_IBlack, On_IRed, On_IGreen, On_IYellow,
On_IBlue, On_IPurple, On_ICyan, On_IWhite On_IBlue, On_IPurple, On_ICyan, On_IWhite
For exemple if you what to wite "ATTENTION: this is a warning!" in red with For example, if you what to write "ATTENTION: this is a warning!" in red with
"ATTENTION:" on yellow background, you should write: "ATTENTION:" on yellow background, you should write:
```shell ```shell
echo -e "${IRed}${On_IYellow}ATTENTION:${DEFAULTBG} this is a warning!${DEFAULTCOL}" echo -e "${IRed}${On_IYellow}ATTENTION:${DEFAULTBG} this is a warning!${DEFAULTCOL}"
@@ -98,14 +99,14 @@ echo -e "${IRed}${On_IYellow}ATTENTION:${DEFAULTBG} this is a warning!${DEFAULTC
Display date and time based on RFC 3339 standard but slightly modified so it can Display date and time based on RFC 3339 standard but slightly modified so it can
be used in filename. be used in filename.
That fonction takes no parameters and return its result on standard output. That function takes no parameters and return its result on standard output.
#### 4.1.2. backupdist \<list_of_files_or_dirs\> #### 4.1.2. backupdist \<list_of_files_or_dirs\>
That fuckyion will provide a backup of any given files or directories given in That function will provide a backup of any given files or directories given in
command line. The backup will be named name.dist-timestamp, where name is the command line. The backup will be named name.dist-timestamp, where name is the
original file or directory name and timestamp the date and time of the backup original file or directory name and timestamp the date and time of the backup
as retuned by the ***stdtime*** function. If a file given in parameter don't as retuned by the ***stdtime*** function. If a file given in parameter don't
exists the function will issue a warning and continue to the next. exists, the function will issue a warning and continue to the next.
The function don't take any other parameters than file and/or directory names. The function don't take any other parameters than file and/or directory names.