README.md

   1 # Archnosh is nosh for Archlinux
   2
   3 This repository provides the build files necessary to integrate the [nosh](https://jdebp.eu/Softwares/nosh/) system and service manager with Archlinux package management.
   4
   5 The packaging here closely follows the [Debian packaging](https://jdebp.eu/Softwares/nosh/debian-binary-packages.html) provided by the author of nosh.
   6
   7 ## How do I use it?
   8
   9 ### The packages
  10
  11 This is a split-package PKGBUILD which will generate several packages, covering the toolset aswell as a service bundle collection which together can provide a complete working system.
  12
  13 #### Dependencies
  14
  15 The make dependencies are the following and require [AUR](https://wiki.archlinux.org/index.php/Aur) access to be set up:
  16
  17 * [pax](https://aur.archlinux.org/packages/pax/) (AUR)
  18 * [redo-jdebp](https://aur.archlinux.org/packages/redo-jdebp/) (AUR)
  19 * [libtinfo](https://aur.archlinux.org/packages/libtinfo/) (AUR)
  20 * [xmlto](https://www.archlinux.org/packages/extra/x86_64/xmlto/) (Extra)
  21 * [docbook-xml](https://www.archlinux.org/packages/extra/any/docbook-xml/) (Extra)
  22 * [docbook-xsl](https://www.archlinux.org/packages/extra/any/docbook-xsl/) (Extra)
  23
  24 For package building in general, ensure the [base-devel](https://www.archlinux.org/groups/x86_64/base-devel/) package is installed.
  25
  26 #### Build the packages
  27
  28 Put the files in a directory and run:
  29
  30     $ makepkg
  31
  32 You can then install the generated packages with:
  33
  34     $ pacman -U <package-name>
  35
  36 ### Running nosh
  37
  38 Read the [timorous admin's installation how-to](https://jdebp.eu/Softwares/nosh/timorous-admin-installation-how-to.html).
  39
  40 The following describes the two expected common setups.
  41
  42 #### nosh service manager only: nosh-run-via-systemd
  43
  44 The current default system and service manager for Archlinux is [systemd](https://wiki.archlinux.org/index.php/Systemd).
  45
  46 It is possible to run nosh as a service manager alongside systemd.
  47
  48 The following packages are necessary:
  49
  50 * nosh-common
  51 * nosh-exec
  52 * nosh-service-management
  53 * nosh-terminal-management
  54 * nosh-bundles
  55 * nosh-run-via-systemd
  56 * nosh-run-debian-server-base
  57
  58 Due to Archlinux's default preset *disable* policy (/usr/lib/systemd/system-preset/99-default.preset), you need to enable the following unit:
  59
  60     # systemctl enable service-manager.socket
  61
  62 Then you should enable one or both of:
  63
  64 * system-control-normal.service
  65 * service-manager-svscan.path
  66
  67 `system-control-normal.service` uses nosh targets to bring up enabled services. Simply run `system-control enable <service>` and `systemctl disable <service>` for its equivalent in order to switch management of the service over to nosh.
  68
  69 `service-manager-svscan.path` will scan and bring up any service bundle you place in the /service directory (which you will have to create), effectively enabling it. This is the more typical daemontools [approach](https://cr.yp.to/daemontools/faq/create.html#why).
  70
  71 It's probably simpler to stick to just one of these methods.
  72
  73 Creating preset files for these units will also ensure their enabled/disabled status in case of package upgrades.
  74
  75 #### nosh system and service manager: nosh-run-system-manager
  76
  77 For a fully nosh-managed system i.e. nosh running as the init process and service manager, install the following packages:
  78
  79 * nosh-common
  80 * nosh-exec
  81 * nosh-execline-shims
  82 * nosh-service-management
  83 * nosh-terminal-management
  84 * nosh-bundles
  85 * nosh-run-system-manager
  86 * nosh-run-udev
  87 * nosh-run-kernel-vt
  88 * nosh-run-debian-server-base
  89 * nosh-run-local-syslog
  90 * nosh-run-klogd
  91
  92 ##### udev
  93
  94 The above installation assumes udev is the device manager, which requires the [systemd](https://www.archlinux.org/packages/core/x86_64/systemd/) package to be installed on Archlinux.
  95
  96 In order to allow this, archnosh packages do not conflict, for the most part, with the systemd packages. Alternative device manager run packages are provided (vdev, busybox-mdev, suckless-mdev) but you will have to account for Archlinux systemd/udev integration with various other system packages.
  97
  98 ##### virtual terminals
  99
 100 Rather than kernel virtual terminals, [user-space virtual terminals](https://jdebp.eu/Softwares/nosh/user-vt-screenshots.html) may be used by installing `nosh-run-user-vt`.
 101
 102 The `nosh-execline-shims` package is necessary if you do not have [execline](https://skarnet.org/software/execline/) available.
 103
 104 ##### base
 105
 106 `nosh-run-debian-server-base` has currently not been renamed...
 107
 108 It provides essential presets for booting your system. A more featureful `nosh-run-debian-desktop-base` is also available.
 109
 110 ##### shims
 111
 112 Various shim packages exist to provide the following:
 113
 114 1. Commands from other service or system managers that will invoke the corresponding nosh management actions, e.g. nosh-debian-shims, nosh-systemd-shims, nosh-upstart-shims...
 115
 116 2. Utilities which may be provided by other packages, e.g. nosh-execline-shims, nosh-ucspi-tcp-shims, nosh-kbd-shims...
 117
 118 ##### troubleshooting
 119
 120 https://jdebp.eu/Softwares/nosh/guide/troubleshooting.html
 121
 122 The link above may come in useful.
 123
 124 ## Some nosh guidelines
 125
 126 The online [nosh guide](https://jdebp.eu/Softwares/nosh/guide/), also available in the `nosh-guide` package, and command [manpages](https://jdebp.eu/Softwares/nosh/guide/commands.html) provide comprehensive documentation.
 127
 128 The nosh toolset follows general [daemontools design](https://jdebp.eu/FGA/daemontools-family.html) which includes:
 129
 130 * using the filesystem as database and API: the system can be inspected and modified using standard filesystem commands
 131 * logging as an ordinary --"first-class citizen"-- service
 132 * chain-loading of simple utilities to build a controlled final running state
 133 * composability: utilities from other toolsets in this family can be used in conjunction with nosh
 134
 135 To these features nosh [adds](https://jdebp.eu/Softwares/nosh/guide/new-interfaces.html):
 136
 137 * explicit separation of *service* and *system* management
 138 * terminal management
 139 * service ordering and interdependency through "service bundles" which allows for system "targets" similar to systemd
 140 * restart scripts
 141
 142 For a general presentation you may read the following:
 143
 144 https://jdebp.eu/Softwares/nosh/guide/introduction.html
 145
 146 ### Service bundles
 147
 148 A standard bundle will look something like this:
 149
 150     /var/sv $ tree kamailio
 151     kamailio
 152     ├── after
 153     │   ├── basic -> /etc/service-bundles/targets/basic
 154     │   └── log -> ../log
 155     ├── before
 156     │   └── shutdown -> /etc/service-bundles/targets/shutdown
 157     ├── conflicts
 158     ├── log -> ../cyclog@kamailio
 159     ├── required-by
 160     ├── service
 161     │   ├── env
 162     │   ├── restart
 163     │   ├── run
 164     │   ├── start
 165     │   └── stop
 166     ├── stopped-by
 167     │   └── shutdown -> /etc/service-bundles/targets/shutdown
 168     ├── supervise
 169     │   ├── control
 170     │   ├── lock
 171     │   ├── ok
 172     │   └── status
 173     ├── wanted-by
 174     │   └── server -> /etc/service-bundles/targets/server
 175     └── wants
 176         └── basic -> /etc/service-bundles/targets/basic
 177
 178 The `before` and `after` directories allow for linking to other service bundles to set *ordering constraints*.
 179
 180 The `conflicts`, `required-by`, `stopped-by`, `wanted-by` and `wants` directories allow for linking to other service bundles to set *dependency constraints*.
 181
 182 The `log` directory points to a logging service.
 183
 184 The `service` directory contains the scripts used to manage the service. `service/env` can be used to store configuration information.
 185
 186 The `supervise` directory contains the control/status API files.
 187
 188 ### system-control
 189
 190 [system-control](https://jdebp.eu/Softwares/nosh/guide/system-control.html) is the workhorse command for the system.
 191
 192 It provides general service management (start/stop, enable/disable etc.) aswell as system management (reboot, poweroff etc.) and various other specialised commands for e.g. converting systemd-style unit files to service bundles.
 193
 194 ### Converting systemd unit files
 195
 196 `system-control convert-systemd-units <unit-file>` supports conversion for [various types](https://jdebp.eu/Softwares/nosh/guide/converting-systemd-units.html) of systemd unit files to service bundles.
 197
 198 It also understands extended syntax to express service-bundle specific functionality in a systemd-like unit file, which can be used for easy distribution for example.
 199
 200 In other words, one can benefit from existing systemd unit files through automatic conversion in many cases.
 201
 202 ## License
 203
 204 These packaging configuration files are distributed under the public domain [Unlicense](https://unlicense.org/), see the UNLICENSE file provided.
 205
 206 The nosh software, however, is distributed under BSD/BSD-compatible licensing.