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

bump to version 0.99.18

Browse Source
This commit is contained in:
fatalerrors
2022-06-24 17:52:17 +02:00
parent e8c6f46572
commit da37fd3bae
52 changed files with 1268 additions and 435 deletions
Download Patch File Download Diff File Expand all files Collapse all files

386
doc/dev.md
View File

@@ -87,7 +87,9 @@
- [13.1.1. ```get_os_version```](#1311-get_os_version)
- [13.1.2. ```set_sys_var <arch> <dist> <version> <codename>```](#1312-set_sys_var-arch-dist-version-codename)
- [13.2. Other functionnalities](#132-other-functionnalities)
- [14. Writing conventions](#14-writing-conventions)
- [14. Global variables](#14-global-variables)
- [15. Writing conventions](#15-writing-conventions)
## 1. Getting started
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.
@@ -95,16 +97,19 @@ This supposes you already read the [README file](../README.md). Creating modules
will also require some good knowledge of Bash programming.
Writing conventions are the classical ones:
* ```<param>```: writen like this, the parameter is mandatory
* ```[param]```: that parameter is optionnal
* ```[ab|cd]```: optionnal parmeter have to be "ab" or "cd"
* ```<param>```: written like this, the parameter is mandatory
* ```[param]```: that parameter is optional
* ```[ab|cd]```: optional parameter have to be "ab" or "cd"
* ```[0..15,20]```: acceptable values start at 0 and goes up to 15 or be 20.
Boolean values have to be set as ```true``` or ```false``` for test to succeed.
Any unset boolean is always interpreted as ```false```.
## 2. The aaa_error.sh file
### 2.1. Functions
#### 2.1.1. ```check_root```
Check if user is root. If the user is not root, script execution is interrupted
and exit with error.
Check if user is root. If the user is not root, script execution interrupts and
exit with error.
This function has no parameter.
@@ -154,30 +159,30 @@ through the use of a *kill* command. The script will exit after cleanup.
#### 3.1.1. ```chroot_bootstrap```
That function is called if a chroot option have been given. It's in charge of
performing the chroot, copying a full working directory structure of init.sh
tree. After that copy, a chroot command is runned launching that new copy of
tree. After that copy, a chroot command is run, launching that new copy of
init.sh.
If the child init.sh end with error, the stage file is gathered in parent
directory tree to allow launching again the chrooted init.sh with the resume
option.
At the end the function will clean up removing the second copy of init.sh.
At the end, the function will clean up, removing the second copy of init.sh.
### 3.2. Other functionnalities
So far, only one function is provided in this file.
## 4. The diskman.sh file
### 4.1. Global warning
The goal of that unit is to provide disk manipulation function, like
partitionning, blanking or formative. All those functions are potentially very
### 4.1. Warning about that unit
The goal of that unit is to provide disks manipulation function, like
partitioning, blanking or format. All those functions are potentially very
destructive. Please use with extra care and do not hesitate to highly protect
your code when using those. By defaults the functions try to be as conservative
as they can, triguering errors on the smallest doubt.
your code when using those. By defaults, the functions try to be as conservative
as they can, triggering errors on the smallest doubt.
### 4.2. Function
#### 4.2.1. ```blank_disk <bloc_device> [--full]```
Blank a block device using two different method to be sure it's all clear. First
we use the *wipefs* method specialized in reseting all possible flags on the
we use the *wipefs* method, specialized in resetting all possible flags on the
drive and it's partitions. It will also blank the partition table. A second pass
will fill the first 512 MB with zeroes to also blank MBR and other parts of the
drive wipefs would have ignored.
@@ -186,61 +191,61 @@ If the parameter ```--full``` is provided as second parameter, the entire disk
will be filled with zeroes. Please consider that such operation might take a
very long time (can be several hours).
That function only take parameter which must be a bloc device.
That function only take parameter which must be a block device.
#### 4.2.2. ```is_blank <bloc_device>```
That function will try to detect if a drive is blank of not. It will return 0 if
That function will try to detect if a drive is blank or not. It will return 0 if
the drive is blank, and return 1 otherwise. If the function return 2, either the
provided parameter is not a block device or that block device do not exists.
provided parameter is not a block device or that block device do not exist.
Please consider that special drive configuration could be detected as blank
while it's not. Only one parameter will be accepted, a bloc device.
while it's not. Only one parameter will be accepted, a block device.
The function will give different information depending on the bloc device you
The function will give different information depending on the block device you
test:
- on a whole disk drive it while return 0 if the drive is blank, meaning no MBR
and no partition table (either GTP or DOS);
- on a partition it will tell if it's formated or not. Beware that an erased
then recreated partion will continue to have old partition data available and
will be shown as non blank.
- On a whole disk drive, it while return 0 if the drive is blank, meaning no
MBR and no partition table (either GTP or DOS);
- On a partition, it will tell if that partition is formatted or not. Beware
that an erased then recreated partition will continue to have old data
available and will be shown as non-blank.
#### 4.2.3. ```mkparts <disk> [dos|gpt] [size_part1 [... size_partN]]```
This function create partitions on the disk given as the first parameter. The
second parameter can be gpt or dos, respectively to instruct the creation of a
second parameter can be gpt or dos, respectively, to instruct the creation of a
GPT partition table (which is default when not mentioned) or a DOS partition
table, deprecated but suported for compatibility purposes. Then a list of size
table, deprecated but supported for compatibility purposes. Then a list of size
can be given to generate more than one partition. In the case of a DOS partition
table, only primary partition are possible, four of it maximum.
table, only primary partition are possible, four of, maximum.
Partition size can be :
- simple number: will be interpreted as a precise number of cylinder, this is
- Simple number: will be interpreted as a precise number of cylinders, this is
the only method that will be precise;
- 100M: will create a 100 MiB partition, more or less to the nearest cylinder;
- 100G: will create a 100 GiB partition, more or less to the nearest cylinder;
- 100T: same again 100 TiB, ang you really have a lot of space...
- 100T: same again 100 TiB, and you really have a lot of space...
- 0: will be interpreted as all remaining space in the final partition scheme.
It must come only once.
Be warned that a size (whatever the unit is) can result in slightly different
space depending on the drive model and cylinder size.
### 4.3. Other functionnalities
### 4.3. Other functionalities
That file don't provide any other things that the previously listed functions.
## 5. The command_line.sh file
### 5.1. Functions
#### 5.1.1. ```read_commandline```
That function consist in a loop that analyse command line one parameter after
the other. Most of command line parameters will result in the positionning of
That function consist in a loop that analyze command line one parameter after
the other. Most of command line parameters will result in the positioning of
some global variables. The following table details the variable with their type
associated to the corresponding parameter:
| Parameter | Variable | Type | Descrition |
| Parameter | Variable | Type | Description |
|:--------------|:-------------------|:--------|:------------------------------|
| --help | *none* | *n/a* | Trigger help display directly and exit |
| --version | *none* | *n/a* | Trigger version display directly and exit |
| --module | MANUAL_MODULE_LIST | string | The following parameter will set a list of module to use |
| --check-only | CHECK_ONLY | boolean | Activate check only mode |
| --jump | JUMP | boolean | Activate no checks mode |
| --jump | JUMP | boolean | Activate no check mode |
| --keep-going | KEEPGOING | boolean | Activate keep going option |
| --resume | RESUME | boolean | Activate resume mode if stage file exists |
| --no-root-check | NO_ROOT_CHECK | boolean | Activate option to not check if user is root |
@@ -251,22 +256,23 @@ associated to the corresponding parameter:
| --chroot | CHROOT_PATH | string | The following parameter will be the path to chroot in |
| --cron | CRON_MODE | boolean | Activate cron mode |
The function will do some basinc synthax checks. For exemple if you put an
option just after one supposing a value declaration, an error will be trigered
The function will do some basic syntax checks. For example, if you put an option
just after one supposing a value declaration, an error will be triggered
directly.
#### 5.1.5. ```process_commandline_and_vars```
That function have the role to check the concistancy of command line parameters.
It will triger errors if incompatible parameters have been given or if those
parameters might lead to a non predictable situation.
That function has the role to check the concistency of command line parameters.
It will trigger errors if incompatible parameters have been given or if those
parameters might lead to a non-predictable situation.
When those checks are done, the definitive module list to load is created. With
that list we then checks the modules are available and do not contain the dash
character.
That function will also triger an error if the definitive module list is empty.
That function will also trigger an error if the resulting module list appears to
be empty.
### 5.2. Other functionnalities
### 5.2. Other functionalities
That file don't provide any other things that the previously listed functions.
## 6. The display.sh file
@@ -291,28 +297,29 @@ The second parameter is the message to display.
As this function is widely used almost everywhere in the code at runtime,
consider it as being a base dependency of all libraries and modules.
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
variables manipulation.
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 variables manipulation.
#### 6.1.2. ```separator```
That function display a seprator made with dash, to fill the length of the
screen minus one character if screen length is 80 character or less. If more
than 80 the lenght of the separator will be 80 plus half of additionnal length.
That function display a separator made with dash, filling the screen length minus
one character if screen length is 80 character or less. If the screen length is
above 80 characters, the length of the separator will be 80 plus half of
additional length.
It takes no parameters and return no value.
#### 6.1.3. ```dsleep <miliseconds> [char]```
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. Optionally, a character (or a
string) can be given as a second parameter to replace the countdown by that
character. For exemple, you can use a dot to display a dot every second until
character. For example, you can use a dot to display a dot every second until
the wait is over.
The function returns nothing useful.
#### 6.1.4. ```dump_key_buffer```
That function dumps keyboard's buffer. It's used to clear eventual key press
That function dumps the keyboard's buffer. It's used to clear eventual key press
before any critical keyboard action.
That function takes no parameter and returns no useful value.
@@ -348,12 +355,12 @@ ending will be filled with background color.
## 7. The filefct.sh file
### 7.1. Common behavior
In our terminology a source file can be of three different origins, selected
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.
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.
@@ -365,42 +372,43 @@ 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
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
recursively until we backup the final target on its side.
If the target file or directory is a symbolic link, the link will be resolved
recursively until we backup in the backup destination.
The function don't take any other parameters than file and/or directory names.
#### 7.2.2. ```select_file <filename>```
Returns the best match in our priority system returning on ```stdout``` the
resulting fully qualified path name as a result. The priorities applies on file
existance.
Returns the best match in our priority system, returning on ```stdout``` the
resulting fully qualified path name as a result. The priorities apply on file
existence.
Many functions manipullating files in ```init.sh``` depends on that function.
Many functions manipulating files in ```init.sh``` depends on that function.
#### 7.2.2. ```install_file <source1> [source2 [... sourceN]] <destination>```
Install a list of source files to the given destination using our priority
system.
Wildcards are not allowed in file names, so an error will occurs if you try to
Wildcards are not allowed in file names, so an error will occur 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.
exists, it will be created automatically. The destination must be a fully
qualified file name (and consequently, begin with "/").
#### 7.2.3. ```append_file <source> <destination>```
That function add the content of source file to destination file. The source
file can have different origins, following the same path priority as the
*install_file* function.
The destination file must exist and be on the root filesystem. Only two
The destination file must exist and be on the root file system. Only two
parameters are accepted, the source and destination files.
#### 7.2.4. ```is_dir_empty <directory>```
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 doesn't exist or is empty. It will return one if there's at least one file
in the given directory.
If the given parametter is a file (or a symlink to a file), it will terminate
If the given parameter is a file (or a symlink to a file), it will terminate
with an error.
#### 7.2.5. ```patch_file <source> <destination> [VAR1 [VAR2 [... VARN]]]```
@@ -411,48 +419,56 @@ exact same name without the trailing @. Variables will be either the
given list or, if nothing is given in parameter, in the global system
variables, in the context of the *init.sh* execution.
Source file must exists and not be empty. The function returns nothing
The source file must exist and not be empty. The function returns nothing
useful.
#### 7.2.6. ```tag_file <file1> [file2 [... fileN]]```
That function add a tag to the first line of the given files. If one file
allready exists, the added line will be in the form:
already exists, the added line will be in the form:
``` # File automatically modified by init.sh on $(stdtime).```
If it don't exists it is created with the line:
If it doesn't exist, it is created with the line:
```# File automatically generated by init.sh on $(stdtime).```
It's not using the file selection system as our source file are not suposed to
```stdtime``` is the timestamps function in the ```utils.sh``` library file.
It's not using the file selection system, as our source file are not supposed to
be modified directly. In consequence, you should always provide fully qualified
path names to it.
#### 7.2.7. ```file_exists <file1> [file2 [... fileN]]```
That function check files existance within our file selection system. If one
That function check files existence within our file selection system. If one
source file is missing it will return 1 and echo the first file name that have
not been found in the list. If all the given files exists, it returns 0.
not been found in the list. If all the given files exists, it returns 0 and
echoes nothing.
#### 7.2.8. ```file_must_exists <file1> [file2 [... fileN]]```
That function check files existance within our file selection system. If one
source file is missing it will return an error and stop execution. That function
is logicaly massively used during check phase to verify all source files are in
That function check files existence within our file selection system. If one
source file is missing, it will return an error and stop execution. That function
is logically massively used during check phase to verify all source files are in
place.
#### 7.2.9. ```directory_exists <directory1> [directory2 [... directoryN]]```
That function check directories existance within our file selection system. If
one source directory is missing it will return 1 and echo the first directory
That function check directories' existence within our file selection system. If
one source directory is missing, it will return 1 and echo the first directory
name that have not been found in the list. If all the given directories exists,
it returns 0.
#### 7.2.10. ```directory_must_exists <directory1> [directory2 [... directoryN]]```
That function check directories existance within our file selection system. If
one source directory is missing it will return an error and stop execution. That
function is logicaly massively used during check phase to verify all source
directories are in place.
That function check directories' existence within our file selection system. If
one source directory is missing, it will return an error and stop execution.
That function is useful during check phase to verify all source directories are
in place.
### 7.3. Other functionnalities
That file don't provide any other things that the previously listed functions.
### 7.3. Other functionalities
That library initialize a couple of variables possibly useful in modules:
* ```HOST_REPO_PATH```: path where source files specific to the host will be
stored. Default is ```repo/hosts/$HOSTNAME``` under the ```init.sh``` script
directory;
* ```COMM_REPO_PATH```: path where common source files will be stored. Default
is ```repo/common``` under the ```init.sh``` script directory.
## 8. The loaders.sh file
### 8.1. Functions
@@ -467,20 +483,20 @@ exist in the following order:
6) ```auto/distro-version-arch.conf.sh```
7) ```auto/distro-codename-arch.conf.sh``` (if ```SYS_CODE``` defined)
Plaese note that a situation where no such file exists would lead to error. Most
of the time a basic package manager configuration will be required to make it
Please note that a situation where no such file exists would lead to error. Most
of the time, a basic package manager configuration will be required to make it
work.
#### 8.1.4. ```load_configuration```
That function loads configuration files. It will first check for configuration
given as command line parameter. If no such parameter exists, it will try to
load a file named ```conf/${HOSTNAME}.conf.sh```. If that file don't exists, the
load a file named ```conf/${HOSTNAME}.conf.sh```. If that file don't exist, the
generic configuration will be loaded in the file ```conf/init.conf.sh```.
If no configuration file can be found the function will trigger an error and
If no configuration file can be found, the function will trigger an error and
exit the script.
### 8.2. Other functionnalities
### 8.2. Other functionalities
That file don't provide any other things that the previously listed functions.
## 9. The pkgman.sh file
@@ -488,96 +504,97 @@ That file don't provide any other things that the previously listed functions.
Because it gives system independent function to the system dependent package
manager, the entire file depends on ```PKG_MAN``` variable, defining the package
manager executable to use. Other variables giving command line parameters to
use for the different function will also be nedeed and detailed for every
function. All those variable are defined in a system dependant configuration
file automatically called on script startup.
use for the different function will also be needed and detailed for every
function. All those variable have to be defined in a system dependent
configuration file automatically called on script startup.
### 9.2. Functions
#### 9.2.1. ```pkgupdt```
That function calls the package manager to update package database.
That function calls the package manager to update the package database.
It depends on the ```COM_UPDATE``` variable wich define the parameters to use to
accomplish that function.
It depends on the ```COM_UPDATE``` variable which define the parameters to use
to accomplish that function.
That function takes no parameters and any given parameters will be ignored.
#### 9.2.2. ```pkginst <package1> [package2 [... packageN]]```
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 will be entirely considered as package names.
Before installation, the list of package to be installed by the package
manager will be extracted to allow execution of pre installation scripts
and post installation scripts, even for dependencies (ie: packages not parts of
the given parameters).
manager will be extracted to allow execution of pre-installation scripts
and post-installation scripts, even for dependencies (i.e.: packages not parts
of the given parameters).
Preinstallation scripts have to be named ```preinst_<package_name>```. Post
installation script will be in the form ```postinst_<package_name>```.
Pre-installation scripts have to be named ```preinst_<package_name>```.
Post-installation script will be in the form ```postinst_<package_name>```.
If the ```INSTALL_MODE``` variable is set to ```dev``` the package manger will
If the ```INSTALL_MODE``` variable is set to ```dev``` the package manager will
be called surrounded by eventual pre and post install scripts, one package
after the other. Elsewhere, all pre installation scripts are executed, followed
after the other. Elsewhere, all pre-installation scripts are executed, followed
by the package manager with the entire package list as parameter and finally
all the post installation scripts.
all the post-installation scripts.
The function depends on the ```COM_INSTALL``` variable wich define the parameter
to use to accomplish that package manager function.
The function depends on the ```COM_INSTALL``` variable which define the
parameter to use to accomplish that package manager function.
#### 9.2.3. ```pkgupgd```
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
That function calls the package manager to upgrade the system. If pre-upgrade
scripts exist, they will be executed if the corresponding package are being
upgraded. After the upgrade, the same behavior will trigger post-upgrade
scripts.
Pre upgrade scripts have to be named ```preupgd_<package_name>```. Post
upgrade script will be in the form ```postupgd_<package_name>```.
Pre-upgrade scripts have to be named ```preupgd_<package_name>```. Post-upgrade
scripts will be in the form ```postupgd_<package_name>```.
It depends on the ```COM_UPGRADE``` variable wich define the parameters to use
It depends on the ```COM_UPGRADE``` variable which define the parameters to use
to accomplish that function.
That function takes no parameters and any given parameters will be ignored.
#### 9.2.4. ```pkgrm <package1> [package2 [... packageN]]```
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 will be entirely considered as package names.
Before removal, the list of package to be uninstalled by the package
manager will be extracted to allow execution of pre removal scripts
and post removal scripts, even for dependencies (ie: packages not parts of
manager will be extracted to allow execution of pre-removal scripts
and post-removal scripts, even for dependencies (i.e.: packages not parts of
the given parameters).
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
If the ```INSTALL_MODE``` variable is set to ```dev``` the package manager will
be called one package after the other (along 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
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
The function depends on the ```COM_REMOVE``` variable which define the parameter
to use to accomplish that function.
#### 9.2.5. ```pkgautorm```
That function calls the package manager to remove no longer needed installed
dependencies. Any package not manually installed is considered as a depndency.
That function calls the package manager to remove no longer needed dependencies
still installed. Any package not manually installed is considered as a
dependency.
Pre removal and post removal scripts will be executed accordingly if any
matching package is to be removed. It's the same as the ones executed by
Pre-removal and post-removal scripts will be executed accordingly if any
matching package is to be removed. It will be the same as the ones executed by
```pkgrm``` function.
It depends on the ```COM_AUTOREM``` variable wich define the parameters to use
It depends on the ```COM_AUTOREM``` variable which define the parameters to use
to accomplish that function.
That function takes no parameters and any given parameters will be ignored.
### 9.3. Other functionnalities
Other functions are declared to call pre and post actions for the corresponding
### 9.3. Other functionalities
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
outside the integrated package manager mechanisms as their functionalities
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 | Required var | Package triger | Description |
| Pre/post-functions | Caller | Required var | Package trigger | 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. |
@@ -593,7 +610,7 @@ The following table resume those function sorted with their respective caller:
That script relies on the ```INIT_COM``` variable, defining the program to use
to manipulate services. It is defined in configuration file automatically called
depending on your distribution. Nevertheless, even if it's system dependent,
some distributions offers you to choose between different services call (and
some distributions offer you to choose between different services call (and
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.
@@ -611,31 +628,31 @@ With the tested init systems, and considering ```%srv%``` the service name and
#### 10.2.1. ```exec_serv <service> <command>```
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
parameter will be acceted and an error will be triggered if there's any more
parameter will be accepted and an error will be triggered if there's any more
than two.
The function returns the exit code of the service command.
#### 10.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 parameters. You can give as many services you want.
That function relies on the previously documented exec_serv function.
#### 10.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 parameters. You can give as
many services you want. Be careful using this as some services don't have that
capability.
That function relies on the previously documented exec_serv function.
#### 10.2.2. ```svc_restart <service1> [service2 [... serviceN]]```
Restart the services given in parmeters. It consist generally in a stop
Restart the services given in parameters. It consists generally in a stop
immediately followed by a start. You can give as many services you want.
That function relies on the previously documented exec_serv function.
#### 10.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 parameters. You can give as many services you want.
That function relies on the previously documented exec_serv function.
@@ -643,9 +660,9 @@ That function relies on the previously documented exec_serv function.
That file don't provide any other thing that the previously listed functions.
## 11. The support.sh file
### 11.1. Global behaviour
### 11.1. Global behavior
That file is designed to just display information. It only contains code that
don't requires any special rights, and do nothing to the system. The idea is to
doesn't require any special rights, 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.
@@ -657,111 +674,135 @@ It's not taking any parameter and return nothing but help text.
#### 11.2.2. ```show_version```
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 respective versions.
If user is not root an additionnal warning will be displayed to warn the fact
the script requires root privileges to work properly.
If the user is not root, an additional warning will be displayed to warn the
fact the script requires root privileges to work properly.
### 11.3. Other functionnalities
### 11.3. Other functionalities
That file don't provide any other thing that the previously listed functions.
## 12. The utils.sh file
### 12.1. Functions
#### 12.1.1. ```stdtime```
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,
minutes and seconds are removed.
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, minutes and seconds are just removed.
That function takes no parameters and return its result on standard output.
#### 12.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.
environment. It returns 0 if yes and 1 value if not. The function name is
mandatory and an error will be triggered if no function name is given.
That functions prints nothing.
#### 12.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.
only one parameter: a module file name.
Result is sent to ```stdout```.
Result will be sent to ```stdout```.
#### 12.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.
command line or if proxy settings are already set.
That function takes no parameters and only change ```http_proxy``` and
```https_proxy``` standard POSIX variables. No usefull result will be returned.
```https_proxy``` standard POSIX variables in the script environment. No useful
result will be returned.
### 12.2. Other functionnalities
### 12.2. Other functionalities
That file don't provide any other thing that the previously listed functions.
## 13. The version.sh file
### 13.1. Functions
#### 13.1.1. ```get_os_version```
That function takes no parameters and will return three values in order:
1. Distribution ID, in lowcase, usually equivalent to the distribution name.
2. Distribution version, if available, elsewhere kernel version with it's major.
3. Distribution codename (eg. buster for Debian 10) in lowercase if available. If not, the generic "null" value is returned instead.
1. Distribution ID, in low case, usually equivalent to the distribution name.
2. Distribution version, if available, elsewhere kernel version (only major and
minor, release will be ignored).
3. Distribution code-name (e.g., buster for Debian 10) in lowercase if
available. If not, the generic "null" value is returned instead.
The function mainly relies on the "*/etc/os-release*" new standard file. If your
distribution do not provide that file it is required you generate it yourself
distribution do not provide that file, it is required you generate it yourself
before using init.sh. If you need help with the *os-release* file you can check
the [official documentation](https://www.freedesktop.org/software/systemd/man/os-release.html).
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 analyzed. Only the *ID* variable is mandatory.
#### 13.1.2. ```set_sys_var <arch> <dist> <version> <codename>```
That function sets important variable that will store the system architecture.
It will allow the automatic loading of mandatory system dependent code and
variables. For debugging purpose it will be possible to call it manually.
That function sets some important variables that will store the system
architecture. It allows the automatic loading of mandatory system dependent code
and variables. For debugging purpose it's be possible to call it manually.
Inside the init.sh initiallisation, it's called that way:
Inside the init.sh initialization, it's called that way:
```shell
set_sys_vars $(uname -m) $(get_os_version)
```
All the four parameters have to be given in that order:
1. System architecture (eg. x86_64, i386, arm64...)
2. Distribution name (eg. debian, centos, ubuntu...)
1. System architecture (e.g., x86_64, i386, arm64...)
2. Distribution name (e.g., debian, centos, ubuntu...)
3. Distribution version (or kernel version for rolling releases)
4. Distribution codename if available (eg. jessie, buster, bulleyes...)
4. Distribution code-name if available (e.g., jessie, buster, bulleyes...)
If your distribution do not provide any codename, you have to give "null" as a
If your distribution do not provide any code-name, you have to give "null" as a
replacement parameter.
The following global variables will be set at the end of the execution:
- **```SYS_ARCH```** for the system architecture
- **```SYS_DIST```** for the distribution name
- **```SYS_VER```** for the distribution version
- **```SYS_CODE```** for the distribution codename
- **```SYS_CODE```** for the distribution code-name
The ```SYS_CODE``` variable won't be set if your distribution provides no
codename.
code-name.
### 13.2. Other functionnalities
That file don't provide any other thing that the previously listed functions.
## 14. Writing conventions
## 14. Global variables
Here is the table of the global variable, that could be usefull either to change
script behavior, or because those variables could be useful in many modules.
| Varaible | Type | Use |
|:-------------|:-------|:-----------------------------------------------|
| HOSTNAME | string, automatic | Define the name of the host |
| MODULE_LIST | comma separated string list, configuration file | The module list to execute |
## 15. Writing conventions
For readability and compatibility purpose, I adopted some writing conventions.
First of all indentation is made with space only, as different editors can have
a very different approach on tabs management. Please configure your editor
accordingly if you want to share your work.
First, indentation is made with space only, as different editors can have a very
different approach on tabs management. I honestly really love the "Emacs" tab
management style, but I must recognize most editor are not behaving correctly
with tabs. Consequently, please configure your editor to replace tabs with four
spaces, if you want to share your work.
If, for and while statement are all written in that way:
```shell
# if exemple
if [[ condition ]]; then
something
elif [[ condition ]]; then
something
else
something
fi
# for exemple
for var in range; do
something
done
# while exemple
while condition; do
something
done
```
Case statement will look like this:
```shell
case var in
@@ -777,12 +818,19 @@ case var in
esac
```
Tests have to be done using if. Writting ```[[ test ]] && action``` is not
encouraged even if elegant. It makes reading harder for beginners.
Tests have to be done using if. Writing ```[[ test ]] && action``` is not
encouraged, even if I personally think it's a very elegant writing. It makes
reading and comprehension harder for beginners.
A much more accepted behavior is the following two rules with tests:
* Don't write ```[[ $VAR ]]``` to test variable existance, write
```[[ -n $VAR ]]``` instead.
* Don't write ```[[ ! $VAR ]]``` to test if a variable is undeclared, write
```[[ -z $VAR ]]``` instead.
-----------------------------------------------------------------------------
Documentation (c) 2019-2021 Geoffray Levasseur.
Documentation (c) 2019-2022 Geoffray Levasseur.
This file is distributed under3-clause BSD license. The complete license
agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause

134
doc/errors.md
View File

@@ -33,17 +33,18 @@ You've called the **init.sh** script with command line syntax error or options
that are not compatible together. Some options exclude each others or trigger
opposite events.
To fix it check your command line taking into account of the detailled error
To fix it check your command line taking into account of the detailed error
message displayed together with that error.
## Error #2: Misuse of Bash built-in
A Bash builtin function is uncorrectly called.
A Bash built-in function is incorrectly called.
If that error happens on the execution of a module you made yourself, you might
check the code of your module and fix what goes wrong.
check the code of your module and fix what goes wrong. The backtrace will help
you to find what line is in cause of it.
If it happens on the execution of **init.sh** or a builtin module, please send a
bug repport.
bug report.
## Error #3: Missing library file or function
One of the internal vital function of **init.sh** is missing.
@@ -52,19 +53,19 @@ Most of the time that error happens when one of the library files of **init.sh**
is missing. Please check your directory tree and all files are available. Use
git as a reference if you have some doubts.
If you have all the files, make sure they are not truncated (it can happens, for
example, if disk is full), that you use consistant versions (yet again, git is
the reference) or you didn't modified something accidentally in libraries or
If you have all the files, make sure they are not truncated (it can happen, for
example, if disk is full), that you use consistent versions (yet again, git is
the reference) or you didn't modify something accidentally in libraries or
**init.sh** script.
## Error #4: No root right
You tried to execute **init.sh** without administrative rights.
As **init.sh** goal is to transform system, administrative rights are absolutely
necessary. To fix this, run **init.sh** as superuser, using ```sudo``` or
```su```.
As **init.sh** goal is to transform the system, administrative rights are
absolutely necessary. To fix this, run **init.sh** as superuser, using
```sudo``` or ```su```.
If you run as non UID #0 user but you're certain to have all the necessary
If you run as non UID #0 user, but you're certain to have all the necessary
rights, you have to use the ```--no-check-root``` option.
## Error #5: Malformed module list
@@ -72,9 +73,9 @@ The module list you provided is malformed or contains forbidden characters.
To fix this, check your module list in your configuration file or in your
command line if you passed it manually. If you created a module you added in the
list, make sure your module does not contain a dash '-' character, or any non
alphanumeric character other than underscore. If you use a number in your module
name, make sure it's not begining with.
list, make sure your module does not contain a dash '-' character, or any
non-alphanumeric character other than underscore. If you use a number in your
module name, make sure it's not beginning with.
## Error #6: Unable to find configuration
That error happens when no configuration file suitable for your machine have
@@ -82,84 +83,86 @@ been found.
To fix this, make sure you have a configuration file named after the lowercase
hostname of the computer you run on in the ```conf/``` directory of your
**init.sh** tree. Alternatively you can use a generic file named
**init.sh** tree. Alternatively, you can use a generic file named
```init.conf.sh``` in that same directory.
If you gave manual configuration files, check they all exists.
If you gave manual configuration files, check they all exist.
## Error #7: Misuse of script internal function
One of the base function of **init.sh** libraries is not being used correctly.
If that error happens while executing one of your module, please check your code
especially when you use a **init.sh** internal. The
[developper documentation](dev.md) will help you about synthax. Check your
If that error happens while executing one of your module, please check your
code, especially when you use an **init.sh** internal. The
[developer's documentation](dev.md) will help you about syntax. Check your
parameters are correctly passed in the good format and do not use wildcards in
file names.
If it happens on the execution of **init.sh** or a builtin module, please send a
bug repport.
If it happens on the execution of **init.sh** or a built-in module, please send
a bug report.
## Error #8: Can't determine OS type or version
As **init.sh** relies on some specific operating system commands (like package
manager) the detection system must be able to obtain OS characteristics.
To fix this you must check the ```/etc/os-release``` file availability for your
To fix this, you must check the ```/etc/os-release``` file availability for your
distribution. If your distribution do not provide that file, you'll have to
create it yourself providing on the bare minimum an ``ID`` entry. Check the
create it yourself, providing on the bare minimum an ``ID`` entry. Check the
[```/etc/os-release``` file documentation](https://www.freedesktop.org/software/systemd/man/os-release.html)
for details.
## Error #9: Unsatisfied dependency
That error can happens in two cases scenario. One case is one or more of your
That error can happen in two cases scenario. One case is one or more of your
modules depends on another which is not part of the module to execute. The other
case is when you call a module too early.
case is when you call a module too early in the list.
To fix this, check your module list order. Check also your modules dependenies
are in the list before they are called themself.
To fix this, check your module list order. Check also your module's dependencies
are in the list before they are called themselves.
If you wrote your own module, make sure you have no circular dependencies.
## Error #10: File missing or empty
You have refered a file that don't exists or is empty, if the file is required
You have referred a file that don't exist or is empty, if the file is required
to have a content.
Check your filename and path in modules and/or configuration files.
## Error #11: Bad function call
That error is trigered when an internal function is called with a wrong number
That error is triggered when an internal function is called with a wrong number
of parameters.
If that error happens while executing one of your module, please check your code
especially when you use a **init.sh** internal. The
[developper documentation](dev.md) will help you about synthax.
If that error happens while executing one of your module, please check your
code, especially when you use an **init.sh** internal. The
[developer's documentation](dev.md) will help you about syntax. Check also if a
required variable is properly set. It's always a good idea to test if all needed
variables are set properly in the checks, before applying any changes.
If it happens on the execution of **init.sh** or a builtin module, please send a bug
repport.
If it happens on the execution of **init.sh** or a built-in module, please send
a bug report.
## Error 12: Error copying files
A file copy opperation have failed.
A file copy operation has failed.
Make sure your source path exists and is readable and destination is writable
and target directory exists. Chack also if target do not contain a symbolic link
and target directory exists. Check also if target do not contain a symbolic link
or a directory with the same name.
## Error #13: Bad target file system
The target file system you provided is not part of the root filesystem, is not
accessible or is not an absolute path.
The target file system you provided is not part of the root file system, is not
accessible, or is not an absolute path.
Make sure your destination paths are fully qualified paths names (begining with
Make sure your destination path is a fully qualified paths names (beginning with
"/"), is writable and the destination path exists.
## Error #14: Impossible to chroot
That error occurs when the chroot target don't exists.
That error occurs when the chroot target don't exist.
Check your target filesystem, make sure it's mounted.
Check your target file system, make sure it's mounted.
## Error #15: Bad chrooted installation, destination OS needs to be fixed
The target installation is incomplete or not usable in a chrooted environment.
Check all the filesystems needed to perform the chroot are mounted correctly. If
your target installation is damaged, you have to fix it before running
Check all the file systems needed to perform the chroot are mounted correctly.
If your target installation is damaged, you have to fix it before running
**init.sh**.
## Error #16: Invalid options provided with cron mode activated
@@ -174,44 +177,49 @@ You asked to resume on last error, but no status file can be found.
To fix this, remove the ```--resume``` option. You can use the ```--modules```
option instead to ask for a limited range of modules.
## Error #18: Module file don't exists or is empty
## Error #18: Module file don't exist or is empty
The module list contains an entry that correspond to no module in the "modules"
directory or the corresponding file is actually empty.
directory, or the corresponding file is actually empty.
Check the spelling of the incriminated module. If spelling is correct, check the
file name of that module. If it don't exists, create the module or remove it
from the module list.
file name of that module. If it don't exist, create the module or remove it from
the module list.
## Error #50 to #100: Error in module execution
A module trigered an internal error while executing change to the system. You
A module triggered an internal error while executing changes to the system. You
need to check the concerned module documentation.
As the module may have done some unfinished changes to the system, it will be
safer to resume after fixing the problem before rebooting.
safer to resume after fixing the problem before rebooting. If you need to
reboot, please check your system is still bootable.
## Error #126: Command exists but is not executable
You try to execute a command that is not executable for you.
Check your rights to execute the so said command. Check also the excutable is
valid if the command is external.
Check your rights to execute the so said command. Check also the executable file
is valid if the command is external.
## Error #127: Command not found
You try to call a command that do not exists.
You try to call a command that do not exist.
If taht error comes from one of your modules, check the spelling of the
command. Check also if the program you need is installed and think about
installing it through the provided **init.sh** builtin functions.
If that error comes from one of your modules, check the spelling of the
command. Check also if the program you need is installed, and think about
installing it through the provided **init.sh** built-in functions before using
it in your module.
If that occurs with a builtin module or in **init.sh** code or libraries please
fill a bug repport.
If that occurs with a built-in module or in **init.sh** code or libraries,
please fill a bug report.
## Error #128: Abortion due to external cause
That error happens when an exeternal signal is triggering a stop in the
That error happens when an external signal is triggering the interuption of the
execution of **init.sh**.
Do not halt or restart the computer before the end of **init.sh** execution.
Using Ctrl + C sequence or the kill command on the bash process running the
script will lead to that error too.
Do not halt or restart the computer before the end of **init.sh** execution. If
one of your module requires a reboot, please use the built-in ```need_reboot```
command.
Note that using Ctrl + C sequence or the kill command on the bash process
running the script will lead to that error too.
## Error #150 to #200: Error in module checks
One of the checks executed prior **init.sh** actions did not pass.
@@ -223,12 +231,12 @@ the associated error message.
That error is a special case when the exit status of a program is above 255 as
authorized by many high level programming languages.
Check the error in the program emiting it and the associated program
Check the error in the program emitting it and the associated program
documentation.
-----------------------------------------------------------------------------
Documentation (c) 2019-2021 Geoffray Levasseur.
Documentation (c) 2019-2022 Geoffray Levasseur.
This file is distributed under3-clause BSD license. The complete license
agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause

19
doc/todo.md
View File

@@ -1,11 +1,11 @@
# init.sh to do list
# init.sh to-do list
There's no specific order in that list. All that is subject to appear in version
1.x.y of ```init.sh```.
* Better error management system
* Fix ```--keep-going``` option not properly working
* Add a function for booleans to accept true, yes and 1, and false, no and 0 answers
* Add a function for boolean variables to accept true, yes and 1, and false, no and 0 answers
* More modules
* Add support for CentOS
* Add support for Slackware
@@ -14,25 +14,26 @@ There's no specific order in that list. All that is subject to appear in version
* Improve output
* Add ```--quiet``` option to hide run commands output
Here is ideas for version 2 of ```init.sh```:
Here are ideas for version 2 of ```init.sh```:
* Support for system dependant modules
* Idempotency (if possible)
* Support for system dependent modules
* Idem potency (if possible)
* Better configuration file design with a proper parser (ini style maybe)
* Configuration designer (CCmake style maybe), can't be done in Bash
* Language support and translations?
What will never appear in that todo list (so don't ask) :
* Windows: don't ask for Windows support, it will never happens
* Windows: don't ask for Windows support, it will never happen, and don't make any sense
* MacOS: same as above
* Base language change: the heart of init.sh is BASH, and will always be
Knowing all that, you can still send feature request if a deasired feature do
not appears in that list.
Knowing all that, you can still send feature request if a desired feature do not
appears in that list.
-----------------------------------------------------------------------------
Documentation (c) 2019-2021 Geoffray Levasseur.
Documentation (c) 2019-2022 Geoffray Levasseur.
This file is distributed under3-clause BSD license. The complete license
agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause