==============================================================================
 KUSA - STEPS FOR FRESH INSTALL
==============================================================================

CONTEXT
------------------------------------------------------------------------------

. a Devuan basic system; actually works on other platforms (PVE, OMV); Ubuntu
  support stopped at 12.04

. network running, static or dhcp, with internet access (or at least access
  to an internal repository from which install the needed packages)

. ssh server installed whould be nice, but you can perform the first steps
  of installation directly from console, provided that you can transfer
  needed files in some way (eg: usb stick)



FILESYSTEMS
------------------------------------------------------------------------------

. there isn't a required filesystem layout for a kusa system, and the presence
  and layout of various layers (raid, lvm, etc) depends on purpouse of the
  machine, it's your choice

. for historycal reasons a canonical kusa layout is something like this:

  	- /	the root, varying from 5 to 16 Gb; note that
		we usually don't use a separate /var (see below)
	- /w	the data filesystem; note that a few /var
		directories will be redirected (symlinked) here


BETTER TO KNOW BEFORE STARTING
------------------------------------------------------------------------------
. kusa is written entirely in bash, except for the utility to read the config
  database, written in Perl; the command kusa-reconf is a wrap for "jtconf"

. the needed packages are:

  	for kusa		kusa
	for jtconf		jtools, liboptions-file-perl

  other packages will be automatically download as requested

. the main configuration script is "kusa-reconf", with "kusa-functions.sh"
  (included at beginning)



MODULES AND DB FILES
------------------------------------------------------------------------------

. kusa is based on concept of modules; a module is a part of os related do
  a specific function, ie: net, base-users, srv-web, cli-nagios, ...
  requesting a module will trigger the installation of related packages,
  config files, and optionally perform a script to setup things

. you can see the modules in /usr/lib/kusa/modules directory

. the modules relies on definitions in the so called "kusa db", a mix of
  structured text files (more later); each module has default values
  defined in a file called "dist-MODULENAME"

. dist files (and sometime entire modules) can come in different flavors,
  depending on, ie, system version, so we can have a dist file called
  "dist-MODULENAME.daedalus", that is added to standard distfile
  (override); use the command "ku-distroenv" to see the normalized
  DISTRIB_ID and DISTRIB_FULL_ID used for this purpouse

. the main configuration command to use is "kusa"; the real program used is
  "kusa-reconf", kusa is a fronted that will call kusa-reconf recording all
  output in files under numbered directories /var/log/kusa/NNNN

. use kusa-reconf alone just to little, basic steps, usually is better use
  "kusa" wrap to have a log record for troubleshooting

. use kusa-conf command to examine the kusa definitions db; the db entries
  are defined, and ovverided when needed, in order from:

  	. kusa defaults
	. modules distfiles
	. /etc/kusa/conf.d/ dir snippets
	. /etc/kusa/kusa.conf file
	. /etc/kusa/kusa.debug file

. to see the config database use the kusa-conf command, eg:

	# kusa-conf --dump --regexp .   (the full db)

	# kusa-conf --dump section_name

  add --no-parse as first option if you want to disable the recursive internal
  variables replacement, and discover where a definition will get his value

. as said, each kusa module have its own defaults settings (distfiles), you
  can override or integrate them adding your definitions in
  /etc/kusa/kusa.conf file, or writing config snippets in /etc/kusa/conf.d/
  directory; do not use the "auto" prefix in this directory, is reserved for
  auto and/or downloaded config snippets by kusa itself

. to see which modules will be installed use the kusa-conf command like this
  (eg: for "server" class):

  	# kusa-conf --dump class.server.modules

. another way see which modules will be installad is to run "kusa-reconf" in
  dry-run / keep tempdir mode:

  	# kusa-reconf -b

  the advantage of this approach is that you can also see the precedence of
  modules installation



STEP 1: INSTALL KUSA PACKAGES
------------------------------------------------------------------------------

