View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0006424 | unreal | documentation | public | 2024-06-09 14:08 | 2025-10-29 13:58 |
| Reporter | hnj | Assigned To | syzop | ||
| Priority | normal | Severity | tweak | Reproducibility | N/A |
| Status | resolved | Resolution | fixed | ||
| Product Version | 6.1.5 | ||||
| Fixed in Version | 6.2.1 | ||||
| Summary | 0006424: improve documentation of the binary, primarily for use with process supervision suites | ||||
| Description | Please 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 Information | I 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 | ||||
| Tags | docs, documentation, ircd | ||||
| 3rd party modules | |||||
|
|
https://bugs.unrealircd.org/view.php?id=4361#c18404 seems related |
|
|
The unrealircd binary is not meant to be executed directly, we have the unrealircd script for that. So it is not meant to document all the options, that is on purpose. But you are right, for things like systemd it can be a good idea to call the binary directly with -F. I think we should just ship with a systemd unit and be done with this. I slightly changed the error to mention at least -F: ERROR: Incorrect command line argument encountered (if you are looking for foreground mode, it is -F). IMPORTANT: This is the unrealircd BINARY. End-users should NOT call this binary directly. Please run the SCRIPT instead: /home/syzop/unrealircd/unrealircd Server not started commit 82f21df20b1a3ff0a3455b89868603dd25228fdc (HEAD -> unreal60_dev, origin/unreal60_dev, origin/HEAD) Author: Bram Matthys <[email protected]> Date: Wed Oct 29 08:17:35 2025 +0100 Make unrealircd binary mention at least -F Reported by henk in https://bugs.unrealircd.org/view.php?id=6424 |
|
|
systemd unit files are now shipped and we actively try to avoid users doing ./unrealircd [start|stop|restart] if the thing is running through systemd already. Still needs docs but that can be done later. commit fea1d2ab8b3ba4cb9c5239a4c5d283e66aebaf96 (HEAD -> unreal60_dev, origin/unreal60_dev, origin/HEAD) Author: Bram Matthys <[email protected]> Date: Wed Oct 29 10:06:30 2025 +0100 Add two systemd unit files in extras/startup: Use extras/startup/unrealircd.service if you want a system-wide unit file, which is normally what people tend to use. The benefit of this is that it allows setting some security options. Use extras/startup/unrealircd_user.service if you want a user unit file. This works if you don't have root on the machine. commit 82417d0cd2efdb96b51d5806972a488b3548ecb7 Author: Bram Matthys <[email protected]> Date: Wed Oct 29 09:56:18 2025 +0100 Don't write PID file if running in foreground mode (-F) and error on ./unrealircd [start|stop|restart] commands if unrealircd is running but without a pid, which will be the case if running through systemd. The systemd example unit files will be in a future commit. Thanks! |
| 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 |
| 2025-10-29 08:19 | syzop | Note Added: 0023533 | |
| 2025-10-29 10:17 | syzop | Assigned To | => syzop |
| 2025-10-29 10:17 | syzop | Status | new => resolved |
| 2025-10-29 10:17 | syzop | Resolution | open => fixed |
| 2025-10-29 10:17 | syzop | Note Added: 0023534 | |
| 2025-10-29 13:58 | syzop | Fixed in Version | => 6.2.1 |
