diff options
author | Christos.K <freedomrfox@gmail.com> | 2017-06-07 00:48:35 +0300 |
---|---|---|
committer | Christos.K <freedomrfox@gmail.com> | 2017-06-07 00:48:35 +0300 |
commit | f73bb4a74a170520fa5bde174c917c583ecfc56a (patch) | |
tree | a06e07fe5f4a9058bd944601d2843ecbea3a7e24 /docs | |
parent | Fixed some logical errors (diff) | |
download | GSE-f73bb4a74a170520fa5bde174c917c583ecfc56a.tar.gz GSE-f73bb4a74a170520fa5bde174c917c583ecfc56a.tar.bz2 GSE-f73bb4a74a170520fa5bde174c917c583ecfc56a.zip |
Created gse.1 and gse.5 manpage
Diffstat (limited to 'docs')
-rw-r--r-- | docs/documentations/gse.1 | 65 | ||||
-rw-r--r-- | docs/documentations/gse.5 | 224 |
2 files changed, 289 insertions, 0 deletions
diff --git a/docs/documentations/gse.1 b/docs/documentations/gse.1 new file mode 100644 index 0000000..fd85496 --- /dev/null +++ b/docs/documentations/gse.1 @@ -0,0 +1,65 @@ +.TH "GSE" "1" +.SH NAME +GSE \- Gentoo Stateless Environment +.SH SYNOPSIS +.B gse +[\fBOPTIONS\fR] +.SH "DESCRIPTION" +.nf +\fBGSE\fR is a set of scripts and configuration files that takes special advantage of catalyst, +for creating a Gentoo system intented to function under stateless conditions, a modualr kernel +and an initramfs which provide functions to further control and modify such a system. +.fi +.SH OPTIONS +.TP +.nf +\fB\-\-menuXYZ...\fR \fB\-mXYZ...\fR +X stands for the menu entry Y its submenu entry and same follows for the rest. +To bring configurations entry, which lie under 'System Menu' -> 'Configure built variables', +one could simply type gse --m12 instead of gse and then guide himself through the menu entries. +.fi +.TP +\fB\-\-fetch-new\fR \fB\-fn\fR +.nf +By default GSE will fetch snapshot and stag3 files if the local files are missing, if they do not +pass local verifications, or if they fail any other health check test. By passing -fn, +gse is instructed to fetch new snapshots and stag3 tarballs. +.fi +.TP +\fB\-\-start-new\fR \fB\-sn\fR +When gse is asked to build a new system, it checks local files and decided from where it should resume, if +it work had been done in the past. At the begining a prompt start new or continue from where tou left off +appears and then at each Part X: (see man 5 gse for Stages, Parts and Masks) a prompt asks if you want to +continue or run again that Part, in case configuration changes have been made. If one wants to force gse to +force new builds, without any prompt (could be used if someone wants to enable the build, and simple go away), +then -sn should be used. + +Warning: This option purges everything in the workdir. +.fi +.TP +\fB\-\-help\fR \fB\-h\fR +.nf +Prints the help screen and exits +.fi +.TP +\fB\-\-keep\fR \fB\-\-k\fR +.nf +This option does what the start-new option, however it saves all workdone /var/gse/work-<date>. +If disk space is not an issue, then this option should be preferred rather than -sn +.fi +.TP +\fB\-\-health-check\fR \fB\-\-hc\fR +.nf +This option simply checks the important scrips for modifications and marks them for restore if +changes are found. +.fi +.TP +\fB\-\-replace-new\fR \fB\-\-rpn\fR +This options replaces all configuration data, and scripts. You don't want to use this, unless +configuration data have been lost or altered beyond a restore point. The script files can be refreshed from +the health-check entry. +.fi +.SH "SEE ALSO" +.nf +man 5 gse + diff --git a/docs/documentations/gse.5 b/docs/documentations/gse.5 new file mode 100644 index 0000000..f334d46 --- /dev/null +++ b/docs/documentations/gse.5 @@ -0,0 +1,224 @@ +.TH "GSE" "5" +.SH NAME +GSE \- Gentoo Stateless Environment +.SH "DESCRIPTION" +.nf +\fB\GSE\fR\ is a project that aims on creating a Gentoo system, by reading configuration files to customize the +system to be built. GSE provides a guided menu that the user can use for configuring those files and +then initiate the building process. During the built process, two products are created, the system being one +and the other one being the kernel with the initramfs being the second. The separation of those is important, +since the kenrel and initramfs will be distributed alone, while the system will be fetched from the controller +functions inside the initramfs and installed on the SYSFS partition. +.fi + +.PP +.nf +\fBThe Builder's\fR process is split in four main stages. \fBStage A\fR contains two parts, \fBStage B\fR contains six Parts +and last \fBStage C\fR which contains two xparts +.if + +.TP +.nf +\fBPart's of stage A:\fR +Part A: Fundamentals +Part B: Preparing the system for chrooting +.fi + +.TP +.nf +\fBPart's of stage B:\fR +Part C: Syncing Portage +Part D: Rebulding the system {Optional Part} +Part E: Configuring the System +Part F: Installing Requested Packages +Part G: Updating Runlevel Entries +Part H: Building the Kernel +Part I: Building the Initramfs. +.fi + +.TP +.nf +\fBParts's of stage C:\fR +Part J: Clean the system +Part K: Archiving & Signing +Part L: Mark for Distribution +.fi + +.PP +.nf +.TP +\fBDescription per part\fR +Part A. Verifies the sources and creates a stage 3 system using catalyst +Part B. Creates the mount points, and files to be used for the scripting process +Part C. Installs eix and updates portage +Part D. Prompts for a world rebuild, if the system is not created from catalyst +Part E. This part reads all the configuration files and applies changes to the system +Part F. Essential to make the system further functional and requested user packages +Part G. Reads the .config file, prompts for extra configuration and builds a modular kernel +Part I. This part creates an initramfs with dracut, using custom modules to enable the controller +Part J: Removes all packages that are no longer required +Part K: Exits chroot, further clean the syste, archive it and sign it +Part L: Mark the products complete and ready to be distributed. From now, all clients that request +a version check, will be notifed for this product and prompted to begin fetching +.fi + +.PP +.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 sublovlumes +-Even wipe the whole setup and start new +.fi + +.SH "DESCRIPTION OF DIRECTORIES AND FILES" +.TP +\fBThe GSE directories and files\fR +.nf +├── bin +│ └── gse +├── config.d +│ └── system +│ ├── catalyst +│ │ ├── catalyst.conf +│ │ ├── catalystrc +│ │ ├── stage1.spec +│ │ ├── stage2.spec +│ │ └── stage3.spec +│ ├── consolefont +│ ├── coptions +│ ├── custom_pacl +│ ├── custom_scripts +│ ├── devname.info +│ ├── fstab +│ ├── fstab.info +│ ├── grub +│ ├── hostname +│ ├── hosts +│ ├── inject_files +│ ├── kernel-conf +│ ├── locale.gen +│ ├── net +│ ├── portage +│ │ ├── localrepo +│ │ │ ├── layout.conf +│ │ │ └── localrepo.conf +│ │ ├── make.conf +│ │ ├── makeconf.backup +│ │ ├── package.use +│ │ │ ├── sysbuild +│ │ │ └── sysbuild.backup +│ │ └── profiles +│ │ ├── child-gse +│ │ │ ├── eapi +│ │ │ └── parent +│ │ └── parent-gse +│ │ ├── eapi +│ │ ├── make.defaults +│ │ ├── package.use +│ │ └── package.use.force +│ ├── runlevels +│ ├── sshd +│ ├── ssh.pub +│ └── system_links +├── etc +│ └── gentoo.conf +├── local +│ ├── loc_req +│ ├── nogloc_req +│ └── sinprog +├── README.md +├── scripts +│ ├── chroot_scripts +│ │ ├── chinit.conf +│ │ ├── chprint_inf +│ │ ├── chroot_init +│ │ ├── chsinit_mon +│ │ └── chsinprog +│ ├── controller +│ ├── functions +│ │ ├── drv_interface +│ │ ├── init_stage3_seq +│ │ ├── lcreq +│ │ ├── makeconf_ed +│ │ ├── men_opt +│ │ ├── print_inf +│ │ └── sinit_mon +│ └── sinit +└── TODO + +.fi + +.PP +.nf +The \fBconfig.d\fR directory is probably the most important directory of this project, since there +are stored all the configuration files, holding the instrucitons that the builder is using and +all the configuration files that the controller is fetching when live, which then uses to make +decisions. + +\fBSystem\fR, subdirectory holds the data used by the builder. Even the data that are used for +building the controller lie under this subdirectory. The main menu configuration entries, +are referring to system directory. One can manually import his make.conf and catalyst specs +before initiating the builder but that is not recommended, since many functions use specific +areas of those configuration files, therefore missing to import them, will make the process +at best, or worst, give a system that seems fine but could utterly break user data when booted. + +\fBController\fR, subdirectory holds configuration files to be used by the the controller inside +the intiramfs. Here one would change for example the cfstab entry, and then send a SIGHUP to the +clients, asking them to reboot. When the clients reboot, the controller will fetch the data from +this subdirectory and apply them locally. When done, all N clients will be forced to use the new +fstab entries. + +For someone to modify the configuration files that lie here, implies that he wants to make changes +to every machine related with the Server/s, and so, modification here must always be rare and planned +with care. If you wish to modify the fstab entry of a particular client, then simply mask fstab from the +controller and then use mount -o rw,remount /, apply changes and reboot. + +\fBMasking\fR, is a way to insturct the controller what he should not consider modifying. Masking is one +of the most important factors of the controller, as is the masking under /etc/portage on any +Gentoo system. A setup that runs without masks, implies that everything connected to the server will +oblige to it. The server has complete control on all N systems. + +To mask a configuration file, simply add #CF_MASK=ON on that file, from the client's side. +To mask a directory for the controller, simply put a .CD_MASK file in that directory. For example +to make the controller ignore whatever lies inside the the /root/.ssh directory, simply do a +touch /root/.ssh/.CD_MASK and your are done, while to make the controller ignore only a file, e.g. +fstab, simply put #CF_MASK=ON. The #CF_MASK=0 must be the only entry ont hat line, and must lead the +line. +.fi +.SH SUPPORTED ARCHITECTURES +.nf +.B x86_64 +.B ~x86 +.fi +.TP +.B Architectures to be included in the future +.nf +.B arm +.B arm64 +.fi +.SH NOTES +.nf +This project was created during the GSoC 2017 for Gentoo, meaning that the time for implementing it +was three months, therefore you must expect to find bugs. If you do find, please report them at <email> +.fi +.SH "SEE ALSO" +.nf +man 1 gse +man 1 controller +.fi |