. from an installed kusa system copy those two script in a temporary location,
  as /tmp, and make them executable

	scp /bin/ku-distroenv /usr/sbin/kusa-bootstrap target:/tmp

. on the target system run kusa-bootstrap: this will add a temporary apt
  entry in /etc/apt/sources.list.d for our repositories and install "kusa"
  package

. debconf: since almost all aspect of the system will be auto configured by
  kusa, the debconf dialogs are useless and annoying, kusa-bootstrap will
  ask to reconfigure debconf and you have the choice to hide the dialogs,
  selecting the option "Noninteractive"


STEP 2: NETWORK AND BASIC TOOLS
------------------------------------------------------------------------------

. basically you need to decide a couple of things, before running kusa-reconf:

	- the class of the system (eg: server, server.web, laptop); the
	  class will automatically select the neede modules

	- the extra modules you want to add, or modules that you want to
	  skip (if any)

	- some basic system info, like the hostname, the network address;
	  domain, network settings (network, gateway, netmask) can be
	  automatically providede if you are using the remote config feature,
	  otherwise you need to define them locally

. a default, example kusa main config file /etc/kusa/kusa.conf is installed
  by kusa package; edit it for your needs

. if your use the centralized config approach (recommended) you just have to
  define the machine class, the network settings and the remote config urls

. otherwise, if you are performing a standalone configuration you need to
  define each setting by hand; what setting depends on which modules you
  have requested

. the modules installed depends on which class(es) you have declared in
  /etc/kusa/kusa.conf file; you can add additional modules using the
  "extramodules" definition, or remove them using the "skiplist" definition

. configure the basic modules: network, repositories, basic stuffs:
# kusa net base-service base-repos base

. perform a system upgrade, just to have a good starting point:

	# apt-get upgrade


STEP 3: USERS
------------------------------------------------------------------------------

. kusa works better with a normalized system userbase, this step is optional
  but recommended

. mail (send only)

  	# kusa srv-smail

  note that if you have "exim" installed, like in very old Devuan system
  (1.1), you need to remove it, as conflict with postfix install


. run the system users normalization:

	# kusa -s base-users base-users

. you need to reboot your machine at this point

. WARNING! before a reboot, make sure that all was gone well, if
  working on a remote machine doble check the network settings 
  (/etc/network/interface) and the ssh server settings
  (/etc/ssh/sshd_config); make sure that you can remotely access
  with root (PermitRootLogin yes in sshd_config, or ssh credentials
  correctly setup and tested, or sudo available for a low privileged
  user)

. I REPEAT: ON REMOTE MACHINES CHECK NETWORK AND SSHD CONFIG TO MAKE
  SURE YOU WILL ABLE TO LOGIN AGAIN AFTER A REBOOT


STEP 4: CONFIGURE THE WHOLE SYSTEM
------------------------------------------------------------------------------

. before proceed, you may want to cleanup some things:

	- /etc/fstab (if you prefer to use real devices or label
	  approach, instead of uuid)

	- /etc/aliases: wipe out all default entries, will be filled
	  by kusa


. run kusa on all needed modules:

	# kusa


LAST BUT NOT THE LEAST
------------------------------------------------------------------------------
unix / linux have a long history of love for recursion

you should have noted that the first step is to copy the bootstrap script from
an istalled machine, so you need an already installed one to install a new one
... duh! :D

this is the easy way, the method used on production environment where you
already have such machines

to start ex-novo, you can manually download the packages from our repos:

    https://repos.kubit.ch

download this packages in a temp dir, and install using "dpkg -i *.deb":

  kusa
  ku-base
  ku-file-utils
  ku-jtools
  kuwatcher
  ku-images
  liboptions-file-perl


or you can download only kusa and ku-base, and extract ku-distroenv (from
ku-base) and kusa-bootstrap (from kusa), using dpkg --extract

that is, have fun!
Lorenzo Canovi

=========================================================================================
