diff --git a/README.md b/README.md index a7a0dea..1054cf0 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,17 @@ using Debian GNU/Linux, Devuan and different flavors of Ubuntu. ## Table of content - [init.sh](#initsh) - - [1. Getting started](#1-getting-started) - - [2. Design](#2-design) - - [2.1. Command line](#21-command-line) - - [2.2. Loading order and process](#22-loading-order-and-process) - - [2.3. Configuration files](#23-configuration-files) - - [2.3.1. Main configuration file](#231-main-configuration-file) - - [2.3.2. Automatically loaded configuration files](#232-automatically-loaded-configuration-files) - - [2.4. Naming conventions](#24-naming-conventions) - - [2.5. Basic module structure](#25-basic-module-structure) - - [3. Error code table](#3-error-code-table) - - [4. Contact and more information](#4-contact-and-more-information) +- [1. Getting started](#1-getting-started) +- [2. Why init.sh?](#2-why-initsh) +- [3. Design](#3-design) + - [3.1. Command line](#31-command-line) + - [3.2. Loading order and process](#32-loading-order-and-process) + - [3.4. Naming conventions](#34-naming-conventions) + - [3.5. Basic module structure](#35-basic-module-structure) +- [4. Error code table](#4-error-code-table) +- [5. Contact and more information](#5-contact-and-more-information) + - [5.1. How to contribute?](#51-how-to-contribute) + - [5.2. Website and maintainor](#52-website-and-maintainor) ## 1. Getting started You should consider reading that document entirely before use. If you need @@ -26,7 +26,23 @@ to create additional modules to meet your needs, consider reading the Please also consider that your needs might meet the needs of someone else, thus it would be a good idea to submit your module to init.sh source base. -## 2. Design +## 2. Why init.sh? +Short answer: why not? + +Long answer: Even if I vallue tools like Puppet or Ansible, I always thought +that such great and complex systems are very nice for big infrastructures. But, +on a much smaller scale, or if you need something fast to deploy and adapt to +your needs, such big tools are somehow overkill. + +I wanted something simple and as universal as possible to manage many different +unique servers in my small local foundations. I started with a lot of long +hardcoded monolitic scripts where I had to rewritte many things on every new +infrastructures I wanted to manage. As it was a fastidious job, I started to +rewritte and redesign everything with a common architecture and code, modular +and easily adaptative. As I don't know any tools in that market scale, I decided +to publish. + +## 3. Design **init.sh** relies on three different elements to work: - the ```init.sh``` script, which provide a simple framework and libraries to do @@ -40,7 +56,7 @@ Additionally, some module might be run regularly, so it could be integrated in a cron-like service using the provided cron mode with the benefits of ```init.sh``` structure and libraries. -### 2.1. Command line +### 3.1. Command line The **init.sh** script allows some command line parameters and some environment variables to change its behavior. @@ -87,7 +103,7 @@ list and their version. The options cannot be concatenated like most of Unix binaries allows. For example you cannot write ```-rR```, you have to write ```-r -R```. -### 2.2. Loading order and process +### 3.2. Loading order and process The first thing the script do is loading its libraries contained in the "*lib*" directory. Any file situated in that directory ending with the .sh extension @@ -121,8 +137,8 @@ Without the ```--keep-going``` option, any error will immediately stop execution Some errors that could make the script impossible to execute will stop execution, even if the ```--keep-going``` option is provided. -### 2.3. Configuration files -#### 2.3.1. Main configuration file +### 3.3. Configuration files +#### 3.3.1. Main configuration file The main configuration file can be two different files. Either it's completely generic and will be named **init.conf.sh** in the ```conf``` directory, either @@ -146,7 +162,7 @@ so you can declare something on your organization configuration file and supersede it in your host configuration file. The only limit will be Bash capabilities in terms of variable manipulation. -#### 2.3.2. Automatically loaded configuration files +#### 3.3.2. Automatically loaded configuration files Those file are basically the system dependent part that assure compatibility with different Linux distributions. Some of those files are shipped with init.sh but you can add what you want to improve possibilities or to add support @@ -172,7 +188,7 @@ The configuration files are loaded if exists in the following order: 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. -### 2.4. Naming conventions +### 3.4. Naming conventions Because of internal mechanics, the dash character is forbidden in module names. Thus, Bash language also forbid that character in variable name. @@ -191,7 +207,7 @@ Any submitted module to the central repository will have module name in lower case with underscore to separate words and ease reading, and variable name upper case with the same underscore as word separator. -### 2.5. Basic module structure +### 3.5. Basic module structure Please note that modules are not supposed to contain any specific code for a platform or a distribution, even if nothing block you doing so. It is highly @@ -263,7 +279,7 @@ be executed in cron mode. Check [cron documentation](./doc/cron.md) for more details. -## 3. Error code table +## 4. Error code table The following table is giving a list of error code with explanation: @@ -298,8 +314,22 @@ you in the debugging process. If you find a bug outside modules or in the basic provided module, please contact the author. Of course, if you also have a patch, your mail will be even more welcomed! -## 4. Contact and more information +## 5. Contact and more information +### 5.1. How to contribute? +If you want to contribute, the best is to use git and push your changes in a +branch you made for that purpose. If you want to submit a patch, you can send it +by mail to the maintainor of init.sh. + +You can improve anything you want, but keep in mind init.sh have to stay small +and simple. If your idea cannot be written using Bash scripting, maybe that +means you're going to far in the improvement. + +Code written in Python or Perl might be accepted as long as it's not mobilizing +a lot of dependencies (forget big framework). Core script will remain in Bash +whatever the evolutions of init.sh will be. + +### 5.2. Website and maintainor Everything except configuration files are licensed under BSD-3 license. Please check license file. diff --git a/doc/dev.md b/doc/dev.md index 4832616..c51a304 100644 --- a/doc/dev.md +++ b/doc/dev.md @@ -354,8 +354,8 @@ 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 | -|:-------------------|:--------|:---------------|:-------------|:--------------| +| Pre/post functions | Caller | Required var | Package triger | 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. |