## Quick start

### Prepare a system

- Bootstrap an Arch Linux system:

```sh
mkdir system
pacstrap system base linux sudo xorg xfce4 lightdm-gtk-greeter network-manager-applet chromium #...
chroot system pacman -Scc
chroot system systemctl enable lightdm
chroot system systemctl enable NetworkManager
chroot system useradd -m -g users -G wheel linomad
echo -e "root:root\nlinomad:linomad" | chroot system chpasswd
sed 's/# \(%wheel ALL=(ALL)\)/\1/' -i system/etc/sudoers
```
- Or, a Slackware one :

```sh
mkdir system
mount -o loop path/to/slackware64-current.iso /mnt
installpkg --terse --root system /mnt/slackware64/{a,ap,d,l,n,x,xap,xfce}/*.t?z
umount /mnt
ln -sf xinitrc.xfce system/etc/X11/xinit/xinitrc
sed 's/^id:3:initdefault:$/id:4:initdefault:/' -i system/etc/inittab
chmod +x system/etc/rc.d/rc.networkmanager
chroot system useradd -m -g users -G wheel,audio,video,plugdev linomad
echo -e "root:root\nlinomad:linomad" | chroot system chpasswd
sed 's/# \(%wheel ALL=(ALL:ALL)\)/\1/' -i system/etc/sudoers
```
- Or, an Ubuntu one :

```sh
mkdir system
debootstrap --include ubuntu-minimal focal system http://archive.ubuntu.com/ubuntu
cp -a /etc/apt/* system/etc/apt/
for d in sys proc dev dev/pts; do sudo mount --bind /$d system/$d; done
chroot system apt update
chroot system apt upgrade
apt-mark showmanual > packages.lst
chroot system apt install $(cat packages.lst)
chroot system locale-gen
chroot system useradd -g users -G adm,cdrom,sudo,plugdev,lpadmin -m -s /bin/bash linomad
echo "linomad:linomad" | chroot chpasswd
chroot system systemctl disable apparmor.service
for d in dev/pts dev proc sys; do sudo umount system/$d; done
```


### Make it live

- Setup kernel, initRamFs, GRUB EFI image and configuration file:

```sh
build-live-system.sh --init system live
```
- Create a SquashFS module of the system:

```sh
build-live-system.sh --module system live 0-base-xfce
```
- According to your needs, generate an ISO 9960 of the live DVD (and possibly
test it with Qemu):

```sh
build-live-system.sh --iso live live-system.iso
qemu-system-x86_64 -enable-kvm -m 2048 -cdrom live-system.iso
```
- Or copy the live system to an USB stick; **warning: this will destroy the
data on the USB device**:

```sh
build-live-system.sh --usb live /dev/sdx
```



## Build script usage - live-system generation

### Variables influencing the script behavior

There are some environment variables that can customize live-system generation:

- `LIVELABEL` (`LiveSystem` by default): the live-system filesystem label,
- `LIVEDIR` (`linomad` by default): the live-system directory name,
- `HOMELABEL` (`LiveData` by default): the persistent data filesystem label,
- and `IMGSIZE` (7680 MiB by default): the size of the disk image for a USB drive.

They should be set before running any of the `--init`, `--module`, `--usb`
`--img` or `--iso` actions:

```sh
HOMELABEL="home-rw"
LIVELABEL="system-ro"
build-live-system.sh --init system live
#...
```


### Setup kernel, initRamFs, GRUB EFI image and configuration file

#### Usage

```sh
build-live-system.sh --init root_dir live_dir [additional:modules]
```
Generates: `live_dir/efi/boot/{bootx64.efi,grub.cfg}` and `live_dir/linomad/{vmlinuz,initrd.gz}`.
Included kernel modules (unless builtin and with their dependencies) are:

- keyboard support (Busybox console): atkbd, i8042
- P/S-ATA & CD-ROM support: ata_piix, sr_mod
- USB support: xhci-pci, ehci-pci, usb-storage
- live filesystems: nls-iso8859-1, isofs, nls-cp437, vfat, ext4, loop, overlay, squashfs

Usually additional modules are NFS and ethernet drivers needed to boot over NFS.

#### Examples

```sh
build-live-system.sh --init system live
build-live-system.sh --init system live nfsv3:e1000e:8139too:atl1c:alx
```


### Create a SquashFS module for the system

#### Usage

```sh
build-live-system.sh --module root_dir live_dir module_file [-gzip|-lza|-lzma|-lzo|-xz|-zstd]
```
All `root_dir` subdirectories but `/sys`, `/proc`, `/dev` and `/tmp` are included.
Generates: `live_dir/linomad/modules/module_file`.

The compression option has an impact on media size and speed; `zstd` is the default.

The system can be divided into multiple modules (example: "1-core", "2-gui", ...)
that are loaded in alphabetical order; if a file is present in several modules,
the one taken from the last loaded module is used.

#### Example

```sh
build-live-system.sh --module system live 0-main
```


### Copy live system to USB device

