12 KiB
init.sh developer's reference
Table of content
- init.sh developer's reference
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. This supposes you already read the README file. Creating modules will also require some good knowledge of Bash programming.
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.
This function has no parameter.
If the variable NO_ROOT_CHECK is set to true, the function always exit without error and no check is done.
2.1.2. die [--force] <exitcode>
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.
If the parameter --force is given, we exit even if the KEEPGOING variable is set to true.
2.1.3. noerror [--noout] <command>
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 without triggering an error and the exit coming with.
If the first parameter is --noout any outputs on standard and error 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 command.
2.2. Other functionalities
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 trapped:
- ERR: The ERR signal is triggered every time Bash encounters an error or if a command return a non-zero value. The function called on that signal will stop execution of the script, displaying an error message with error code and a back trace to help identify the error origin. Because of this behavior, the function supersedes the internal "errexit" Bash configuration switch, unless the noerror function is used.
- SIGINT: That signal is triggered when Ctrl + C is pressed by the user. That signal will be interpreted only if the command being executed when the event occurs is a Bash internal. If an executable program receive the signal it will be interpreted with its own mechanisms, generally resulting in an execution error that will trigger an ERR signal as described above. The script will exit after cleanup when that signal is trapped.
- SIGTERM: That signal is typically the result of an external kill of 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.
3. The display.sh file
3.1. Functions
3.1.1. prnt [I|W|E|m] <message>
Print a message with timestamp and header. The header depends on first parameter will be colored and have a fixed length, so the messages will always be aligned.
The first parameter is the header type, having those possible values:
- I: Display an informative message in green
- W: Display a warning in yellow
- E: Display an error in red
- m: Display a message without header but aligned
- Anything else will be treated as the message and will lose alignment.
The second parameter is the message to display.
3.2. Other functionalities
Using that script will declare some easy to remember variables containing Bash color codes:
- Standard codes depending on your environment: DEFAULTFG, DEFAULTBG, DEFAULTCOL=${DEFAULTBG}${DEFAULTFG}
- Regular colors: Black, Red, Green, Yellow, Blue, Purple, Cyan, White
- Bold (only available in graphical console or some non standard console fonts): BBlack, BRed, BGreen, BYellow, BBlue, BPurple, BCyan, BWhite
- Underline: UBlack, URed, UGreen, UYellow, UBlue, UPurple, UCyan, UWhite
- Background: On_Black, On_Red, On_Green, On_Yellow, On_Blue, On_Purple, On_Cyan, On_White
- High intensity: IBlack, IRed, IGreen, IYellow, IBlue, IPurple, ICyan, IWhite
- Bold high intensity (only available in graphical console or some non standard console fonts): BIBlack, BIRed, BIGreen, BIYellow, BIBlue, BIPurple, BICyan, BIWhite
- High intensity backgrounds: On_IBlack, On_IRed, On_IGreen, On_IYellow, On_IBlue, On_IPurple, On_ICyan, On_IWhite
For example, if you what to write "ATTENTION: this is a warning!" in red with "ATTENTION:" on yellow background, you should write:
echo -e "${IRed}${On_IYellow}ATTENTION:${DEFAULTBG} this is a warning!${DEFAULTCOL}"
4. The filefct.sh file
4.1. Functions
4.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.
That function takes no parameters and return its result on standard output.
4.1.2. backupdist <list_of_files_or_dirs>
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 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.
The function don't take any other parameters than file and/or directory names.
4.1.3. installfile <sources> <destination>
Install a list of file to the given destination. The source of the file can be of three different orrigins, from highest to lowest priority:
- repo/hosts/$HOSTNAME: this allows to provide system specific configuration 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 apply on file existance. 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 path do not exists, it will be created automatically.
4.2. Other functionnalities
That file don't profide any other things that the previously listed functions.
5. The pkgman.sh file
5.1. Global dependencies
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.
5.2. Functions
5.2.1. pkgupdt
That function calls the package manager to update package database.
It depends on the COM_UPDATE variable wich define the parameters to use to accomplish that function.
That function takes no parameters and any given parameters will be ignored.
5.2.2. pkginst <package_list>
That function installs using the package manager the packages given in 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 called one package after the other. Elsewhere, it will be called once with the entire package list as parameter.
The function depends on the COM_INSTALL variable wich define the parameter to use to accomplish that function.
5.2.3. pkgupgd
That function calls the package manager to upgrade system.
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.
5.2.4. pkgrem <package_list>
That function uninstalls using the package manager the packages given in 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 called one package after the other. Elsewhere, it will be called once with the entire package list as parameter.
The function depends on the COM_REMOVE variable wich define the parameter to use to accomplish that function.
5.2.3. pkgupgd
That function calls the package manager to remove no longer needed installed 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 accomplish that function.
That function takes no parameters and any given parameters will be ignored.
5.3. Other functionnalities
That file don't profide any other things that the previously listed functions.
6. The services.sh files
6.1. Global dependencies
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 init system). Tested init systems are SystemV init, SystemD and UpStart. Thus, the originally UpStart "service" program tend to be available on many systems and is privileged.
6.2. Functions
6.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 than two.
The function returns the exit code of the service command.
6.2.2. svc_start [service2 ... serviceN]
Start the services given in parmeters. You can give as many services you want.
That function relies on the previously documented exec_serv function.
6.2.3. svc_reload [service2 ... serviceN]
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 capability.
That function relies on the previously documented exec_serv function.
6.2.2. svc_restart [service2 ... serviceN]
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.
That function relies on the previously documented exec_serv function.
6.2.3. svc_stop [service2 ... serviceN]
Stop the services given in parmeters. You can give as many services you want.
That function relies on the previously documented exec_serv function.
6.3. Other functionnalities
That file don't profide any other thing that the previously listed functions.