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

documentation updated and reworked

Browse Source
This commit is contained in:
levasseur
2021-10-27 17:01:40 +02:00
parent 029a5b7a0d
commit 9fc9b96165
2 changed files with 301 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
README.md
View File

@@ -29,7 +29,7 @@ it would be a good idea to submit your module to init.sh source base.
## 2. Design
**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 tasks and embed system dependent functions to provide system independent
function calls.
- modules that actually do the job, as possible on a system independent way
@@ -37,7 +37,8 @@ through the use of the framework and consisting of very small and simple tasks.
- multilevel configuration files, being simply Bash variables declaration.
Additionally, some module might be run regularly, so it could be integrated in a
cron-like service.
cron-like service using the provided cron mode with the benefits of ```init.sh```
structure and libraries.
### 2.1. Command line
@@ -51,8 +52,8 @@ 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
identical variable name.
- **-m \<list\>, --module \<list\>**: Allows to manually give a module list and
override the *MODULE_LIST* variable declaration. The list is a comma separated
module name. If that option is provided, the module list is mandatory.
override 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.
@@ -74,16 +75,17 @@ debugging purpose. No action or modification is made to the system unless you
launch commands manually doing some.
- **--chroot \<path\>**: Allows you to apply init.sh test or modification on a non
running system, mounted in the given path.
- **--cron**: execute init.sh in cron mode. Check cron subsystem documentation
- **--cron**: execute init.sh in cron mode. Check [cron subsystem
documentation](./doc/cron.md)
for more details.
- **-l, --logfile**: Specify a custom name for the log file. Standard log file
is named init-hostname-date-time.log in the log subdirectory. That file can also
be customized using the LOGFILE environment variable.
be customized using the ```LOGFILE``` environment variable.
- **-v, --version**: Display version information, including available module
list and their version.
The options cannot be concatenated like most of Unix binaries allows. For
example you cannot write "*-rR*", you have to write "*-r -R*".
example you cannot write ```-rR```, you have to write ```-r -R```.
### 2.2. Loading order and process
@@ -96,11 +98,11 @@ 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 display
information 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, unless the
*--no-root-check* option have been given.
use of ```--version``` and ```--help``` options in user space. Those options
display information 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, unless the
```--no-root-check``` option have been given.
Next will be the log file creation and the loading of configuration files.
Configuration files exists in two distinct categories. First system dependant
@@ -111,23 +113,23 @@ options.
Finally, checking processes are launched in their declaration order (cf.
configuration file). A module depency check is made prior to the module specific
checks unless the *--no-deps* option is given or if a manual module list have
been transmited. If no error occurs and after a confirmation prompt, final
checks unless the ```--no-deps``` option is given or if a manual module list
have been transmited. 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 immediately 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
execution, even if the *--keep-going* option is provided.
execution, even if the ```--keep-going``` option is provided.
### 2.3. Configuration files
#### 2.3.1. Main configuration file
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
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 taken into account after a new execution of init.sh.
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 taken 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
@@ -151,24 +153,24 @@ init.sh but you can add what you want to improve possibilities or to add support
for a new distribution. init.sh understand the following possibilities in terms
of OS detection:
| Name | Variable | |
|:------------|:---------|:----------------------------------------------------|
| **arch** | SYS_ARCH | This is the system architecture, like x86_64, i386, arm64, etc. |
| **dist** | SYS_DIST | The name of the Linux distribution as reported by */etc/os-release*. |
| **version** | SYS_VER | Version of the distribution. If you run a rolling release and no version is provided by your */etc/os-release* file, the main version of the Linux kernel will be used (e.g. 5.4 for any version of 5.4. kernel branch). |
| **codename**| SYS_CODE | If your distribution profide a version codename, it will be set with it. |
| Name | Variable | Description |
|:------------|:---------------|:----------------------------------------------|
| **arch** | ```SYS_ARCH``` | This is the system architecture, like x86_64, i386, arm64, etc. |
| **dist** | ```SYS_DIST``` | The name of the Linux distribution as reported by */etc/os-release*. |
| **version** | ```SYS_VER``` | Version of the distribution. If you run a rolling release and no version is provided by your */etc/os-release* file, the main version of the Linux kernel will be used (e.g. 5.4 for any version of 5.4.x kernel branch). |
| **codename**| ```SYS_CODE``` | If your distribution profide a version codename, it will be set with it. |
The configuration files are loaded if exists in the following order:
1. arch.conf.sh
2. distro.conf.sh
3. distro-arch.conf.sh
4. distro-version.conf.sh
5. distro-codename.conf.sh (if *$SYS_CODE* defined)
5. distro-codename.conf.sh (only if ```$SYS_CODE``` is defined)
6. distro-version-arch.conf.sh
7. distro-codename-arch.conf.sh (if *$SYS_CODE* defined)
7. distro-codename-arch.conf.sh (only if ```$SYS_CODE``` is defined)
The loading of those files, if one exists, cannot be avoided. They all must be
located in the *conf/auto* directory of the init.sh tree.
located in the ```conf/auto``` directory of the init.sh tree.
### 2.4. Naming conventions
@@ -198,9 +200,9 @@ 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 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 following command:
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 following command:
```shell
sed -e "s/@template@/module_name/g" -e "/^# .*/d" -e "s/^##/# /" template > \
@@ -254,10 +256,10 @@ export -f precheck_@template@
```
Unexported template function will work but won't be available in the integrated
debugging shell (see --shell option).
debugging shell (see ```--shell``` option).
An optionnal *cron_@template@* function allows you to define code that will be
executed in cron mode. Check [cron documentation](./doc/cron.md) for more
An optionnal ```cron_@template@``` function allows you to define code that will
be executed in cron mode. Check [cron documentation](./doc/cron.md) for more
details.
@@ -265,30 +267,31 @@ details.
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 built-in |
| 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 |
| 8 | Can't determine OS version |
| 9 | Unsatisfied dependency |
| 11 | Bad function call |
| 12 | Error copying files |
| 13 | Bad target file system |
| 14 | Impossible to chroot |
| 15 | Bad target filesystem/installation |
| 16 | Invalid options for cron mode |
| 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 |
| Code | Meaning |
|:----------|:---------------------------------------|
| 0 | No error |
| 1 | Command line syntax error |
| 2 | Misuse of Bash built-in |
| 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 |
| 8 | Can't determine OS type or version |
| 9 | Unsatisfied dependency |
| 10 | File missing or empty |
| 11 | Bad function call |
| 12 | Error copying files |
| 13 | Bad target file system |
| 14 | Impossible to chroot |
| 15 | Bad chrooted installation, destination OS needs to be fixed |
| 16 | Invalid options provided with cron mode activated |
| 50..100 | Error in module execution |
| 126 | Command exists but is not executable |
| 127 | Command not found |
| 128 | Abortion due to external cause |
| 150..200 | Error in module checks |
| 255 | Exit status out of range |
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