Initial commitv1

Signed-off-by: David Oberhollenzer <david.oberhollenzer@tele2.at>

2 files changed, 207 insertions, 0 deletions

diff --git a/docs/defconfig.md b/docs/defconfig.md
new file mode 100644
index 0000000..f0a6c86
--- /dev/null
+++ b/docs/defconfig.md
@@ -0,0 +1,124 @@
+# Default Service Configuration
+
+## Pseudo Services
+
+The default configuration contains a number of "pseudo services" in the boot
+target that don't actually do anything but are merely used as anchors in
+service dependencies, i.e. they indicate that some sort of milestone in the
+boot sequence has been reached. Everything that is part of that milestone
+specifies that it should be run *before* that pseudo service and everything
+that requires that this milestone has been reached, specifies that it wants
+to run afterwards.
+
+The pseudo targets are (in the order that they are executed):
+
+ * vfs
+
+   All services that do mount point setup go before this, all service that
+   depend on the fully mounted rootfs go after this.
+
+ * sysinit
+
+   The system has reached a sane state, i.e. the hostname is set, the system
+   clock has a sane value, modules and kernel parameters are loaded, some
+   very basic, fundamental services are running.
+   Everything that is part of that setup process goes between `vfs` and
+   `sysinit`, everything that requires a sane setup goes *after* `sysinit`.
+
+ * network
+
+   Network configuration is done. All services that do network configuration
+   should position themselves between `sysinit` and `network`. Everything that
+   requires a fully configured networking setup should go *after* `network`.
+
+## Default Bootup Services
+
+This section outlines the services for the boot target that are enabled by
+default.
+
+
+The following services are enabled by default and run *before* the `vfs` target
+for filesystem setup:
+
+ * procfs - mount `procfs` to `/proc` and try to mount additional pseudo
+   filesystems in `/proc` such as `binfmt_misc`
+ * tmpfs - mount a `tmpfs` to `/tmp`
+ * sysfs - mount `sysfs` to `/sys` and try to mount additional pseudo
+   filesystems in `/sys` (e.g. `securityfs`, `configfs`, ...)
+ * devfs - mount `devtmpfs` to `/dev`, try to mount additional pseudo
+   filesystems in `/dev` (e.g. `devpts`, `mqueue`, ...) and try to create
+   some additional device nodes and symlinks.
+ * tmpfsvar - mount a `tmpfs` to `/var` and populate it with a default set
+   of files and directories. Overlay mount `/var/lib` with lower dir on
+   `/cfg/preserve/var_lib/` and upper on `/cfg/overlay/var_lib/`.
+ * tmpfsrun - mount a `tmpfs` to `/run`, symlink `/var/run` to `/run` and
+   `/var/lock` to `/run/lock`.
+ * mountusr - overlay mount setup for `/usr`. Lower dir is on
+   `/cfg/preserve/usr/` and upper on `/cfg/overlay/usr/`.
+
+
+The following services are enabled by default and configured to run *after*
+the `vfs` target and *before* the `sysinit` target:
+
+ * hostname - reload hostname `/etc/hostname`
+ * loopback - bring the loopback device up
+ * modules - iterate over the file `/etc/modules` and try to load each module
+   using modprobe.
+ * sysctl - restore kernel parameters using `sysctl --system`. See `sysctl(8)`
+   for a list of possible locations that the parameters are read from.
+ * usyslogd - Starts and supervises the `usyslogd` syslog implementation.
+ * klogd - Starts and supervises the `klogd` daemon.
+
+
+The following services are enabled by default and configured to run *after*
+the `sysinit` target and *before* the `network` target:
+
+ * ifcfg - static network configuration
+   Does the static network configuration outlined in [network.md](network.md)
+
+
+The following services are enabled by default and configured to run *after*
+the `network` target:
+
+ * gcrond
+
+
+## Default Shutdown and Reboot Services
+
+For the shutdown and reboot targets, the following services are executed:
+
+ * sigterm - send the SIGTERM signal to all processes and wait for 5 seconds
+ * sigkill - send the SIGKILL signal to all remaining processes
+ * ifdown - bring all network interfaces down
+ * sync - run the sync command
+
+
+## Additional Services not Enabled by Default
+
+ * agetty - A parameterizeable, respawn type `agetty` service. The first
+   parameter is the terminal device that the getty should run on.
+ * consolefont - If enabled, run once before sysinit. Sets the console font
+   to the first parameter.
+ * dhcpcdmaster - If one or more network interfaces should be configured using
+   dhcpcd, this service starts a central `dhcpcd` master instance.
+ * dhcpcd - A parameterizeable single shot service that signals the `dhcpcd`
+   master that it should configure a specific interface. The first parameter
+   is the interface that should be configured by `dhcpcd`.
+ * dnsmasq - A respawn type service for the `dnsmasq` DNS and DHCP server.
+ * hostapd - If the system should operate a WIFI access point, this respawn
+   type service can be enabled to manage an instace of the `hostapd` program.
+ * unbound - A respawn type service that manages an instance of the `unbound`
+   name resolver.
+ * hwclock - If the system has a hardware clock, this service can restore the
+   kernels clock from the hardware at bootup, between the `vfs` and `sysinit`
+   targets.
+ * nft - If enabled, restores net filter table rules during boot.
+ * swclock - For systems that don't have a hardware clock, this service
+   restores a somewhat usable time from a file during boot.
+ * swclocksave - For systems that don't have a hardware clock, this service
+   saves the current time to a file during shutdown or reboot.
+ * sshd_keygen - A wait type service that generates host keys for the OpenSSH
+   server and then disables itself.
+ * sshd - Starts an OpenSSH server after the network pseudo service and after
+   the sshd_keygen service.
+ * nginx - Starts the Nginx server after the network pseudo serivce.
diff --git a/docs/network.md b/docs/network.md
new file mode 100644
index 0000000..f111a8f
--- /dev/null
+++ b/docs/network.md
@@ -0,0 +1,83 @@
+# Static Network Configuration
+
+The default configuration provides multiple services that perform network
+initialization and static configuration using helper scripts that require
+programs from the `iproute2` package.
+
+Configuration files are typically stored in `/etc/netcfg/` (depending on
+configure options).
+
+Please note that the loopback device is treated specially and not included in
+any of the network configuration outlined below. The loopback device is brought
+up and configured by a dedicated service long before the network configuration
+is done.
+
+
+## Interface Renaming
+
+If the `ifrename` service is enabled (it is disabled by default), network
+interfaces are renamed based on a rule set stored in the file `ifrename`.
+The file contains comma separated shell globing patterns for the current
+interface name, MAC address and a prefix for the new interface name.
+
+For each network interface, rules are processed top to bottom. If the first two
+globing patterns apply, the interface is renamed. Interfaces with the same
+prefix are sorted by mac address and a running index is appended to the prefix.
+
+If none of the rules apply, the interface name is left unchanged.
+
+
+The intent is, to provide a way to configure persistent, deterministic names for
+at least all network interfaces that are permanently installed on a board.
+
+Extension cards or external network adapters should be given a different prefix
+to avoid changes in the order as they come and go.
+
+
+## Interface Configuration
+
+After interface renaming, for each network interface, the configuration path is
+scanned for files with the same name as the interface.
+
+Each successfully found configuration file is processed line by line, top to
+bottom. Each line may contain a keyword, followed by multiple arguments.
+
+The following keywords can be used to add IPv4 or IPv6 network addresses to
+an interface:
+
+ * address
+ * addr
+ * ip
+ * ip6
+ * ipv6
+
+Those commands are expected to be followed by an IPv4 or IPv6 address and
+network mask.
+
+
+Furthermore, the following commands can be used for configuring interface
+parameters:
+
+ * `arp {on|off}`
+ * `multicast {on|off}`
+ * `mtu <value>`
+ * `offload [rx {on|off}] [tx {on|off}] [sg {on|off}] [tso {on|off}]`
+ * `offload [gso {on|off}] [gro {on|off}] [lro {on|off}] [rxvlan {on|off}]`
+ * `offload [txvlan {on|off}] [ntuple {on|off}] [rxhash {on|off}]`
+ * `offload [ufo {on|off}]`
+
+
+## Route Configuration
+
+After interface configuration is done, routes and rules are restored from a
+file named `routes` in the same configuration path.
+
+The file may contain lines starting with `route` or `rule`. Everything that
+follows is passed on to `ip route add` or `ip rule add` respectively.
+
+
+## Net Filter Tables
+
+
+An additional service is provided that restores the nft rule set from
+`/etc/nftables.rules`.