View Issue Details

IDProjectCategoryView StatusLast Update
0006424unrealdocumentationpublic2024-09-25 13:07
Reporterhnj Assigned To 
PrioritynormalSeveritytweakReproducibilityN/A
Status newResolutionopen 
Product Version6.1.5 
Summary0006424: improve documentation of the binary, primarily for use with process supervision suites
DescriptionPlease create documentation of the actual unrealircd binary, in particular which option it takes.
I found that it takes -F to not fork into the background, which is likely the most important option to know about, but it would be good if any others it can take were documented as well.

-f might be relevant for distro packagers.
-C or -c seem also relevant for anyone else trying to automate deployment, config management and restarts, etc.

Background is explained in "Additional Information".
Additional InformationI am in the process of setting up unrealircd on two machines.
For the start I set it up to be started by a cronjob, as explained in the docs, as that seems to be the only documented way. As such, it also seems to be the recommended way and the only supported way.
I ran into a problem with this way of setting it up, though:
restarting one of the VMs caused the connections of both my services package (anope), the other IRCd, and all connected clients to be dropped instead of being cleanly closed. (anope actually didn’t even notice the connection had been lost and just continued as if nothing happened which is likely a bug in anope.)

AFAICT this likely happens because the init-system on linux starts and stops services and other things related to the system’s operation in a given order. I cannot explain this order in detail but the relevant part is that processes/services which are _not_ managed by it, just fall under "remaining processes" which are terminated (SIGTERM) and then killed (SIGKILL) at a very late stage in the shutdown process.
In particular it seems like "networking" is stopped _before_ these "remaining processes" are being terminated.
Since an unrealircd that has been started via cron and not via any service/process management system (such as systemd, sysvrc, openrc, etc.) counts as a "remaining process", it will be stopped _after_ networking has already been stopped, so it cannot cleanly close established connections.

Since this is suboptimal, I would prefer to start unrealircd using a proper service/process supervision suite.
To integrate unrealircd into such a software _properly_, it is best to use the daemon binary directly, instead of using the wrapper script. (I don’t really want to expand on this right now. In short: 0) having another shell script in between that provides no benefit is just more complexity and 1) the wrapper is usually designed to run the daemon in the background which is _not_ the right approach for these kinds of tools. I’m aware that the unrealircd binary also forks but there is -F … this is why I don’t want to expand on it. It gets complicated and I hope it’s not necessary to explain this in detail but if the concepts of daemontools-concept based process supervision suites are unknown, please let me know and I will link to more information. In short: they actually _supervise_ the process, not just start it, forget it, and check on it when requested using a PID which may or may not still belong to that process.)

There are a few such suites which prefer using the daemon binary directly, work much more reliably when set up this way, prevent race conditions, and so on, among others systemd, which has been adopted by most mainstream distros in the last few years, but also others which are popular mainly among puristic, minimalist, and/or embedded users and distros, like the aforementioned daemontools, runit, and s6, to name just a few.

Just one link with more information about these kinds of supervision suites: https://www.skarnet.org/software/s6/overview.html
Tagsdocs, documentation, ircd
3rd party modules

Activities

hnj

2024-06-09 14:10

reporter   ~0023215

https://bugs.unrealircd.org/view.php?id=4361#c18404 seems related

Issue History

Date Modified Username Field Change
2024-06-09 14:08 hnj New Issue
2024-06-09 14:08 hnj Tag Attached: docs
2024-06-09 14:08 hnj Tag Attached: documentation
2024-06-09 14:08 hnj Tag Attached: ircd
2024-06-09 14:10 hnj Note Added: 0023215
2024-09-25 13:07 syzop Severity major => tweak