path: root/docs/documentations/gse.1

.TH "GSE" "1"
.SH NAME
GSE \- Gentoo Stateless Environment
.SH SYNOPSIS
.B gse 
[\fBOPTIONS\fR] \fB--base\fR={catalyst,precomp}
.SH "DESCRIPTION"
.nf
\fBGSE\fR is a set of scripts and configuration files that takes special advantage of catalyst,
for creating a Gentoo system intended to function under stateless conditions, a modular kernel
and an initramfs which provide functions to further control and modify such a system.
.fi
.SH OPTIONS
.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, even if they are located locally.
.fi
.TP
\fB\-\-force-new\fR
When gse is asked to build a new system, it checks local files and decided from where it should resume.
At the beginning a prompt start new or continue from where you left, 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 the case it has been completed successfully. If one wants to force gse to make new builds, without any 
prompt, then -sn should be used.

Warning: This option uses force on every action and ignores any workdone. For more safe approach, see enforce.
.fi
.TP
\fB\-\-lawful-good\fR \fI[="Hook Points"]
This option instructs gse to automatically say no to a completed part. For example, if there has been
already a successful system build and one wishes to reconfigure all parts but one, say apply new changes,
then he could simply start gse with --lawful-good=apply-new. This command can be used multiple times,
each time with a new entry.

Supported entries: gfund, gseed, gsnap, gcat, extr, gprec, gupdate, gportage, gapply-new, 
gconfigure, ginstall, gkernel, ginitrd, gclean, all.

