Browse Source

documentation first draft

2.3.1
obarun 2 years ago
parent
commit
1902bf4842
  1. 214
      doc/boot@.md
  2. 69
      doc/html/boot@.html
  3. 13
      doc/make-html.sh
  4. 42
      doc/make-man.sh

214
doc/boot@.md

@ -0,0 +1,214 @@
title: The 66 Suite: boot@-66serv
author: Eric Vidal <eric@obarun.org>
# boot@ service
The boot@ instantiated service is a portable set of service to boot a machine in conjunction with the 66 API.
## How to enable
Like any other instantiated service to enable it you need to specify the target of the service. The target can be a random name.
Such this service is a specific service to handle the boot sequence of a machine, its usually enabled on a tree build especially for it and contains only this service.
For example:
```
# 66-tree -n boot
# 66-enable -t boot boot@system
```
The name of the tree need to match the name set at your `TREE=` *key=value* pair define into the `/etc/66/init.conf` file.
Do not marks this tree enabled with the `66-tree -E` option. The [66-init](https://web.obarun.org/software/66/66-tree.html) will take care for you about this special tree and starts it automatically.
Refer to the [66-tree](https://web.obarun.org/software/66/66-tree.html) and [66-enable](https://web.obarun.org/software/66/66-tree.html) for further information about these tools.
## How to configure it
This service is declared as a `module` service and comes with its own configuration file.
The configuration file can be seen easily using the [66-env](https://web.obarun.org/software/66/66-env.html) tool with:
```
# 66-env boot@system
```
When you're done editing this file, you need to enable again the service to apply your changes:
```
# 66-enable -t boot -F boot@system
```
## Configuration file key=value pair explanation
Two differents kind of variable is used:
- boolean: accepts as valid value the term `yes` or `no` and nothing else.
- string: depends of the variable and defines in the following documentation.
---
- **HOSTNAME**:
- type: string.
- valid value: anything you want.
- description: tells at the kernel the hostname to use and set the /etc/hostname file with the value passed.
- **TZ** (TimeZone):
- type: string.
- valid value: any valid name found at /usr/share/zoneinfo.
- description: creates a symlink at `/etc/localtime` pointing to the `/usr/share/zoneinfo` directory define. Usually the value contain a slash like Pacific/Noumea, America/New_york,...
- **KEYMAP**:
- type: string.
- valid value: any valid name found at `/usr/share/kbd/keymaps` directory.
- description: uses the `loadkeys` program to set the keymap for the console to use. Usually a simple string like fr, us,...
- **FONT**:
- type: string.
- valid value: any valid name found at `/usr/share/kbd/consolefonts`.
- description: uses the `setfont` program to set the font for the console to use. Usually a simple string like lat9w-16, alt-8x14,...
- **FONT_MAP**:
- type: string.
- valid value: any valid name found at `/usr/share/kbd/consoletrans`.
- description: uses the `setfont` program to indicate the mapping to use. Usually a simple string like 8859-1, 8859-2,...
- **FONT_UNIMAP**:
- type: string.
- valid value: any valid name found at `/usr/share/kbd/unimaps`.
- description: uses the `setfont` program to indicate the unicode mapping table to use. Usually no mapping table is needed, and a Unicode mapping table is already contained in the font.
- **FSTAB**:
- type: boolean.
- description: uses the `mount -a` command to mount each filesystem set at `/etc/fstab`.
- **SWAP**:
- type: boolean.
- description: uses the `swapon -a` command to active your swap partitions/files.
- **LVM**:
- type: boolean.
- description: uses the `lvmetad` and `vgchange` program to activate a LVM partitions.
- **DMRAID**:
- type: boolean.
- description: uses the `dmraid` program to activate a RAID partitions.
- **BTRFS**:
- type: boolean.
- description: uses the `btrfs` program to activate a BTRFS partitions.
- **ZFS**:
- type: boolean.
- description: uses the `zfs` program to mount a ZFS partitions.
- **ZFS_IMPORT**:
- type: string.
- valid value: scan or zpoolcache.
- description: select the import method to use to detect the ZFS devices. This variable work in conjunction with the `ZFS` variable. In case of the `ZFS` variable is set to no or commented, the `ZFS_IMPORT` variable has no effects.
- **SETUPCONSOLE**:
- type: boolean.
- description: set it to no if you don't want to configure the console. In this case the `KEYMAP,FONT`, `FONT_MAP`, `FONT_UNIMAP` variable has no effects.
- **HARDWARECLOCK**:
- type: string.
- valid value: UTC or locatime.
- description: Restore the system clock to the given timezone set at `TZ` variable and set the hardware clock with timescale given (A.K.A. UTC or localtime).
- **UDEV**:
- type: boolean.
- description: use the udev program to detect the devices e.g. network card, external hard drive, .... If it's set to no the `SETUPCONSOLE`, `KEYMAP`, `FONT`, `FONT_MAP`, `FONT_UNIMAP`, `CRYPTTAB`, `DMRAID`, `BTRFS`, `LVM` variable has no effects.
- **SYSCTL**:
- type: boolean.
- description: use the sysctl program to change the kernel parameters at runtime. The `/etc/sysctl.conf` ***must*** exist on your system and correctly written.
- **FORCECHCK**:
- type: boolean.
- description: force the check of the files system.
- **LOCAL**:
- type: boolean.
- description: use the `/etc/66/rc.local` script. This script is launched at the end of the boot procedure. The file ***must*** exist on your system and executable with a correct definition of the shebang at the start of the script.
- **CONTAINER**:
- type: boolean.
- description: convenient variable used to boot inside a container. Some services will not works or unnecessary when you boot inside a container. This variable provide you a safe default for this purpose. If set to yes the `HARDWARECLOCK`, `SETUPCONSOLE`, `KEYMAP`, `FONT`, `FONT_MAP`, `FONT_UNIMAP`, `CRYPTTAB`, `SWAP`, `LVM`, `DMRAID`, `BTRFS`, `ZFS`, `UDEV`, `SYSCTL`, `FORCECHCK`, `CGROUPS`, `MODULE_SYSTEM`, `RANDOMSEED`, `MNT_NETFS` variable has no effects.
- **TMPFILES**:
- type: boolean.
- description: read, parse and apply a systemd-style tmpfiles.d files usually found at `/usr/lib/tmpfiles.d` directory to handle volatile and temporary files.
- **MODULE_KERNEL**:
- type: boolean.
- description: load the kernel modules returned by the `kmod static-nodes` command.
- **MODULE_SYSTEM**:
- type: boolean.
- description: read, parse and load the modules found at `/etc/modules-load.d`, `/run/modules-load.d`, `/usr/lib/modules-load.d`.
- **RANDOMSEED**:
- type: boolean.
- description: generates random numbers and save it at `/var/lib/random-seed` if it doesn't exist yet.
- **CRYPTTAB**:
- type: boolean.
- description: use the file `/etc/crypttab` to decrypt an encrypted device. The file `/etc/crypttab` ***must*** exist on your system.
- **FIREWALL**:
- type: string.
- valid value: iptables,ip6tables,nftables,ebtables,arptables.
- description: use the given program to set a firewall applying the correspond configuration files. In case of iptables and ip6tables the `/etc/<program>/<program>.rules` file ***must*** exist on your system. In other case the `/etc/<program>.conf` ***must*** exist on your system.
- **CGROUPS**:
- type: boolean.
- description: read and parse the `/proc/cgroups` file and mount the corresponding `/sys/fs/cgroup/<groups>` directory. The `/sys/fs/cgroup/unified` is also mounted.
- **MNT_PROC**:
- type: boolean.
- description: check and mount the `/proc` directory if it not mounted yet.
- **MNT_SYS**:
- type: boolean.
- description: check and mount the `/sys` directory if it not mounted yet.
- **MNT_DEV**:
- type: boolean.
- description: check and mount the `/dev` directory if it not mounted yet.
- **MNT_RUN**:
- type: boolean.
- description: check and mount the `/run` directory if it not mounted yet.
- **MNT_TMP**:
- type: boolean.
- description: check and mount the `/tmp` directory if it not mounted yet.
- **MNT_PTS**:
- type: boolean.
- description: check and mount the `/dev/pts` directory if it not mounted yet.
- **MNT_SHM**:
- type: boolean.
- description: check and mount the `/dev/shm` directory if it not mounted yet.
- **MNT_NETFS**:
- type: boolean.
- description: mount all files system with the command `mount -a -t nosysfs,nonfs,nonfs4,nosmbfs,nocifs -O no_netdev`.
- **POPULATE_SYS**:
- type: boolean
- decription: mount the `/sys/firmware/efi/efivars`, `/sys/fs/fuse/connections`,`/sys/kernel/config`, `/sys/kernel/debug` and `/sys/kernel/security` directory.
- **POPULATE_DEV**:
- type: boolean
- description: mount the `/dev/hugepages` and `/dev/mqueue` directory.
- **POPULATE_RUN**:
- type: boolean
- description: mount the `/run/lvm`, `/run/user` and `/run/lock` directory.
- **POPULATE_TMP**:
- type: boolean
- description: create the `/tmp/.X11-unix` and `/tmp/.ICE-unix` directory.

69
doc/html/boot@.html

@ -0,0 +1,69 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>The 66 Suite: boot@-66serv</title>
<meta name="author" content="Eric Vidal &#60;eric@obarun.org&#62;" />
</head>
<body>
<h1 id="boot@%20service">boot@ service</h1>
<p>The boot@ instantiated service is a portable set of service to boot a machine in conjunction with the 66 API.</p>
<h2 id="How%20to%20enable">How to enable</h2>
<p>Like any other instantiated service to enable it you need to specify the target of the service. The target can be a random name.</p>
<p>Such this service is a specific service to handle the boot sequence of a machine, its usually enabled on a tree build especially for it and contains only this service.</p>
<p>For example:</p>
<pre><code># 66-tree -n boot
# 66-enable -t boot boot@system
</code></pre>
<p>The name of the tree need to match the name set at your <code>TREE=</code> <em>key=value</em> pair define into the <code>&#47;etc&#47;66&#47;init.conf</code> file.</p>
<p>Do not marks this tree enabled with the <code>66-tree -E</code> option. The <a href="https://web.obarun.org/software/66/66-tree.html">66-init</a> will take care for you about this special tree and starts it automatically.</p>
<p>Refer to the <a href="https://web.obarun.org/software/66/66-tree.html">66-tree</a> and <a href="https://web.obarun.org/software/66/66-tree.html">66-enable</a> for further information about these tools.</p>
<h2 id="How%20to%20configure%20it">How to configure it</h2>
<p>This service is declared as a <code>module</code> service and comes with its own configuration file.
The configuration file can be seen easily using the <a href="https://web.obarun.org/software/66/66-env.html">66-env</a> tool with:</p>
<pre><code># 66-env boot@system
</code></pre>
<p>When you&#39;re done editing this file, you need to enable again the service to apply your changes:</p>
<pre><code># 66-enable -t boot -F boot@system
</code></pre>
<h2 id="Configuration%20file%20key=value%20pair%20explanation">Configuration file key=value pair explanation</h2>
<p>Two differents kind of variable is used:</p>
<ul>
<li><p>boolean: accepts as valid value the term <code>yes</code> or <code>no</code> and nothing else.</p></li>
<li><p>string: depends of the variable and defines in the following documentation.</p></li>
</ul>
<hr/>
<ul>
<li><strong>HOSTNAME</strong> :
<ul>
<li>type: string</li>
<li>valid value:
Anything you want</li>
<li>description:
Tells at the kernel the hostname to use and set the &#47;etc&#47;hostname file with the value passed.</li>
</ul></li>
</ul>
</body>
</html>

13
doc/make-html.sh

@ -0,0 +1,13 @@
#!/bin/sh
html='boot@'
if [ ! -d doc/html ]; then
mkdir -p -m 0755 doc/html || exit 1
fi
for i in ${html};do
lowdown -s doc/${i}.md -o doc/html/${i}.html || exit 1
done
exit 0

42
doc/make-man.sh

@ -0,0 +1,42 @@
#!/bin/sh
man1='66-all 66-dbctl 66-disable 66-echo 66-enable 66-env 66-init 66-inresolve 66-inservice 66-instate 66-intree 66-parser 66-scanctl 66-scandir 66-start 66-stop 66-svctl 66-tree 66-update execl-envfile'
man8='66-boot 66-hpr 66-shutdown 66-shutdownd 66-umountall'
man5='frontend instantiated-service module-service'
for i in 1 5 8;do
if [ ! -d doc/man/man${i} ]; then
mkdir -p -m 0755 doc/man/man"${i}" || exit 1
fi
done
for i in ${man1}; do
lowdown -s -Tman doc/"${i}".md -o doc/man/man1/"${i}".1 || exit 1
var=$(head -n1 < doc/man/man1/"${i}".1)
var=$(printf '%s' "$var" | tr '7' '1')
var="${var} \"\" \"General Commands Manual\""
sed -i "s!^.TH.*!${var}!" doc/man/man1/"${i}".1 || exit 1
sed -i '2,5d' doc/man/man1/"${i}".1 || exit 1
done
for i in ${man5}; do
lowdown -s -Tman doc/"${i}".md -o doc/man/man5/"${i}".5 || exit 1
var=$(head -n1 < doc/man/man5/"${i}".5)
var=$(printf '%s' "$var" | tr '7' '5')
var="${var} \"\" \"File Formats Manual\""
sed -i "s!^.TH.*!${var}!" doc/man/man5/"${i}".5 || exit 1
sed -i '2,5d' doc/man/man5/"${i}".5 || exit 1
done
for i in ${man8}; do
lowdown -s -Tman doc/"${i}".md -o doc/man/man8/"${i}".8 || exit 1
var=$(head -n1 < doc/man/man8/"${i}".8)
var=$(printf '%s' "$var" | tr '7' '8')
var="${var} \"\" \"System Administration\""
sed -i "s!^.TH.*!${var}!" doc/man/man8/"${i}".8 || exit 1
sed -i '2,5d' doc/man/man8/"${i}".8 || exit 1
done
exit 0
Loading…
Cancel
Save