Wee, sleekit, cow'rin, tim'rous beastie,
O, what a nosh'n's o' thy BSD!
Some people jump right in with nosh, download and compile the source package, and away they go. This is for the less adventuresome system administrator.
The first order of business is to download and to read the Nosh Guide. This is at the top of the FreeBSD and Debian Linux packages download pages for a reason. It contains explanation of some of the concepts involved in nosh, some of which you will be familiar with and some of which are new; explanations of the anatomy of services; explanations of how nosh relates to and imports from existing subsystems; details of the startup and shutdown processes; and explanations of terminal management and log management.
It's a set of HTML pages that you can open up in whatever HTML viewer you choose.
It's packaged up to be present locally, on your filesystem, on the basis that the times when you are likely to need it quickly and easily to hand are the times when you probably don't have working Internet/LAN access.
/usr/local/share/doc is a conventional respository for all sorts of documentation that you might not have known was there, by the way.
The Guide has the various command manuals in HTML form.
These are also available via the ordinary man command, although the DocBook XML conversion tools available for Linux and FreeBSD/TrueOS mean that some of the formatting is lost when viewed via man.
The man pages aren't packaged with the Guide; they are packaged with the binaries alongside the commands that they describe.
The command manuals are quite detailed. For examples:
The system-control manual describes service bundles, the nature of jobs, and the various special service bundles that act as system targets.
The service-manager manual describes supervise/ and service/ subdirectories.
The system-manager manual describes system initialization/shutdown and system state management.
The shutdown manual describes various necessary differences from older shutdown commands.
For FreeBSD/TrueOS and Debian Linux installation is a matter of installing the relevant binary, bundles, and run packages in the desired configuratoin; as almost everything necessary to produce a fully nosh-managed system is now available pre-packaged. In older versions of nosh, there were things that one had to do onesself by hand. As explained on the Roadmap, there's just one of those left to make into a package.
On Debian Linux, one uses the aptitude or apt-get command.
The examples that follow assume that you've stuck the packages into a Debian package repository somewhere and pointed /etc/apt/sources.list at it.
(Note that you can use file: URLs as APT sources.)
root ~ #aptitude install nosh-exec nosh-service-management nosh-terminal-management nosh-systemv-shims
On FreeBSD/TrueOS one can use the similar pkg command.
Note that (for FreeBSD 9 and 10.0 in particular) the packages require up-to-date versions of the pkg command, because they use the newer style of package manifests.
So make pkg update itself beforehand.
The examples that follow, for exposition purposes, show the route of not having the packages stored in a FreeBSD/TrueOS package repository.
root ~ #pkg install nosh-exec nosh-service-management nosh-terminal-management nosh-systemv-shims
The aforementioned are what you will likely want.
If you don't have systemd but want a systemctl command, you might choose to add the systemd shims package.
Likewise you might choose to add the upstart shims package and gain an initctl command; or the OpenBSD shims package and gain an rcctl command.
Or, alternatively, you might not want System 5/BSD compatibility shims (perhaps because they conflict with existing commands from other packages) and just do everything the native nosh way.
Similarly, but less likely, you might only want the chain loading tools and nosh interpreter for use with some other toolset, and might not desire the service or terminal management.
Installing the binaries packages does nothing to reconfigure your system. It simply adds some extra commands and documentation. Installing the collection of service bundles is where things begin to happen.
root ~ #aptitude install nosh-bundles
root ~ #pkg add ./nosh-bundles*.txz
As part of its (re-)installation process the bundles package creates dedicated user accounts for various logging services, and for various main services whose own packaging does not create the right user accounts. It also creates and sets the ACLs on the log directories that those logging services write. Everything is disabled at first, because the bundles package takes no action to enable/disable services.
Installing the bundles has created all of the service bundle directories, users, and ancillaries such as log directories.
It hasn't actually changed what your system does at bootstrap, or set up symbolic links for a few basic services and whatever additional services you've decided to preset.
That's done by installing some of the pre-supplied -run packages.
The most necessary of these are the packages that enable certain basic services without which your system will probably fail to bootstrap.
These -run-something-base packages come in "desktop" and "server" flavours, the latter being a subset of the former.
Choose which one is appropriate; you should only use one.
root ~ #aptitude install nosh-run-debian-server-base
root ~ #pkg add ./nosh-run-freebsd-server-base*.txz
root ~ #pkg add ./nosh-run-trueos-desktop-base*.txz
Other -run packages do much the same as these do, but for non-basic services.
They contain *.preset files, and their installation and deinstallation scripts respectively preset and disable some services.
You can create more packages to do the same, for services not covered by any of these -run packages.
You can preset services directly, too; by creating *.preset files detailing which of the pre-supplied service bundles you want enabled.
If you want an exim4 SMTP Relay service enabled, for example, edit /etc/system-control/presets/20-exim.preset, add the lines enable exim4-smtp-relay.service and enable cyclog@exim4-smtp-relay.service, and then run:
root ~ #system-control preset {cyclog@,}exim4-smtp-relay
Note that because your preset is in /etc/system-control/presets/ (a directory intended for presets supplied by the system administrator) it overrides presets that are in the (other) directories that are intended for presets supplied by the operating system or by packages.
Also note that presetting a service does not start/stop the service to match its new enable/disable state.
That is done at next bootstrap (of course) and can also be done manually in a running system with:
root ~ #system-control reset {cyclog@,}exim4-smtp-relay
You can of course manually enable services later without presets, just as you can manually start services after bootstrap without enabling them to be auto-started.
But be aware the installation and upgrade process for the various -run packages (re-)applies the presets (for the services covered by the package) every time, overriding any manual enabling that you have done.
You have to enable packages if you want them to be started automatically after a reboot.
Similarly, you have to preset packages if you want them to be enabled automatically after an upgrade of the relevant -run package.
This is not to say that you'll be upgrading/reinstalling the software often. It's simply a potential problem to remember to avoid, by setting up presets for what you want, before you do upgrade/reinstall.
As mentioned, the -run packages simply pre-package what was just being explained: installing a preset file that enables some of the service bundles and then applying the presets (and starting the enabled services).
They each cover various groups of services, and they are used in various combinations.
There are descriptions and notes on the download pages right next to the package download hyperlinks, which it is important to read and to digest.
For starters, you'll be mainly interested in two combinations.
The nosh system by design splits up service management and system management.
One can run a fully nosh managed system, with the nosh system-manager handling system management, or one can run the nosh service-manager under another system management subsystem.
You can experiment with nosh service management running under previous system management prior to trying out a wholly nosh-managed system.
Running nosh service management under systemd is pre-packaged for (only) Debian Linux and Arch Linux.
Running it under Mewburn rc is pre-packaged for (only) FreeBSD/TrueOS.
Running it under OpenBSD rc is pre-packaged for (only) OpenBSD.
root ~ #aptitude install nosh-run-via-systemd
root ~ #pkg add ./nosh-run-via-mewburn-rc*.txz
root ~ #pkg_add ./nosh-run-via-openbsd-rc*.txz
You could in theory run it (again Linux-only) under upstart, under System 5 rc, or even under System 5 init directly.
None of these are supplied pre-packaged, though, and in all honesty they probably won't be as by far the more probable use cases are either running nosh under systemd/Mewburn/OpenBSD rc or running a wholly nosh-managed system.
/etc/inittab is a thing of the past and it is a waste of time and effort packaging up ways to run nosh service management from it.
This is the line beyond which you'll have to do things for yourself if you want them.
Of course, if you enable a service in one remember to disable it (and possibly mask it, too) in the other.
This is somewhat tricky on FreeBSD/TrueOS, as /etc/rc.conf{,.local} is automatically imported into native nosh service management configuration information.
Life is a bit simpler on Linux, where there is no /etc/rc.conf{,.local}.
root ~ #system-control enable gnucron cyclog@gnucron ; systemctl disable cron.service
Likewise remember for manual starts and stops to ensure that only one service is running at a time.
root ~ #system-control start gnucron cyclog@gnucron ; systemctl stop cron.service
root ~ #system-control start gnucron cyclog@gnucron ; /usr/sbin/service cron stop
If you get confused with these similarly-named commands, remember that there are compatibility shims supplying alternative names. So you if you really really needed to you could use …
… the upstart compatibility shim:
root ~ #initctl enable gnucron cyclog@gnucron ; systemctl disable cron.service
… the Solaris SMF compatibility shim:
root ~ #svcadm enable gnucron cyclog@gnucron ; systemctl disable cron.service
… the OpenBSD compatibility shim (which isn't a general purpose alternative, note):
root ~ #rcctl enable gnucron cyclog@gnucron ; systemctl disable cron.service
Becoming familiar with system-control as the name, rather than learning those shims as a new habit, is definitely preferable, though.
What you will not get from running under previous system management are experience of external format import and nosh management of things like volume mounts, filesystem checks, and terminals. For that, one installs a fully nosh managed system.
root ~ #aptitude install nosh-run-system-manager nosh-run-local-syslog nosh-run-kernel-vt nosh-run-udev
root ~ #pkg add ./nosh-run-system-manager*.txz ./nosh-run-local-syslog*.txz ./nosh-run-kernel-vt*.txz
One usually wants to import the external configuration into nosh-native form, as well. This will set up all sorts of things, from per-user service management subsystems for each individual (real) user account to instances of MySQL/MariaDB/OpenVPN/PC-BSD Warden services for any detected configurations of those softwares.
root ~ #redo -C /etc/system-control/convert/ all
Here come the important notes.
Important note #1: This changes the way that your system bootstraps. Check the Troubleshooting chapter of the Nosh Guide. Read your system boot loader doco and familiarize yourself with how you can bootstrap into emergency mode and into rescue mode (both of which nosh system management supports, albeit that the FreeBSD/TrueOS loader only supports the latter).
Important note #1a: is no longer the case in version 1.20.
Important note #1b: There's a bug that was fixed in version 1.20, causing system management to erroneously trigger filesystem mounts in emergency mode. This is a simple matter of an erroneous symbolic link creating an incorrect relationship. You can remove it directly if you like; the filesystem is the database, remember, and ordinary filesystem tools can be used to manage stuff.
root ~ #rm /etc/service-bundles/services/emergency-login@console/wants/basic
Important note #1c:
In extremis, the other system management system is still there, and accessible by interrupting the boot loader and switching init=/lib/systemd/systemd (on Debian Linux) or init_path=/sbin/init (on FreeBSD/TrueOS).
However, the ancillary System 5 compatibility tools for that system (service, poweroff, telinit, and so forth) will either be superseded or not present.
Important note #2:
Installing the nosh-run-system-manager package removes the nosh-run-via-systemd package.
Make sure that you don't do this from within a login session that is managed by the nosh service manager at the time.
Removing the nosh-run-via-systemd package disables and stops the systemd service that starts up the nosh service manager, causing every service spawned by the nosh service manager to be killed; so what happens if you do do the package management from within a nosh-service-manager-supervised login session is that systemd kills the login session partway through the package installation procedure that is running in that login session, leaving your system in a quite tangled state.
Do this from a systemd-supervised login session, or from the systemd rescue mode.
Important note #3:
Installing the nosh-run-system-manager package does not remove the nosh-run-via-netbsd-rc package.
Less important is that the syslog system isn't strictly mandatory; but you'll probably have a lot of badly written programs that are clients of a local syslog server.
Similarly, if you choose vdev, busybox mdev, or suckless mdev (all three of which you can choose, on Linux) over systemd's udev, you're on your own with configuring all of the device rules.
The authors of those systems don't (yet) package up and install handy pre-written rulesets that will get you a working system right off the bat.
mdev at least comes with such a ruleset, but it doesn't install it.
FreeBSD/TrueOS always uses the operating-system-supplied devd, of course.
There's a wealth of information in the manuals and in the Nosh Guide. The timorous admin will of course read them thoroughly. So here are only a few tips that will start you looking at things.
Where is the vdev service?
root ~ #system-control find vdev
What does the qmail-smtp-relay service do?
root ~ #system-control cat qmail-smtp-relay
What's the state of the gnucron service?
root ~ #system-control status gnucron
How was my /etc/ttys file understood?
root ~ #cat /etc/system-control/convert/terminal-services
How was my /etc/fstab file understood?
root ~ #cat /etc/system-control/convert/volumes
But I changed them‽
root ~ #cd /etc/system-control/convert/ && redo all
I want that Linux Alt-Up thing mentioned in the doco!
root ~ #ln -s rescue /etc/service-bundles/targets/kbrequest
How is the tinydns service configured?
root ~ #rcctl get tinydns root ~ #system-control print-service-env tinydns