To make gse passive for everything, simply do: gse --lawful-good=all. This option will simply archive
the work done and sign it.
.fi
.TP
\fB\-\-enforce\fR \fI[="Hook Points"]\fR
See --lawful-good, for examples. The only difference is that this option instructs gse to use force on the
target part instead of being passive. Note that --enforce=all, implies --force-new.
.fi
.TP
\fB\-\-time-state\fR \fI\ [?/=state_name]\fR
Time state is the gse option for saving or viewing already saved states. A saved state is a folder that contains
all the configuration files, flags and their arguments for a given build. This state can be used again and again
and always will reproduce the same output, given no unexpected issues pupup during the process.
.fi
.TP
\fB\-\-time-warp\fR \fI[=N]\fR
Time warp enables time states. If this and only this option is passed on gse, then gse will search for the inidcated
state, export it and initiate the process.
.fi
.TP
\fB\-\-distcc\fR \fI\ [=on/pump]\fR
With this option, gse in instructed to enable distcc on the chroot stage. This option alone does nothing. One has to configure
the distcc files (the gse distcc files, not the server's config files).
.fi
.TP
\fB\-\-ccache\fR \fI\ [=yes/no]\fR
This option instructs gse to enable ccache for the chroot stage.
.fi
.TP
\fB\-\-kernel\fR \fI\ [=kern_image]\fR
With this option, gse is instructed that a kernel image already exists and so, a new kernel build should not be initiated.
.fi
.TP
\fB\-\-initramfs\fR \fI\ [=initrd_image]\fR
With this option, gse is instructed that an initramfs image already exists and so, a new initramfs build should not be initiated.
Please note, that --kernel and --initramfs options, will disable the controller functions. These options exist for builds that wish to
go controller free, hence no stateless.
.fi
.TP
\fB\-\-auto\fR \fI\ [=yes/no]\fR
This option enables/disables the gse interactive mode. By default it's on.
.fi
.TP
\fB\-\-base\fR \fB\-b\fR \fI[=catalyst/precomp]\fR
This option instructs gse about the method that should be used for the fundations of the system to be built.
Currently there are 2 options which gse supports. The one is 'catalyst', while the other is 'precomp'. The
catalyst opton will initiate the functions for creating a stage3 tarball, reading the spec files. The precomp
option instructs gse to mark the system's fundation as stage3-latest-tarball, which is the tarball that one
would donwload from the Gentoo mirors for installing a basics system. Precomp stands for precompiled which
is actually not a good name but it states that the targeted tarball has already been built by the
Gentoo Release Engineering Team.
.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 work done /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
.TP
\fB\-\-no-kernel\fR \fB\-nk\fR
.nf
This option forces gse to exclude the kernel fromt Stage B building sequence. This option implies
--no-initramfs also. If you use no kernel, you must then provide your kernel moddir, and build
and intiramfs as a separate step, by using --build-controller (see below).
.fi
.TP
\fB\-\-no-initramfs\fR \fB\-ni\fR
.nf
This option instructs gse to exclude the initramfs build from Stage B building sequence.
.fi
.TP
\fB\-\-build-controller\fR \fB\-bc\fR [\fB\-\fR\fIkernel-mods\fR]
.nf
This option will instruct gse to build only the controller. To build the initramf outside of the 
stage B you have to provide the gse with the directory containing the kernel modules. 
Be warrned however, that the setup is based on a modular kernel, therefore be sure to include
the entries that your clients will require to function and not to remove any of 
{overlayFS, tmpfs, nfs, fuser} entries.
.fi
.TP
\fB\-\-verbose\fR \fB\-v\fR
Verbose option will enable set -x on all scripts. This option should be used only fore debugging.
.fi
.TP
\fB\-\-quiet\fR \fB\-q\fR
The quiet option will disable almost all terminal output. For each part a message regarding the part
will be displayed instead. For example "Updating protage" or "Building stage1"
.fi
.TP
\fB\-\-build-minimal\fR \fB\-bm\fR
This option forces gse to exclude all extra packages that are found at chinit.conf, which is
located at /scripts/chroot_scripts. This option implies --no-kernel --no-initramfs. The GSE
profile is also excluded from the system. Minimal system is ideal for creating a simple, small
image with customized bootscripts and configuration files.
.fi
.SH EXAMPLES
You can simply call gse without any arguments, and follow the main menu and submenus for initiating
the build of your system. GSE should be run each time one wants to edit the configuration files, since
the configuration files are listed on configuration submenus which makes it more easy to follow, and
is a way to make sure you did not forget to configure an entry, since its is listed there.

The --base={catalyst,precomp} is the only option that is required to use GSE without the main menu.
It actually instructs gse that it should use the configuration files as they are and initiate the
inidcated build that follows --base=.

To instruct gse for making a system with catalyst base, you type: gse --base=catalyst.

If you have configured again the configuration files and you wish to make a new system, but keep the current
one, you could then add: gse --base=catalyst --keep, or gse --base=precomp --keep, if the system was built with
precomp method.

The --lawful-good & --enfoce options are perfect for skiping/forcing certain areas that gse will prompt to
reconfigure or continue. Asume that gse has already finished building a system with --base=catalyst and you
wish to apply new configuration options in the chroot stage. Then you could run: gse --base=catalyst
--lawful-good="gparta,gupdate,gportage,ginst,gkernel,ginitrd" --enforce="gconfiguration"
.fi
.PP
Note: Remeber hat --lawful-good supresses --enforce. Thereforce --lawful-good="gparta" --enforce="gparta" will
read only --lawful-good="gparta"
.fi
.PP
Saving a state for future use, with sourced custom scripts before the catalyst part.
.fi
gse --base=catalyst --sdir=/home/myscripts --do="script1,script2" -g="-gcat" --time-state="custom_scripts"
.fi
.PP
Enabling the state from the above example. gse --time-warp=1. It is assume that the custom_script state has a mark of 1.
If other states existed prior to this, then 1 is not true. To see the related mark, run: gse --time-state?
.fi
.PP
To build a minimal system ( see --build-minimal for informations ): gse --base=catalyst --build-minimal.
.fi
.PP
To build the controller, run: gse --controller. Without a =[moddir], gse will look in the default modules locations.
For a custom location, run: gse --controller=[moddir].
.fi
.PP
If you have a kernel already built and you wish to use that image instead of building a new one, start gse with:
gse --base=catalyst --kernel=[path/to/kernel]. 
Same holds for initramfs, gse --base=catalyst --initramfs=[path/to/image]
.fi
.SH "SEE ALSO"
.nf
man 5 gse