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 ## 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 tasks 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 independent way - 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. - multilevel configuration files, being simply Bash variables declaration.
Additionally, some module might be run 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 using the provided cron mode with the benefits of ```init.sh```
structure and libraries.
### 2.1. Command line ### 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 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
override the *MODULE_LIST* variable declaration. The list is a comma separated override the ```MODULE_LIST``` variable declaration. The list is a comma
module name. If that option is provided, the module list is mandatory. 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. - **-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.
@@ -74,16 +75,17 @@ debugging purpose. No action or modification is made to the system unless you
launch commands manually doing some. launch commands manually doing some.
- **--chroot \<path\>**: Allows you to apply init.sh test or modification on a non - **--chroot \<path\>**: Allows you to apply init.sh test or modification on a non
running system, mounted in the given path. 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. for more details.
- **-l, --logfile**: Specify a custom name for the log file. Standard log file - **-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 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 - **-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
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 ### 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. 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 display use of ```--version``` and ```--help``` options in user space. Those options
information and don't require any superuser rights and exit at that point of display information and don't require any superuser rights and exit at that
execution. Everything after that will require administrator rights and the point of execution. Everything after that will require administrator rights and
script will exit with error at that point if not superuser, unless the the script will exit with error at that point if not superuser, unless the
*--no-root-check* option have been given. ```--no-root-check``` option have been given.
Next will be the log file creation and the loading of configuration files. Next will be the log file creation and the loading of configuration files.
Configuration files exists in two distinct categories. First system dependant 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. Finally, checking processes are launched in their declaration order (cf.
configuration file). A module depency check is made prior to the module specific 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 checks unless the ```--no-deps``` option is given or if a manual module list
been transmited. If no error occurs and after a confirmation prompt, final have been transmited. 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 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 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. Configuration files
#### 2.3.1. Main configuration file #### 2.3.1. Main configuration file
The main configuration file can be two different files. 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
will be named after the current hostname of the computer in that same "conf" it will be named after the current hostname of the computer in that same
directory. Please remember that the actual name will be used until the end of ```conf``` directory. Please remember that the actual name will be used until
the execution of init.sh. If one of your module change the hostname, the new the end of the execution of init.sh. If one of your module change the hostname,
name can only be taken into account after a new execution of init.sh. 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 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
@@ -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 for a new distribution. init.sh understand the following possibilities in terms
of OS detection: of OS detection:
| Name | Variable | | | Name | Variable | Description |
|:------------|:---------|:----------------------------------------------------| |:------------|:---------------|:----------------------------------------------|
| **arch** | SYS_ARCH | This is the system architecture, like x86_64, i386, arm64, etc. | | **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*. | | **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). | | **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. | | **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: The configuration files are loaded if exists in the following order:
1. arch.conf.sh 1. arch.conf.sh
2. distro.conf.sh 2. distro.conf.sh
3. distro-arch.conf.sh 3. distro-arch.conf.sh
4. distro-version.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 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 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 ### 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 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 example, @template@ have to be replaced with the name of your In the following example, ```@template@``` have to be replaced with the name of
module with the filename @template@.sh. You can automatically create your new your module with the filename ```@template@.sh```. You can automatically create
module with the following command: your new module with the following command:
```shell ```shell
sed -e "s/@template@/module_name/g" -e "/^# .*/d" -e "s/^##/# /" template > \ 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 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 An optionnal ```cron_@template@``` function allows you to define code that will
executed in cron mode. Check [cron documentation](./doc/cron.md) for more be executed in cron mode. Check [cron documentation](./doc/cron.md) for more
details. details.
@@ -265,30 +267,31 @@ details.
The following table is giving a list of error code with explanation: The following table is giving a list of error code with explanation:
| Code | Meaning | | Code | Meaning |
|:----------|:------------------------------------| |:----------|:---------------------------------------|
| 0 | No error | | 0 | No error |
| 1 | Command line syntax error | | 1 | Command line syntax error |
| 2 | Misuse of Bash built-in | | 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 |
| 6 | Unable to find configuration | | 6 | Unable to find configuration |
| 7 | Misuse of script internal function | | 7 | Misuse of script internal function |
| 8 | Can't determine OS version | | 8 | Can't determine OS type or version |
| 9 | Unsatisfied dependency | | 9 | Unsatisfied dependency |
| 11 | Bad function call | | 10 | File missing or empty |
| 12 | Error copying files | | 11 | Bad function call |
| 13 | Bad target file system | | 12 | Error copying files |
| 14 | Impossible to chroot | | 13 | Bad target file system |
| 15 | Bad target filesystem/installation | | 14 | Impossible to chroot |
| 16 | Invalid options for cron mode | | 15 | Bad chrooted installation, destination OS needs to be fixed |
| 50..100 | Error in module execution | | 16 | Invalid options provided with cron mode activated |
| 126 | Command exists but not executable | | 50..100 | Error in module execution |
| 127 | Command not found | | 126 | Command exists but is not executable |
| 128 | Abortion due to external cause | | 127 | Command not found |
| 150..200 | Error in module checks | | 128 | Abortion due to external cause |
| 255 | Exit status out of range | | 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 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

