From f0b7cce9059a1ae8770ce1d54c6ebe30f5d02c1c Mon Sep 17 00:00:00 2001 From: levasseur Date: Wed, 15 Dec 2021 17:33:45 +0100 Subject: [PATCH] added error documentation --- doc/errors.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 doc/errors.md diff --git a/doc/errors.md b/doc/errors.md new file mode 100644 index 0000000..30060e1 --- /dev/null +++ b/doc/errors.md @@ -0,0 +1,202 @@ +# This is **init.sh** error fixing documentation + +This document do not pretend to be exhaustive but will cover all errors that can +be returned by libraries and some basic modules. It will not cover errors +generated by external programs or Bash itself. Please refer to corresponding +documentation in such situation. + +## Error #1: Command line syntax error or incompatible options +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 +message displayed together with that error. + +## Error #2: Misuse of Bash built-in +A Bash builtin function is uncorrectly 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. + +If it happens on the execution of **init.sh** or a builtin module, please send a +bug repport. + +## Error #3: Missing library file or function +One of the internal vital function of **init.sh** is missing. + +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 +**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```. + +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 +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. + +## Error #6: Unable to find configuration +That error happens when no configuration file suitable for your machine have +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.conf.sh``` in that same directory. + +If you gave manual configuration files, check they all exists. + +## 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 +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. + +## 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 +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 +[```/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 +modules depends on another which is not part of the module to execute. The other +case is when you call a module too early. + +To fix this, check your module list order. Check also your modules dependenies +are in the list before they are called themself. + +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 +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 +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 it happens on the execution of **init.sh** or a builtin module, please send a bug +repport. + +## Error 12: Error copying files +A file copy opperation have 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 +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. + +Make sure your destination paths are fully qualified paths names (begining with +"/"), is writable and the destination path exists. + +## Error #14: Impossible to chroot +That error occurs when the chroot target don't exists. + +Check your target filesystem, 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 +**init.sh**. + +## Error #16: Invalid options provided with cron mode activated +When cron mode is on, **init.sh** support a very limited range of options. + +To fix this, don't use the ```--check-only``` or ```--jump``` options when using +cron mode. + +## Error #17: Missing or invalid status file, can't resume +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 #50 to #100: Error in module execution +A module trigered an internal error while executing change 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. + +## 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. + +## Error #127: Command not found +You try to call a command that do not exists. + +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 occurs with a builtin module or in **init.sh** code or libraries please +fill a bug repport. + +## Error #128: Abortion due to external cause +That error happens when an exeternal signal is triggering a stop in 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. + +## Error #150 to #200: Error in module checks +One of the checks executed prior **init.sh** actions did not pass. + +To resolve this, fix the condition of execution of your module as explained in +the associated error message. + +## Error #255: Exit status out of range +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 +documentation. + +----------------------------------------------------------------------------- +Documentation (c) 2019-2021 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