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=partX\fR
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=x\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\-\-base\fR \fB\-b\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\-\-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

To build a minimal system ( see --build-minimal for informations ): gse --base=catalyst --build-minimal.
.fi
.SH "SEE ALSO"
.nf
man 5 gse