412
doc/dev.md
View File

@@ -2,56 +2,62 @@
## Table of content ## Table of content
- [init.sh developer's reference](#initsh-developers-reference) - [init.sh developer's reference](#initsh-developers-reference)
- [1. Getting started](#1-getting-started) - [1. Getting started](#1-getting-started)
- [2. The aaa_error.sh file](#2-the-aaa_errorsh-file) - [2. The aaa_error.sh file](#2-the-aaa_errorsh-file)
- [2.1. Functions](#21-functions) - [2.1. Functions](#21-functions)
- [2.1.1. check_root](#211-check_root) - [2.1.1. ```check_root```](#211-check_root)
- [2.1.2. die [--force] \<exitcode\>](#212-die---force-exitcode) - [2.1.2. ```die <exitcode> [--force]```](#212-die-exitcode---force)
- [2.1.3. noerror [--noout] \<command\>](#213-noerror---noout-command) - [2.1.3. ```noerror [--noout] <command>```](#213-noerror---noout-command)
- [2.2. Other functionalities](#22-other-functionalities) - [2.2. Other functionalities](#22-other-functionalities)
- [3. The display.sh file](#3-the-displaysh-file) - [3. The display.sh file](#3-the-displaysh-file)
- [3.1. Functions](#31-functions) - [3.1. Functions](#31-functions)
- [3.1.1. prnt [-n] [I|W|E|m] \<message\>](#311-prnt--n-iwem-message) - [3.1.1. ```prnt [-n] [I|W|E|m] <message>```](#311-prnt--n-iwem-message)
- [3.1.2. dsleep \<miliseconds\> [char]](#312-dsleep-miliseconds-char) - [3.1.2. ```dsleep <miliseconds> [char]```](#312-dsleep-miliseconds-char)
- [3.1.3. dump_key_buffer](#313-dump_key_buffer) - [3.1.3. ```dump_key_buffer```](#313-dump_key_buffer)
- [3.2. Other functionalities](#32-other-functionalities) - [3.2. Other functionalities](#32-other-functionalities)
- [4. The filefct.sh file](#4-the-filefctsh-file) - [4. The filefct.sh file](#4-the-filefctsh-file)
- [4.1. Functions](#41-functions) - [4.1. Common behavior](#41-common-behavior)
- [4.1.1. stdtime](#411-stdtime) - [4.2. Functions](#42-functions)
- [4.1.2. backupdist \<list_of_files_or_dirs\>](#412-backupdist-list_of_files_or_dirs) - [4.2.1. ```backupdist <list_of_files_or_dirs>```](#421-backupdist-list_of_files_or_dirs)
- [4.1.3. installfile \<sources\> \<destination\>](#413-installfile-sources-destination) - [4.2.2. ```installfile <sources> <destination>```](#422-installfile-sources-destination)
- [4.1.4. appendfile \<source\> \<destination\>](#414-appendfile-source-destination) - [4.2.3. ```appendfile <source> <destination>```](#423-appendfile-source-destination)
- [4.1.5. isdirempty \<directory\>](#415-isdirempty-directory) - [4.2.4. ```isdirempty <directory>```](#424-isdirempty-directory)
- [4.2. Other functionnalities](#42-other-functionnalities) - [4.2.5. ```patch_file <source> <destination> [VAR1 [VAR2 ...]]```](#425-patch_file-source-destination-var1-var2-)
- [5. The pkgman.sh file](#5-the-pkgmansh-file) - [4.3. Other functionnalities](#43-other-functionnalities)
- [5.1. Global dependencies](#51-global-dependencies) - [5. The pkgman.sh file](#5-the-pkgmansh-file)
- [5.2. Functions](#52-functions) - [5.1. Global dependencies](#51-global-dependencies)
- [5.2.1. pkgupdt](#521-pkgupdt) - [5.2. Functions](#52-functions)
- [5.2.2. pkginst \<package_list\>](#522-pkginst-package_list) - [5.2.1. ```pkgupdt```](#521-pkgupdt)
- [5.2.3. pkgupgd](#523-pkgupgd) - [5.2.2. ```pkginst <package_list>```](#522-pkginst-package_list)
- [5.2.4. pkgrem \<package_list\>](#524-pkgrem-package_list) - [5.2.3. ```pkgupgd```](#523-pkgupgd)
- [5.2.3. pkgupgd](#523-pkgupgd) - [5.2.4. ```pkgrm <package_list>```](#524-pkgrm-package_list)
- [5.3. Other functionnalities](#53-other-functionnalities) - [5.2.5. ```pkgautorm```](#525-pkgautorm)
- [6. The services.sh files](#6-the-servicessh-files) - [5.3. Other functionnalities](#53-other-functionnalities)
- [6.1. Global dependencies](#61-global-dependencies) - [6. The services.sh file](#6-the-servicessh-file)
- [6.2. Functions](#62-functions) - [6.1. Global dependencies](#61-global-dependencies)
- [6.2.1. exec_serv \<service\> \<command\>](#621-exec_serv-service-command) - [6.2. Functions](#62-functions)
- [6.2.2. svc_start \<service1\> [service2 ... serviceN]](#622-svc_start-service1-service2--servicen) - [6.2.1. ```exec_serv <service> <command>```](#621-exec_serv-service-command)
- [6.2.3. svc_reload \<service1\> [service2 ... serviceN]](#623-svc_reload-service1-service2--servicen) - [6.2.2. ```svc_start <service1> [service2 ... serviceN]```](#622-svc_start-service1-service2--servicen)
- [6.2.2. svc_restart \<service1\> [service2 ... serviceN]](#622-svc_restart-service1-service2--servicen) - [6.2.3. ```svc_reload <service1> [service2 ... serviceN]```](#623-svc_reload-service1-service2--servicen)
- [6.2.3. svc_stop \<service1\> [service2 ... serviceN]](#623-svc_stop-service1-service2--servicen) - [6.2.2. ```svc_restart <service1> [service2 ... serviceN]```](#622-svc_restart-service1-service2--servicen)
- [6.3. Other functionnalities](#63-other-functionnalities) - [6.2.3. ```svc_stop <service1> [service2 ... serviceN]```](#623-svc_stop-service1-service2--servicen)
- [7. The support.sh file](#7-the-supportsh-file) - [7. The support.sh file](#7-the-supportsh-file)
- [7.1. Functions](#71-functions) - [7.1. Global behaviour](#71-global-behaviour)
- [7.1.1. disp_help](#711-disp_help) - [7.2. Functions](#72-functions)
- [7.1.2. show_version](#712-show_version) - [7.2.1. ```disp_help```](#721-disp_help)
- [7.1.3. get_mod_name \<module_file\>](#713-get_mod_name-module_file) - [7.2.2. ```show_version```](#722-show_version)
- [7.1.4. set_system_proxy](#714-set_system_proxy) - [7.3. Other functionnalities](#73-other-functionnalities)
- [8. The version.sh file](#8-the-versionsh-file) - [8. The utils.sh file](#8-the-utilssh-file)
- [8.1. Functions](#81-functions) - [8.1. Functions](#81-functions)
- [8.1.1. get_os_version](#811-get_os_version) - [8.1.1. ```stdtime```](#811-stdtime)
- [8.1.2. set_sys_var \<arch\> \<dist\> \<version\> \<codename\>](#812-set_sys_var-arch-dist-version-codename) - [8.1.2. ```function_exists <function_name>```](#812-function_exists-function_name)
- [8.1.3. ```get_mod_name <module_file>```](#813-get_mod_name-module_file)
- [8.1.4. ```set_system_proxy```](#814-set_system_proxy)
- [8.2. Other functionnalities](#82-other-functionnalities)
- [9. The version.sh file](#9-the-versionsh-file)
- [9.1. Functions](#91-functions)
- [9.1.1. ```get_os_version```](#911-get_os_version)
- [9.1.2. ```set_sys_var <arch> <dist> <version> <codename>```](#912-set_sys_var-arch-dist-version-codename)
## 1. Getting started ## 1. Getting started
This is a developer'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.
@@ -59,36 +65,36 @@ This supposes you already read the [README file](../README.md). Creating modules
will also require some good knowledge of Bash programming. will also require some good knowledge of Bash programming.
Writing conventions are the classical ones: Writing conventions are the classical ones:
* \<param\>: writen like this, the parameter is mandatory * ```<param>```: writen like this, the parameter is mandatory
* [param]: that parameter is optionnal * ```[param]```: that parameter is optionnal
* [ab|cd]: optionnal parmeter have to be "ab" or "cd" * ```[ab|cd]```: optionnal parmeter have to be "ab" or "cd"
* [0..15,20]: acceptable values start at 0 and goes up to 15 or be 20. * ```[0..15,20]```: acceptable values start at 0 and goes up to 15 or be 20.
## 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 the user is not root, script execution is interrupted Check if user is root. If the user is not root, script execution is interrupted
and exit with error. and exit with error.
This function has 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
error and no check is done. without error and no check is done.
#### 2.1.2. die \<exitcode\> [--force] #### 2.1.2. ```die <exitcode> [--force]```
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
set to true. is 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 tests 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 coming 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
are disabled. The other parameters are the raw command line to execute. console 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 In any case, the function echoes the error code returned by the executed
command. command.
@@ -97,34 +103,34 @@ command.
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 behavior 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 encounters an error or - **```ERR```**: The ERR signal is triggered every time Bash encounters an
if a command return a non-zero value. The function called on that signal will error or if a command return a non-zero value. The function called on that
stop execution of the script, displaying an error message with error code and a signal will stop execution of the script, displaying an error message with error
back trace to help identify the error origin. Because of this behavior, the code and a back trace to help identify the error origin. Because of this
function supersedes the internal "**errexit**" Bash configuration switch, unless behavior, the function supersedes the internal ```errexit``` Bash configuration
the *noerror* function is used. switch, unless the *noerror* function is used.
- **SIGINT**: That signal is triggered when Ctrl + C is pressed by the user. - **```SIGINT```**: That signal is triggered when ```Ctrl + C``` is pressed by
That signal will be interpreted only if the command being executed when the the user. That signal will be interpreted only if the command being executed
event occurs is a Bash internal. If an executable program receive the signal it when the event occurs is a Bash internal. If an executable program receive the
will be interpreted with its own mechanisms, generally resulting in an execution signal it will be interpreted with its own mechanisms, generally resulting in an
error that will trigger an **ERR** signal as described above. The script will execution error that will trigger an **```ERR```** signal as described above.
exit after cleanup when that signal is trapped. The script will 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
bash process running the script. The kill signal can come from the kernel or the 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 [-n] [I|W|E|m] \<message\> #### 3.1.1. ```prnt [-n] [I|W|E|m] <message>```
Print a message with timestamp and header. The header depends on a single Print a message with timestamp and header. The header depends on a single
character parameter, will be colored and have a fixed length, so the messages character parameter, will be colored and have a fixed length, so the messages
will always be aligned. will always be aligned.
If the first parameter is *-n*, we won't go to a new line after displaying the If the first parameter is ```-n```, we won't go to a new line after displaying
message. the message.
The first parameter (if *-n* is not provided) is the header type, having those The first parameter (if ```-n``` is not provided) is the header type, having
possible values: 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
@@ -139,7 +145,7 @@ Consequently that function can only contain code that cannot trigger errors or
fail as it's also used to display errors. Thus it only contains echoes and some fail as it's also used to display errors. Thus it only contains echoes and some
variables manipulation. variables manipulation.
#### 3.1.2. dsleep \<miliseconds\> [char] #### 3.1.2. ```dsleep <miliseconds> [char]```
That function is an equivalent to *sleep* bash command but will display a That function is an equivalent to *sleep* bash command but will display a
countdown every second until it reaches zero. Optionnally a character (or a countdown every second until it reaches zero. Optionnally a character (or a
string) can be given as a second parameter to replace the countdown by that string) can be given as a second parameter to replace the countdown by that
@@ -148,7 +154,7 @@ the wait is over.
The function returns nothing useful. The function returns nothing useful.
#### 3.1.3. dump_key_buffer #### 3.1.3. ```dump_key_buffer```
That function dumps keyboard's buffer. It's used to clear eventual key press That function dumps keyboard's buffer. It's used to clear eventual key press
before any critical keyboard action. before any critical keyboard action.
@@ -159,7 +165,7 @@ 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,
DEFAULTBG, DEFAULTCOL=*${DEFAULTBG}${DEFAULTFG}* DEFAULTBG, ```DEFAULTCOL=${DEFAULTBG}${DEFAULTFG}```
- Regular colors: Black, Red, Green, Yellow, Blue, Purple, Cyan, White - Regular colors: Black, Red, Green, Yellow, Blue, Purple, Cyan, White
- Bold (only available in graphical console or some non standard console - Bold (only available in graphical console or some non standard console
fonts): BBlack, BRed, BGreen, BYellow, BBlue, BPurple, BCyan, BWhite fonts): BBlack, BRed, BGreen, BYellow, BBlue, BPurple, BCyan, BWhite
@@ -184,13 +190,22 @@ variable. If not, any new line might be filled with the last used color and line
ending will filled with background color. ending will filled with background color.
## 4. The filefct.sh file ## 4. The filefct.sh file
### 4.1. Functions ### 4.1. Common behavior
In our terminology a source file can be of three different origins, selected
automatically from highest to lowest priority:
- **```repo/hosts/$HOSTNAME```**: this allows to provide system specific
files. Use only relative path to access it.
- **```repo/common```**: this one will provide files suitable for your entire
infrastructure. Yet again provide a relative path to access it.
- **Any path**: You can give fully qualified path names to access resources
from other locations.
#### 4.1.1. backupdist \<list_of_files_or_dirs\> ### 4.2. Functions
#### 4.2.1. ```backupdist <list_of_files_or_dirs>```
That function 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.
If target file or directory is a symbolic link, the link will be resolved until If target file or directory is a symbolic link, the link will be resolved until
@@ -198,24 +213,24 @@ we backup the target on its side.
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.
#### 4.1.2. installfile \<sources\> \<destination\> #### 4.2.2. ```select_file <filename>```
Install a list of file to the given destination. The source of the file can be Returns the best match in our priority system returning on ```stdout``` the
of three different orrigins, from highest to lowest priority: resulting fully qualified path name as a result. The priorities applies on file
- **repo/hosts/$HOSTNAME**: this allows to provide system specific configuration existance.
files. Use only relative path to access the file.
- **repo/common**: this one will provide configuration files suitable for your
entire infrastructure. Yet again provide a relative path to access it.
- **Any path**: You can give fully qualified path names to access resources
from other locations.
The priorities applies on file existance. Wildcards are not allowed in file Many functions manipullating files in ```init.sh``` depends on that function.
names, so an error will occurs if you try to use any. It's also not yet possible
to give an entire directory as a source.
The last parameter is always the destination. If the path do not exists, it #### 4.2.2. ```installfile <sources> <destination>```
will be created automatically. Install a list of source files to the given destination using our priority
system.
#### 4.1.3. appendfile \<source\> \<destination\> Wildcards are not allowed in file names, so an error will occurs if you try to
use any. It's also not yet possible to give an entire directory as a source.
The last parameter is always the destination. If the destination path does not
exists, it will be created automatically.
#### 4.2.3. ```appendfile <source> <destination>```
That function add the content of source file to destination file. The source That function add the content of source file to destination file. The source
file can have defferent origins, following the same path priority as the file can have defferent origins, following the same path priority as the
*installfile* function. *installfile* function.
@@ -223,7 +238,7 @@ file can have defferent origins, following the same path priority as the
The destination file must exist and be on the root filesystem. Only two The destination file must exist and be on the root filesystem. Only two
parameters are accepted, the source and destination files. parameters are accepted, the source and destination files.
#### 4.1.4. isdirempty \<directory\> #### 4.2.4. ```isdirempty <directory>```
That function take only one parameter, a path name and return 0 if the given That function take only one parameter, a path name and return 0 if the given
path don't exists or is empty. It will return one if there's at least one file path don't exists or is empty. It will return one if there's at least one file
in the given directory. in the given directory.
@@ -231,7 +246,7 @@ in the given directory.
If the given parametter is a file (or a symlink to a file), it will terminate If the given parametter is a file (or a symlink to a file), it will terminate
with an error. with an error.
#### 4.1.5. patch_file \<source\> \<destination\> [VAR1 [VAR2 ...]] #### 4.2.5. ```patch_file <source> <destination> [VAR1 [VAR2 ...]]```
That function will patch the given file using our priority system, patch it That function will patch the given file using our priority system, patch it
then place the result in the given destination. The patching will be done when then place the result in the given destination. The patching will be done when
any @VAR@ item in the source file will match an environment variable of the any @VAR@ item in the source file will match an environment variable of the
@@ -242,98 +257,135 @@ variables, in the context of the *init.sh* execution.
Source file must exists and not be empty. The function returns nothing Source file must exists and not be empty. The function returns nothing
useful. useful.
### 4.2. Other functionnalities ### 4.3. Other functionnalities
That file don't profide any other things that the previously listed functions. That file don't profide any other things that the previously listed functions.
## 5. The pkgman.sh file ## 5. The pkgman.sh file
### 5.1. Global dependencies ### 5.1. Global dependencies
Because it gives system independent function to the system dependent package Because it gives system independent function to the system dependent package
manager, the entire file depends on *PKG_MAN* variable, defining the package manager, the entire file depends on ```PKG_MAN``` variable, defining the package
manager executable to use. Other variables giving command line parameters to manager executable to use. Other variables giving command line parameters to
use for the different function will also be nedeed and detailed for every use for the different function will also be nedeed and detailed for every
function. All those variable are defined in a system dependant configuration function. All those variable are defined in a system dependant configuration
file automatically called on script startup. file automatically called on script startup.
### 5.2. Functions ### 5.2. Functions
#### 5.2.1. pkgupdt #### 5.2.1. ```pkgupdt```
That function calls the package manager to update package database. That function calls the package manager to update package database.
It depends on the *COM_UPDATE* variable wich define the parameters to use to It depends on the ```COM_UPDATE``` variable wich define the parameters to use to
accomplish that function. accomplish that function.
That function takes no parameters and any given parameters will be ignored. That function takes no parameters and any given parameters will be ignored.
#### 5.2.2. pkginst \<package_list\> #### 5.2.2. ```pkginst <package_list>```
That function installs using the package manager the packages given in That function installs using the package manager the packages given in
parameters. The list of parameters are all considered as package names. parameters. The list of parameters are all considered as package names.
Before installation the list of package to be installed by the package Before installation, the list of package to be installed by the package
manager will be extracted to allow execution of pre installation scripts manager will be extracted to allow execution of pre installation scripts
and post installation scripts after, even for dependencies. and post installation scripts, even for dependencies (ie: packages not parts of
the given parameters).
Preinstallation scripts have to be named *preinst_\<package_name\>*. Post Preinstallation scripts have to be named ```preinst_<package_name>```. Post
installation script will be in the form *postinst_\<package_name\>*. installation script will be in the form ```postinst_<package_name>```.
If the *INSTALL_MODE* variable is set to "dev" the package manger will be If the ```INSTALL_MODE``` variable is set to ```dev``` the package manger will
called surrounded by eventual pre and post install scripts, one package be called surrounded by eventual pre and post install scripts, one package
after the other. Elsewhere, it will be called once with the entire package after the other. Elsewhere, all pre installation scripts are executed, followed
list as parameter. by the package manager with the entire package list as parameter and finally
all the post installation scripts.
The function depends on the *COM_INSTALL* variable wich define the parameter The function depends on the ```COM_INSTALL``` variable wich define the parameter
to use to accomplish that function. to use to accomplish that package manager function.
#### 5.2.3. pkgupgd #### 5.2.3. ```pkgupgd```
That function calls the package manager to upgrade system. That function calls the package manager to upgrade system. If pre upgrade
scripts exists, they will be executed if the corresponding package are being
upgraded. After the upgrade, the same behaviour will trigger post upgrade
scripts.
It depends on the *COM_UPGRADE* variable wich define the parameters to use to Pre upgrade scripts have to be named ```preupgd_<package_name>```. Post
accomplish that function. upgrade script will be in the form ```postupgd_<package_name>```.
It depends on the ```COM_UPGRADE``` variable wich define the parameters to use
to accomplish that function.
That function takes no parameters and any given parameters will be ignored. That function takes no parameters and any given parameters will be ignored.
#### 5.2.4. pkgrm \<package_list\> #### 5.2.4. ```pkgrm <package_list>```
That function uninstalls using the package manager the packages given in That function uninstalls using the package manager the packages given in
parameters. The list of parameters are all considered as package names. parameters. The list of parameters are all considered as package names.
If the *INSTALL_MODE* variable is set to "dev" the package manger will be Before removal, the list of package to be uninstalled by the package
called one package after the other. Elsewhere, it will be called once with manager will be extracted to allow execution of pre removal scripts
the entire package list as parameter. and post removal scripts, even for dependencies (ie: packages not parts of
the given parameters).
The function depends on the *COM_REMOVE* variable wich define the parameter If the ```INSTALL_MODE``` variable is set to ```dev``` the package manger will
be called one package after the other (allong with pre and post remove scripts).
Elsewhere all pre removal scripts are executed, followed by the package manager
with the entire package list as parameter and finally all the post removal
scripts.
Pre remove scripts have to be named ```prerm_<package_name>```. Post remove
script will be in the form ```postrm_<package_name>```.
The function depends on the ```COM_REMOVE``` variable wich define the parameter
to use to accomplish that function. to use to accomplish that function.
#### 5.2.3. pkgupgd #### 5.2.5. ```pkgautorm```
That function calls the package manager to remove no longer needed installed That function calls the package manager to remove no longer needed installed
dependencies. Any package not manually installed is considered as a depndency. dependencies. Any package not manually installed is considered as a depndency.
It depends on the *COM_AUTOREM* variable wich define the parameters to use to Pre removal and post removal scripts will be executed accordingly if any
accomplish that functionenfin. matching package is to be removed. It's the same as the ones executed by
```pkgrm``` function.
It depends on the ```COM_AUTOREM``` variable wich define the parameters to use
to accomplish that function.
That function takes no parameters and any given parameters will be ignored. That function takes no parameters and any given parameters will be ignored.
### 5.3. Other functionnalities ### 5.3. Other functionnalities
That file don't profide any other things that the previously listed functions. Other functions are declared to call pre and post actions for the corresponding
package manager events. It doesn't make sense those functions to be called
outside of the integrated package manager mechanisms as their functionnalities
depends on variables managed by their respective package manager functions.
The following table resume those function sorted with their respective caller:
| Pre/post functions | Caller | Package triger | Required var | Description |
|:-------------------|:--------|:---------------|:-------------|:--------------|
| ```exec_preinst``` | ```pkginst``` | ```GET_INTALLLIST``` | ```preinst_@pkgname@``` | ```GET_INTALLLIST``` variable defines the command that allows us to obtain the list of package that will be installed with ```@pkg@``` as a substitute to the list given as ```pkginst``` parameters. |
| ```exec_postinst``` | ```pkginst``` | ```POSTINSTLIST``` | ```postinst_@pkgname@``` | ```POSTINSTLIST``` is generated by ```exec_preinst``` and destroyed after ```exec_postinst``` execution. |
| ```exec_preupgd``` | ```pkgupgd``` | ```GET_UPGRADELIST``` | ```preupgd_@pkgname@``` | ```GET_UPGRADELIST``` variable defines the command that allows us to obtain the list of package that will be installed. |
| ```exec_postupgd``` | ```pkgupgd``` | ```POSTUPGRADELIST``` | ```postupgd_@pkgname@``` | ```POSTUPGDLIST``` is generated by ```exec_preupgd``` and destroyed after ```exec_postupgd``` execution. |
| ```exec_prerm``` | ```pkgrm``` | ```GET_REMOVELIST``` | ```prerm_@pkgname@``` | ```GET_REMOVELIST``` variable defines the command that allows us to obtain the list of package that will be removed. ```@pkg@``` will be substituted by the list given as ```pkgrm``` parameters. |
| ```exec_postrm``` | ```pkgrm``` | ```POSTRMLIST``` | ```postrm_@pkgname@``` | ```POSTRMLIST``` is generated by ```exec_prerm``` and destroyed after ```exec_postrm``` execution. |
| ```exec_preautorm``` | ```pkgautorm``` | ```GET_AUTORMLIST``` | ```prerm_@pkgname@``` | ```GET_AUTORMLIST``` variable defines the command that allows us to obtain the list of package that will be automatically removed. |
| ```exec_postautorm``` | ```pkgautorm``` | ```POSTRMLIST``` | ```postrm_@pkgname@``` | ```POSTRMLIST``` is generated by ```exec_preautorm``` and destroyed after ```exec_postautorm``` execution. |
## 6. The services.sh file ## 6. The services.sh file
### 6.1. Global dependencies ### 6.1. Global dependencies
That script relies on the *INIT_COM* variable, defining the program to use to That script relies on the ```INIT_COM``` variable, defining the program to use
manipulate services. It is defined in configuration file automatically called to manipulate services. It is defined in configuration file automatically called
depending on your distribution. Nevertheless, even if it's system dependent, depending on your distribution. Nevertheless, even if it's system dependent,
some distributions offers you to choose between different services call (and some distributions offers you to choose between different services call (and
init system). If you're not using the standard init system of your distribution, init system). If you're not using the standard init system of your distribution,
you'll need to overload the *INIT_COM* variable in your configuration files. you'll need to overload the ```INIT_COM``` variable in your configuration files.
It have been tested with SystemV, SystemD and UpStart init systems. Thus, It have been tested with SystemV, SystemD and UpStart init systems. Thus,
the originally UpStart "service" program tend to be available on many systems the originally UpStart "service" program tend to be available on many systems
and is privileged. and is privileged.
With the tested init systems, and considering %srv% the service name and %com% With the tested init systems, and considering ```%srv%``` the service name and
the command to execute, the *INIT_COM* variable can be: ```%com%``` the command to execute, the ```INIT_COM``` variable can be:
* **"$RC_SCRIPTS_PATH/%srv% %com%"** with *$RC_SCRIPTS_PATH* being "/etc/init.d" on Debian like systems when using SystemV init * **```$RC_SCRIPTS_PATH/%srv% %com%```** with ```$RC_SCRIPTS_PATH``` being ```/etc/init.d``` on Debian like systems when using SystemV init. The variable can be overloaded to change the access path.
* **"systemctl %com% %srv%"** for systems using SystemD * **```systemctl %com% %srv%```** for systems using SystemD
* **"service %srv% %com%"** for upstart like scripts (but widely available) * **```service %srv% %com%```** for upstart like scripts (but widely available)
### 6.2. Functions ### 6.2. Functions
#### 6.2.1. exec_serv \<service\> \<command\> #### 6.2.1. ```exec_serv <service> <command>```
That function execute the given action to the given service. The service have That function execute the given action to the given service. The service have
to be the first parameter and the action, the second parameter. No more to be the first parameter and the action, the second parameter. No more
parameter will be acceted and an error will be triggered if there's any more parameter will be acceted and an error will be triggered if there's any more
@@ -341,75 +393,87 @@ than two.
The function returns the exit code of the service command. The function returns the exit code of the service command.
#### 6.2.2. svc_start \<service1\> [service2 ... serviceN] #### 6.2.2. ```svc_start <service1> [service2 ... serviceN]```
Start the services given in parmeters. You can give as many services you want. Start the services given in parmeters. You can give as many services you want.
That function relies on the previously documented exec_serv function. That function relies on the previously documented exec_serv function.
#### 6.2.3. svc_reload \<service1\> [service2 ... serviceN] #### 6.2.3. ```svc_reload <service1> [service2 ... serviceN]```
Reload the configuration of the services given in parmeters. You can give as Reload the configuration of the services given in parmeters. You can give as
many services you want. Be careful using this as some services don't have that many services you want. Be careful using this as some services don't have that
capability. capability.
That function relies on the previously documented exec_serv function. That function relies on the previously documented exec_serv function.
#### 6.2.2. svc_restart \<service1\> [service2 ... serviceN] #### 6.2.2. ```svc_restart <service1> [service2 ... serviceN]```
Restart the services given in parmeters. It consist generally in a stop Restart the services given in parmeters. It consist generally in a stop
immediately followed by a start. You can give as many services you want. immediately followed by a start. You can give as many services you want.
That function relies on the previously documented exec_serv function. That function relies on the previously documented exec_serv function.
#### 6.2.3. svc_stop \<service1\> [service2 ... serviceN] #### 6.2.3. ```svc_stop <service1> [service2 ... serviceN]```
Stop the services given in parmeters. You can give as many services you want. Stop the services given in parmeters. You can give as many services you want.
That function relies on the previously documented exec_serv function. That function relies on the previously documented exec_serv function.
## 7. The support.sh file ## 7. The support.sh file
### 7.1. Functions ### 7.1. Global behaviour
#### 7.1.1. disp_help That file is designed to just display information. It only contains code that
don't requires any special writes, and do nothing to the system. The idea is to
have the minimal sets of dependencies. As it's sometimes using colors to display
results, it depends only on color code declaration in the ```display.sh``` file.
### 7.2. Functions
#### 7.2.1. ```disp_help```
That function display the help screen, usually called using the *--help* switch. That function display the help screen, usually called using the *--help* switch.
It's not taking any parameter and return nothing but help text. It's not taking any parameter and return nothing but help text.
#### 7.1.2. show_version #### 7.2.2. ```show_version```
That function display the version of init.sh. It will also parse all the That function display the version of init.sh. It will also parse all the
available modules to display a table with their respecting versions. available modules to display a table with their respecting versions.
If user is not root an additionnal warning will be displayed to warn the fact If user is not root an additionnal warning will be displayed to warn the fact
the script requires root privileges to work properly. the script requires root privileges to work properly.
As it's using colors to display results, it depends on color code declaration in ### 7.3. Other functionnalities
the *display.sh* file. That file don't profide any other thing that the previously listed functions.
#### 7.1.3. get_mod_name \<module_file\>
That function return the name of the module file given in parameter. It takes
only one parameter: the module file name.
Result is sent to *stdout*.
#### 7.1.4. set_system_proxy
That function applies proxy settings in the configuration files to the system
proxy configuration, unless the *--no-proxy* parameters have been given command
line.
That function takes no parameters and only change *http_proxy* and *https_proxy*
standard POSIX variables. No usefull result will be returned.
## 8. The utils.sh file ## 8. The utils.sh file
### 8.1. Functions ### 8.1. Functions
#### 8.1.1. stdtime #### 8.1.1. ```stdtime```
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. Thus spaces are replaced by dash, and comas between hours, be used in filename. Thus spaces are replaced by dash, and comas between hours,
minutes and seconds are removed. minutes and seconds are removed.
That function takes no parameters and return its result on standard output. That function takes no parameters and return its result on standard output.
#### 8.1.2. ```function_exists <function_name>```
That function checks if the given name is a defined function in the execution
environment. It returns 0 if yes and an undefined non zero value if not.
That functions prints nothing.
#### 8.1.3. ```get_mod_name <module_file>```
That function return the name of the module file given in parameter. It takes
only one parameter: the module file name.
Result is sent to ```stdout```.
#### 8.1.4. ```set_system_proxy```
That function applies proxy settings in the configuration files to the system
proxy configuration, unless the ```--no-proxy``` parameters have been given
command line.
That function takes no parameters and only change ```http_proxy``` and
```https_proxy``` standard POSIX variables. No usefull result will be returned.
### 8.2. Other functionnalities ### 8.2. Other functionnalities
That file don't profide any other thing that the previously listed functions. That file don't profide any other thing that the previously listed functions.
## 9. The version.sh file ## 9. The version.sh file
### 9.1. Functions ### 9.1. Functions
#### 9.1.1. get_os_version #### 9.1.1. ```get_os_version```
That function takes no parameters and will return three values in order: That function takes no parameters and will return three values in order:
1. Distribution ID, in lowcase, usually equivalent to the distribution name. 1. Distribution ID, in lowcase, usually equivalent to the distribution name.
2. Distribution version, if available, elsewhere kernel version with it's major. 2. Distribution version, if available, elsewhere kernel version with it's major.
@@ -423,7 +487,7 @@ the [official documentation](https://www.freedesktop.org/software/systemd/man/os
In "*/etc/os-release*" the variables *ID*, *VERSION_ID* and *VERSION_CODENAME* In "*/etc/os-release*" the variables *ID*, *VERSION_ID* and *VERSION_CODENAME*
will be the ones being analysed. Only the *ID* variable is mandatory. will be the ones being analysed. Only the *ID* variable is mandatory.
#### 9.1.2. set_sys_var \<arch\> \<dist\> \<version\> \<codename\> #### 9.1.2. ```set_sys_var <arch> <dist> <version> <codename>```
That function sets important variable that will store the system architecture. That function sets important variable that will store the system architecture.
It will allow the automatic loading of mandatory system dependent code and It will allow the automatic loading of mandatory system dependent code and
variables. For debugging purpose it will be possible to call it manually. variables. For debugging purpose it will be possible to call it manually.
@@ -443,10 +507,10 @@ If your distribution do not provide any codename, you have to give "null" as a
replacement parameter. replacement parameter.
The following global variables will be set at the end of the execution: The following global variables will be set at the end of the execution:
- **SYS_ARCH** for the system architecture - **```SYS_ARCH```** for the system architecture
- **SYS_DIST** for the distribution name - **```SYS_DIST```** for the distribution name
- **SYS_VER** for the distribution version - **```SYS_VER```** for the distribution version
- **SYS_CODE** for the distribution codename - **```SYS_CODE```** for the distribution codename
The *SYS_CODE* variable won't be set if your distribution provides no codename. The ```SYS_CODE``` variable won't be set if your distribution provides no codename.