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 With caution! Installing some of the nosh packages provided here can profoundly change the way your system bootstraps and runs services.
  10
  11 Furthermore, the packages have so far only been tested on virtual machines with bare minimum installs of early 2017 Archlinux releases, where they *do* work for the most part but tailoring to your system will be necessary.
  12
  13 **N.B.: Automatic network configuration currently does not work with Archlinux, network interfaces may have to be brought up and configured manually.**
  14
  15 *Caveat emptor.*
  16
  17 ### The packages
  18
  19 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.
  20
  21 #### Dependencies
  22
  23 The make dependencies are the following and require [AUR](https://wiki.archlinux.org/index.php/Aur) access to be set up:
  24
  25 * [pax](https://aur.archlinux.org/packages/pax/) (AUR)
  26 * [redo-jdebp](https://aur.archlinux.org/packages/redo-jdebp/) (AUR)
  27 * [libtinfo](https://aur.archlinux.org/packages/libtinfo/) (AUR)
  28 * [xmlto](https://www.archlinux.org/packages/extra/x86_64/xmlto/) (Extra)
  29 * [docbook-xml](https://www.archlinux.org/packages/extra/any/docbook-xml/) (Extra)
  30 * [docbook-xsl](https://www.archlinux.org/packages/extra/any/docbook-xsl/) (Extra)
  31
  32 For package building in general, ensure the [base-devel](https://www.archlinux.org/groups/x86_64/base-devel/) package is installed.
  33
  34 #### Build the packages
  35
  36 Put the files in a directory and run:
  37
  38     $ makepkg
  39
  40 You can then install the generated packages with:
  41
  42     $ pacman -U <package-name>
  43
  44 ### Running nosh
  45
  46 Read the [timorous admin's installation how-to](https://jdebp.eu/Softwares/nosh/timorous-admin-installation-how-to.html).
  47
  48 The following describes the two expected common setups. Both assume you are running a default systemd-managed install.
  49
  50 #### nosh service manager only: nosh-run-via-systemd
  51
  52 The current default system and service manager for Archlinux is [systemd](https://wiki.archlinux.org/index.php/Systemd).
  53
  54 It is possible to run nosh as a service manager alongside systemd.
  55
  56 The following packages are necessary:
  57
  58 * nosh-common
  59 * nosh-exec
  60 * nosh-service-management
  61 * nosh-terminal-management
  62 * nosh-bundles
  63 * nosh-run-via-systemd
  64 * nosh-run-debian-server-base
  65
  66 Due to Archlinux's default preset *disable* policy (/usr/lib/systemd/system-preset/99-default.preset), you need to enable the following unit:
  67
  68     # systemctl enable service-manager.socket
  69
  70 Then you should enable one or both of:
  71
  72 * system-control-normal.service
  73 * service-manager-svscan.path
  74
  75 `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.
  76
  77 `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).
  78
  79 It's probably simpler to stick to just one of these methods.
  80
  81 Creating preset files for these units will also ensure their enabled/disabled status in case of package upgrades.
  82
  83 #### nosh system and service manager: nosh-run-system-manager
  84
  85 For a fully nosh-managed system i.e. nosh running as the init process and service manager, install the following packages:
  86
  87 * nosh-common
  88 * nosh-exec
  89 * nosh-execline-shims
  90 * nosh-service-management
  91 * nosh-terminal-management
  92 * nosh-bundles
  93 * nosh-run-system-manager
  94 * nosh-run-udev
  95 * nosh-run-kernel-vt
  96 * nosh-run-debian-server-base
  97 * nosh-run-local-syslog
  98 * nosh-run-klogd
  99
 100 ##### udev
 101
 102 The above installation assumes udev is the device manager, which is provided by the [systemd](https://www.archlinux.org/packages/core/x86_64/systemd/) package on Archlinux. However, using that package's `systemd-udevd` and `udevadm` commands with nosh has proven unsuccessful. If you know of any way to make it work, let me know.
 103
 104 Instead we will detail the installation of [eudev](https://aur.archlinux.org/packages/eudev/), [libeudev](https://aur.archlinux.org/packages/libeudev/), [eudev-systemd](https://aur.archlinux.org/packages/eudev-systemd/) and [libeudev-systemd](https://aur.archlinux.org/packages/libeudev-systemd/) (available from the AUR) which should provide a drop-in replacement for systemd/udev.
 105
 106 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.
 107
 108 1. Install libeudev
 109
 110     This conflicts with the libsystemd package, you should remove it but it will almost certainly be a dependency for other packages on your system so run:
 111
 112         # pacman -dd -S libeudev
 113
 114     The `-dd` (or `--nodeps`) repeated option skips dependency checking. You will be providing replacements for these dependencies.
 115
 116     It might also fail to install due to the following pre-existing files: `/usr/include/libudev.h` and `/usr/lib/pkgconfig/libudev.pc`. Delete these manually.
 117
 118 2. Install libeudev-systemd
 119
 120     This will provide the `libsystemd.so` libraries.
 121
 122 3. Install eudev
 123
 124     This conflicts with the systemd package and, again, will doubtless bring up many dependency warnings so run:
 125
 126         # pacman -dd -S eudev
 127
 128 4. Install eudev-systemd
 129
 130     This will provide some shim systemd binaries and libraries.
 131
 132
 133 ##### virtual terminals
 134
 135 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`.
 136
 137 The `nosh-execline-shims` package is necessary if you do not have [execline](https://skarnet.org/software/execline/) available.
 138
 139 ##### base
 140
 141 `nosh-run-debian-server-base` has currently not been renamed...
 142
 143 It provides essential presets for booting your system. A more featureful `nosh-run-debian-desktop-base` is also available.
 144
 145 ##### shims
 146
 147 Various shim packages exist to provide the following:
 148
 149 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...
 150
 151 2. Utilities which may be provided by other packages, e.g. nosh-execline-shims, nosh-ucspi-tcp-shims, nosh-kbd-shims...
 152
 153 ##### troubleshooting
 154
 155 [https://jdebp.eu/Softwares/nosh/guide/troubleshooting.html](https://jdebp.eu/Softwares/nosh/guide/troubleshooting.html)
 156
 157 The link above may come in useful.
 158
 159 ## Some nosh guidelines
 160
 161 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.
 162
 163 The nosh toolset follows general [daemontools design](https://jdebp.eu/FGA/daemontools-family.html) which includes:
 164
 165 * using the filesystem as database and API: the system can be inspected and modified using standard filesystem commands
 166 * logging as an ordinary --"first-class citizen"-- service
 167 * chain-loading of simple utilities to build a controlled final running state
 168 * composability: utilities from other toolsets in this family can be used in conjunction with nosh
 169
 170 To these features nosh [adds](https://jdebp.eu/Softwares/nosh/guide/new-interfaces.html):
 171
 172 * explicit separation of *service* and *system* management
 173 * terminal management
 174 * service ordering and interdependency through "service bundles" which allows for system "targets" similar to systemd
 175 * restart scripts
 176
 177 For a general presentation you may read the following:
 178
 179 [https://jdebp.eu/Softwares/nosh/guide/introduction.html](https://jdebp.eu/Softwares/nosh/guide/introduction.html)
 180
 181
 182 ### Service bundles
 183
 184 A standard bundle will look something like this:
 185
 186     /var/sv $ tree kamailio
 187     kamailio
 188     ├── after
 189     │   ├── basic -> /etc/service-bundles/targets/basic
 190     │   └── log -> ../log
 191     ├── before
 192     │   └── shutdown -> /etc/service-bundles/targets/shutdown
 193     ├── conflicts
 194     ├── log -> ../cyclog@kamailio
 195     ├── required-by
 196     ├── service
 197     │   ├── env
 198     │   ├── restart
 199     │   ├── run
 200     │   ├── start
 201     │   └── stop
 202     ├── stopped-by
 203     │   └── shutdown -> /etc/service-bundles/targets/shutdown
 204     ├── supervise
 205     │   ├── control
 206     │   ├── lock
 207     │   ├── ok
 208     │   └── status
 209     ├── wanted-by
 210     │   └── server -> /etc/service-bundles/targets/server
 211     └── wants
 212         └── basic -> /etc/service-bundles/targets/basic
 213
 214 The `before` and `after` directories allow for linking to other service bundles to set *ordering constraints*.
 215
 216 The `conflicts`, `required-by`, `stopped-by`, `wanted-by` and `wants` directories allow for linking to other service bundles to set *dependency constraints*.
 217
 218 The `log` directory points to a logging service.
 219
 220 The `service` directory contains the scripts used to manage the service. `service/env` can be used to store configuration information.
 221
 222 The `supervise` directory contains the control/status API files.
 223
 224 ### system-control
 225
 226 [system-control](https://jdebp.eu/Softwares/nosh/guide/system-control.html) is the workhorse command for the system.
 227
 228 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.
 229
 230 ### Converting systemd unit files
 231
 232 `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.
 233
 234 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.
 235
 236 In other words, one can benefit from existing systemd unit files through automatic conversion in many cases.
 237
 238 ## Repositories
 239
 240 This repository is publicly available at the following locations:
 241
 242 1. [https://framagit.org/taca/archnosh](https://framagit.org/taca/archnosh)
 243 2. [https://repo.or.cz/archnosh.git](https://repo.or.cz/archnosh.git)
 244 3. [https://github.com/tacatac/archnosh](https://github.com/tacatac/archnosh)
 245
 246 ## License
 247
 248 These packaging configuration files are distributed under the public domain [Unlicense](https://unlicense.org/), see the UNLICENSE file provided.
 249
 250 The nosh software, however, is distributed under BSD/BSD-compatible licensing.