From a2b0ac7564e204dfa6a45ff9c0e7ca22d140fd0b Mon Sep 17 00:00:00 2001 From: "Christos.K" <freedomrfox@gmail.com> Date: Tue, 4 Jul 2017 02:56:23 +0300 Subject: Included overview docs --- docs/documentations/overview_config.d.5 | 58 +++++++++++++++++++++++++++++++ docs/documentations/overview_controller.5 | 51 +++++++++++++++++++++++++++ docs/documentations/overview_gse.5 | 36 +++++++++++++++++++ docs/documentations/overview_scripts.5 | 54 ++++++++++++++++++++++++++++ 4 files changed, 199 insertions(+) create mode 100644 docs/documentations/overview_config.d.5 create mode 100644 docs/documentations/overview_controller.5 create mode 100644 docs/documentations/overview_gse.5 create mode 100644 docs/documentations/overview_scripts.5 diff --git a/docs/documentations/overview_config.d.5 b/docs/documentations/overview_config.d.5 new file mode 100644 index 0000000..a849051 --- /dev/null +++ b/docs/documentations/overview_config.d.5 @@ -0,0 +1,58 @@ +.TH "GSE CONFIG.D OVERVIEW" "5" + +.PP +The config.d directory hosts all the configuration files that are used to build a system. +While the building process depends on those files, they are not considered core files (except three), meaning that +GSE is not requiring those to function. If they miss, GSE will simply skip the part that depends on those. +.fi +.PP +However, while those configuration files are not runtime dependencies for GSE, they are the incarnation +of GSE, since from those, it provides the means to configure and build the system the way someone wishes and +control the hosts that run upon that. Therefore, someone can argue, that these files are the most important aspect of +GSE, since from those, derive all the functions that someone would find interesting and install GSE in the +first place. +.fi + +.PP +.nf +The config.d directory lies under /usr/lib64/gse and hosts two main sub-directories. + I) System + II) Controller +.fi +.PP +The system sub-directory hosts all the configuration files that are used during the system built and configuration. +Configuration files like hostname, make.conf, portage profile, package.use, system links, fstab entries are common +files under this sub-directory. + +It was noted above that three files under the config.d directory are considered core files. Those files lie under this +sub-directory and are: +.fi +.PP +.nf + I) Fstab entries + II) Driver interface + III) Catalyst +.fi + +.PP +The fstab and driver interface files are considered core items, since from those GSE will read what kind of interface +it should expect to see or create on the new hosts. For example, boot/system/userdata file system type/size and mount options. + +The third and last entry (Catalyst) is important if catalyst is used as the foundation of the new system. The catalyst directory +hosts the spec files, catalyst.conf and catalystrc files, which will inform catalyst about the built and options it should apply. +.fi + +.PP +The second main sub-directory is called controller. The controller sub-directory hosts all the configuration files that are used +from the initramfs functions on the hosts, during the boot-up. Those files are fetched from the hosts on boot-up and are considered +as a way of server-client communication. +.fi +.PP +Each time a host boots-up, it will search for network connection and if it can establish one, then it will proceed with fetching this +directory from the server. From those file, the host will be informed about new changes, e.g. fstab changes, hostname changes, server +IP changes, ssh pub key changes, gpg public key changes,... +.fi +.PP +Since those files provide a way of control from the server to clients, GSE provides an option for masking a specific file or directory. +A mask informs the controller that no change should happen to that file, whatever the new fetched version instructs. +.fi \ No newline at end of file diff --git a/docs/documentations/overview_controller.5 b/docs/documentations/overview_controller.5 new file mode 100644 index 0000000..f4810c1 --- /dev/null +++ b/docs/documentations/overview_controller.5 @@ -0,0 +1,51 @@ +.TH "CONTROLLER OVERVIEW" "5" + +.PP +Note: The following entries are part of man 5 gse. For more information about GSE, please refer there. +.fi +.SH "CONTROLLER" +.nf +\fBThe controller\fR consists from a set of scripts, functions and files that lie inside the initramfs. +The concept of it, derives from the need to controll and make changes to multiple systems that host the +images created from the builder. By names definition, the controller is responsible making dicisions +before the system begins booting, that is, before the initramfs handles the control to the main system. + +.TP +\fBController's functions\fR +-Fetch configuration data from the server +-Check local version with the server's version +-Check the health integrity of SYSFS and BACKUPFS +-Apply new configuration files to the SYSFS +-Update runlevels +-Create new drive interfaces +-Create filesystems +-Create and modify LABELS +-Switch BOOTFS +-Mount /etc and other directories as tmpfs +-Decide which partition will be named SYSFS +-Create,delete and modify subvolumes +-Even wipe the whole setup and start new +.fi +.PP +.nf +The above features can be acceced and modifed, while not recommended from the controller modules. +The modules are located at "$GSE/config.d/controller/modules" and are orginized by categories. +.fi +.PP +.nf +The controller is built inside the initramfs at the end of the chroot part. While that makes the +reproduction of the controller a slower process, the reason to include be included at that part, +is to shield off rebuilding the host's kernel. This feature will be transfered outside the chroot +phase in the future, making it independent from the rest of the process. Meaning that Part H. and +Part I. would be moved out of Stage B. +.fi +.SH "GSE PROFILE" +.nf +The GSE profile, is an experimental profile which aims to enable early functions, features and flags +for the purpose of assisting computer labs on Research facilities and University labs. +The projects idea was born to aid such needs, and the profile is a way reflecting those. + +The profile enables global support for programming languages and global support for math functions. +This profile will be split in other parts in the future, to support embedded systems, by enabling +fewer flags and emerging as much as possible fewer packages. But for now it is simply tested. +.fi \ No newline at end of file diff --git a/docs/documentations/overview_gse.5 b/docs/documentations/overview_gse.5 new file mode 100644 index 0000000..4abd45b --- /dev/null +++ b/docs/documentations/overview_gse.5 @@ -0,0 +1,36 @@ +.TH "GSE OVERVIEW" "5" + +.PP +.nf +There are 5 important directories regarding GSE. +.PP + I) The config.d directory under /usr/lib64/gse + II) The scripts directory under /usr/lib64/gse + III) The gse directory under /etc + IV) The dist.d directory, default under /var/tmp/gse + V) The local directory under /var/tmp/gse +.fi + +.PP +The config.d directory holds all configuration files that describe the items and features to be added or enabled on the system to be built. +.fi +.PP +The scripts directory actually is GSE. This directory holds all the functions that are either initiated directly from /bin/gse or sourced +during the process. It is not recommended to modify those files, since gse provides many configuration files targeted for the system and additionally +it provides a custom script mechanism, with which someone could source whatever he wishes, without modifying any core scripts. +.fi +.PP +GSE configuration files. Those files instruct GSE where to look for important items that regard mostly the Part: A Fundamentals, for example: +the GSE pub key, stage3 tarball, portage snapshot. +.fi +.PP +The dist.d directory is where GSE will do all the work after the catalyst part, which is a separate process. Under dist.d GSE keeps all the workdirs, +and Downloaded items (stage3 tarball, portage snapshot, md5sum files,...). +.fi +.PP +The local directory holds all the gse log files, states and extra files important for controlling the building sequence. +.fi +.PP +.nf +Note: For more technical details of GSE functions and features, please check man 1 gse. +.fi \ No newline at end of file diff --git a/docs/documentations/overview_scripts.5 b/docs/documentations/overview_scripts.5 new file mode 100644 index 0000000..0a65e11 --- /dev/null +++ b/docs/documentations/overview_scripts.5 @@ -0,0 +1,54 @@ +.TH "GSE CORE SCRIPTS OVERVIEW" "5" + +.PP +.nf +The core script's that consist GSE are: + I) gse under /bin + II) sinit under /usr/lib64/gse/scripts + III) sinit_functions under /usr/lib64/gse/scripts/functions + IV) catalyst_functions under /usr/lib64/gse/scripts/functions + V) drv_interface under /usr/lib64/gse/scripts/functions + VI) init_stage3_seq under /usr/lib64/gse/scripts/functions + VII) makeconf_ed under /usr/lib64/gse/scripts/functions + VIII) men_opt under /usr/lib64/gse/scripts/functions + IX) chroot_sinit under /usr/lib64/gse/scripts/chroot_functions + X) cfunctions under /usr/lib64/gse/scripts/chroot_functions +.fi +.PP +The gse script is the first script that runs. From this script the paths, workdirs, configdirs, distdirs are set +and everything that follows is sourced. The most important thing function that this script provides, is a way to call +warp function after ensuring that all the above paths and directories have been set and exported. The warp function is +the main function that initiates the building sequence. It's and autonomous process, meaning that someone could call just +this function if he had set manually the above directories and paths. +.fi +.PP +The sinit script is the main script that controls Stage: A. For more information about stages and parts, see man 5 gse. +.fi +.PP +The sinit_functions is a file with all the functions that sinit requires to complete the process. Actually this file holds +almost all functions of Stage: A and it in fact is sourced even before the warp function is called. +.fi +.PP +The catalyst_functions are the set all of functions that are required by the init_stage3_seq scrip. +.fi +.PP +The drv_interfface is a script which generates the driver interface to be created on all host files. From this script, someone +can set the boot,system,userdata file-systems types and sizes. +.fi +.PP +The init_stage3_seq is a script that is sourced when the catalyst base option is provided. This script will scan for portage snapshot, +create or download a new one if no local snapshot is found or the one provided fails to satisfy certain conditions. Then, it will initiate +the building sequence of stage{1,2,3}. For each stage it will automatically read, filter and export the spec files that are provided for the process. +.fi +.PP +Makeconf_ed is a simple script that is either initiated manually from the main menu or automatically by the warp function. This script will use +a default make.conf files and edit it with MAKEOPTS, EMERGE_DEFAULT_OPTS, SYSTEM ARCH, FEATURES and GENTOO MIRRORS. A completely optional script, that +wont harm the process if it's missing, however it is recommended to keep it and use it, since it provides a fast way of creating a simple make.conf file, +optimized for compilation as described in GCC Optimization wiki page. +.fi +.PP +The chroot_sinit script is the script that controls the Stage: B. This stage actually is a chroot stage, meaning that GSE will chroot to the new +system, configure it, update it and apply all requested packages, profiles and system links. +.fi +.PP The cfunctions is the same as catalyst_functions and sinit_functions. All functions that are required by chroot_sinit lie here. +.fi \ No newline at end of file -- cgit v1.2.3-65-gdbad