**Warning: this operation can destroy USB device data**.

#### Usage

```sh
build-live-system.sh --usb live_dir device [systemsize]
```

This action triggers two different behaviors:

- if `systemsize` is **not** specified **and** if the device already contains
a live-system (ie `$LIVELABEL` is found on device), an update is performed:
    - fsck is run on system and data partitions,
    - *extra storage and persistent data are kept*,
    - existing `efi` and `$LIVEDIR` are overwritten with their new versions.
- in the other cases, the device is wiped, **permanently destroying all its data**:
    - device is partitionned using GPT (GUID Partition Table - see table below),
    - live-system and persistent data partitions are formatted,
    - live-system files are copied.

| N° |  Type  | FileSystem |    Size    |   Label    |           Content           |
|----|--------|------------|------------|------------|-----------------------------|
| 1  | 0xef00 | vfat       | systemsize | $LIVELABEL | live-system |
| 2  | 0x8300 | ext4       | remaining  | $HOMELABEL | persistent data             |

- when partitioning, if `systemsize` is not specified, its size will be adjusted 
according to that of the system. For example, if the system size is 1.5 GiB, 
the `systemsize` will be calculated as 1.5 x 2 (for live updates), rounded 
to the nearest multiple of 2, resulting in 4 GiB.

#### Examples

```sh
build-live-system.sh --usb live /dev/sdx 8192   #install (systemsize is specified)
build-live-system.sh --usb live /dev/sdx        #install or update (`$LIVELABEL` found)
```


### Create ISO or disk image

These operations are useful for distributing the live system. ISO images are
intended for DVDs, while disk images are for USB devices, allowing data persistence.
*USB Flashing is slower than partitionning, formatting and copying *

#### Usage

```sh
build-live-system.sh --img live_dir img_file_name
build-live-system.sh --iso live_dir iso_file_name
```

*The disk image will, by default, have a size of 7.5 GiB (less than 8 GB for
compatibility) and will be compressed with zstd.*

#### Example

```sh
build-live-system.sh --img live live.img
build-live-system.sh --iso live live.iso
```


### Flash disk image to USB device

**Warning: this operation destroys USB device data**.

#### Usage

```sh
zstd -d compressed_img_file_name -o device
```

*The device must have a minimum size of `IMGSIZE` (8 GB by default).*


#### Example

```sh
zstd -d live.img.zst -o /dev/sdx
```

It is then recommended to resize the `LiveData` partition and optionnally 
create an additionnal exFAT one, to share data between systems. Use a [GParted](https://gparted.org/)
like partition editor, or the command line:

- option 1: use all available space for the `LiveData` partition: 

```sh
sgdisk -d 2 -n 2:0:0 /dev/sdx
resize2fs /dev/sdx2
```

- option 2: resize the `LiveData` partition (to 8 GiB in this example) and 
add another shared one:

```sh
sgdisk -d 2 -n 2:0:+8G -n 3:0:0 -t 3:0700 /dev/sdx
partprobe /dev/sdx
resize2fs /dev/sdx2
mkfs.exfat [-L "Shared Data / Anything"] /dev/sdx3
```



## Boot parameters

### System language and keymap layout

- `locale`: system language; example: `locale=fr_FR.UTF-8`
- `keymap`: keymap layout; example: `keymap=fr`; the first two caracters are
used for Xorg keymap layout
- `tz`: timezone; example: `tz=Europe/Paris` (value must be a valid path from
`/usr/share/zoneinfo`)
- `hwc`: hardware clock: `UTC` or `localtime`


### Misc

- `home=label`, `home=UUID` or `home=IP:path` (NFS): specify persistent home
location (defaults to `LiveData`);
- `sys=label:path`, `sys=UUID:path` or `sys=IP:path` (NFS): specify live system
location (defaults to `LiveSystem:linomad`)
- `exclude=module1:module2`: to prevent loading of specified modules
- `mode=busybox`: to boot into a Busybox console (instead of the live system)



## Live system installation

The live system can be installed into a hard disk partition; the result should
be the same as a clean installation following the distribution regular install
procedure. Both BIOS and UEFI firmwares are supported.


### Install system and GRUB boot loader

**Warning: this operation destroys all data on the install partition**.

#### Usage

```sh
build-live-system.sh --install root_dir partition
```

#### Example

From a running live-system:

```sh
build-live-system.sh --install /live/system /dev/sdx2
```


### Setup /home, user login and password

After installation, it is recommended to add a "normal" (non "root") user
and use a separate partition to store users files (`/home`).

#### Usage

```sh
build-live-system.sh --home install_part home_part login password
```

#### Example

```sh
build-live-system.sh --home /dev/sdx2 /dev/sdx4 linomad P@ssw0rd
```


### GRUB installation and configuration

To boot the installed system, a boot loader (eg. GRUB) must be installed and configured.


#### Usage

```sh
build-live-system.sh --grub partition
```

#### Example

```sh
build-live-system.sh --grub /dev/sdx2
```

