-
Notifications
You must be signed in to change notification settings - Fork 1
/
daemon.c
5287 lines (3946 loc) · 143 KB
/
daemon.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* daemon - https://libslack.org/daemon
*
* Copyright (C) 1999-2004, 2010, 2020-2023 raf <[email protected]>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses/>.
*
* 20230824 raf <[email protected]>
*/
/*
=head1 NAME
I<daemon> - turns other processes into daemons
=head1 SYNOPSIS
usage: daemon [options] [--] [cmd arg...]
options:
-h, --help - Print a help message then exit
-V, --version - Print a version message then exit
-v, --verbose[=level] - Set the verbosity level
-d, --debug[=level] - Set the debugging level
-C, --config=path - Specify the system configuration file
-N, --noconfig - Bypass the system configuration file
-n, --name=name - Guarantee a single named instance
-X, --command="cmd" - Specify the client command as an option
-P, --pidfiles=/dir - Override standard pidfile location
-F, --pidfile=/path - Override standard pidfile name and location
-u, --user=user[:[group]] - Run the client as user[:group]
-R, --chroot=path - Run the client with path as root
-D, --chdir=path - Run the client in directory path
-m, --umask=umask - Run the client with the given umask
-e, --env="var=val" - Set a client environment variable
-i, --inherit - Inherit environment variables
-U, --unsafe - Allow execution of unsafe executable
-S, --safe - Disallow execution of unsafe executable
-c, --core - Allow core file generation
--nocore - Disallow core file generation (default)
-r, --respawn - Respawn the client when it terminates
-a, --acceptable=# - Minimum acceptable client duration (seconds)
-A, --attempts=# - Respawn # times on error before delay
-L, --delay=# - Delay between respawn attempt bursts (seconds)
-M, --limit=# - Maximum number of respawn attempt bursts
--idiot - Idiot mode (trust root with the above)
-f, --foreground - Run the client in the foreground
-p, --pty[=noecho] - Allocate a pseudo terminal for the client
-B, --bind - Stop when the user's last logind session ends
-l, --errlog=spec - Send daemon's error output to syslog or file
-b, --dbglog=spec - Send daemon's debug output to syslog or file
-o, --output=spec - Send client's output to syslog or file
-O, --stdout=spec - Send client's stdout to syslog or file
-E, --stderr=spec - Send client's stderr to syslog or file
--ignore-eof - After SIGCHLD ignore any client output
--read-eof - After SIGCHLD read any client output (default)
--running - Check if a named daemon is running
--restart - Restart a named daemon client
--stop - Terminate a named daemon process
--signal=signame - Send a signal to a named daemon
--list - Print a list of named daemons
=head1 DESCRIPTION
I<daemon(1)> turns other processes into daemons. There are many tasks that
need to be performed to correctly set up a daemon process. This can be
tedious. I<daemon> performs these tasks for other processes.
The preparatory tasks that I<daemon> performs for other processes are:
=over 4
=item *
First, revoke any setuid or setgid privileges that I<daemon> may have been
installed with (by system administrators who laugh in the face of danger).
=item *
Process command line options.
=item *
Change the root directory if the C<--chroot> option was supplied.
=item *
Change the process uid and gid if the C<--user> option was supplied. Only
I<root> can use this option. Note that the uid of I<daemon> itself is
changed, rather than just changing the uid of the client process.
=item *
Read the system configuration file(s) (C</etc/daemon.conf> and
C</etc/daemon.conf.d/*> by default, or specified by the C<--config> option),
unless the C<--noconfig> option was supplied. Then read the user's personal
configuration file(s) (C<~/.daemonrc> and C<~/.daemonrc.d/*>), if any.
Generic options that apply to all daemons are processed first, then options
that are specific to the daemon with the given name. B<Note: The root
directory and the user must be set before access to the configuration
file(s) can be attempted, so neither the C<--chroot> nor C<--user> options
may appear in the configuration file.>
On I<BSD> systems (except I<macOS>), the system configuration file(s) are
C</usr/local/etc/daemon.conf> and C</usr/local/etc/daemon.conf.d/*> by
default.
On I<macOS>, when installed via I<macports>, the system configuration
file(s) are C</opt/local/etc/daemon.conf> and
C</opt/local/etc/daemon.conf.d/*>.
=item *
Disable core file generation to prevent leaking potentially sensitive
information in daemons that are run by I<root> (unless the C<--core> option
was supplied).
=item *
Become a daemon process:
=over 4
=item *
If I<daemon> was not invoked by I<init(8)> (i.e. parent process id 1) or
I<inetd(8)> (i.e. C<stdin> is a socket):
=over 4
=item *
Ignore C<SIGHUP> signals in case the current process session leader
terminates while attached to a controlling terminal, causing us to
receive a C<SIGHUP> signal before we start our own process session below.
This can happen when I<daemon> was invoked interactively via the shell
builtin C<exec>. When this initial process terminates below, the terminal
emulator that invoked the shell also terminates, so I<daemon> need to
protect itself from that.
=item *
Background the process to lose process group leadership.
=item *
Start a new process session.
=item *
Background the process again to lose process session leadership. Under
I<SVR4>, this prevents the process from ever gaining a controlling terminal.
This is only necessary under I<SVR4>, but is always done for simplicity.
Note that ignoring C<SIGHUP> signals earlier means that when the newly
created process session leader terminates, then even if it has a controlling
terminal open, the newly backgrounded process won't receive the
corresponding C<SIGHUP> signal that is sent to all processes in the process
session's foreground process group, because it inherited signal dispositions
from the initial process.
=back
=item *
Change the current directory to the root directory so as not to hamper
umounts.
=item *
Clear the I<umask> to enable explicit file creation modes.
=item *
Close all open file descriptors. If I<daemon> was invoked by I<inetd(8)>,
C<stdin>, C<stdout> and C<stderr> are left open, because they are open to a
socket.
=item *
Open C<stdin>, C<stdout> and C<stderr> to C</dev/null>, in case something
requires them to be open. Of course, this is not done if I<daemon> was
invoked by I<inetd(8)>.
=item *
If the C<--name> option was supplied, create and lock a file containing the
process id of the I<daemon> process. The presence of this locked file
prevents two instances of a daemon with the same name from running at the
same time. The default location of the pidfile is C</var/run> for I<root>
(C</etc> on I<Solaris>, C</opt/local/var/run> on I<macOS> when installed via
I<macports>), and C</tmp> for normal users. If the C<--pidfiles> option was
supplied, its argument specifies the directory in which the pidfile will be
placed. If the C<--pidfile> option was supplied, its argument specifies the
name of the pidfile and the directory in which it will be placed.
=back
=item *
If the C<--umask> option was supplied, set the I<umask> to its argument,
which must be a valid three-digit octal mode. Otherwise, set the umask to
C<022>, to prevent clients from accidentally creating group- or
world-writable files.
=item *
Set the current directory if the C<--chdir> option was supplied.
=item *
Spawn the client command and wait for it to terminate. The client command
can be specified as command line arguments, or as the argument of the
C<--command> option. If both the C<--command> option and command line
arguments are present, the client command is the result of appending the
command line arguments to the argument of the C<--command> option.
=item *
If the C<--output>, C<--stdout> and/or C<--stderr> options were supplied,
the client's standard output and/or standard error are captured by
I<daemon>, and are sent to the respective I<syslog> destinations.
=item *
When the client terminates, I<daemon> respawns it if the C<--respawn> option
was supplied. If the client ran for less than C<300> seconds (or the value
of the C<--acceptable> option), then I<daemon> sees this as a failure. It
will attempt to restart the client up to five times (or the value of the
C<--attempts> option), before waiting for C<300> seconds (or the value of
the C<--delay> option). This gives the system administrator the chance to
correct whatever is preventing the client from running successfully without
overloading system resources. If the C<--limit> option was supplied,
I<daemon> terminates after the specified number of respawn attempt bursts.
The default is zero, which means never give up, never surrender.
When the client terminates, and the C<--respawn> option wasn't supplied,
I<daemon> terminates as well.
=item *
If I<daemon> receives a C<SIGTERM> signal (e.g. from a separate invocation
of I<daemon> with the C<--stop> option), it propagates the signal to the
client and then terminates.
=item *
If I<daemon> receives a C<SIGUSR1> signal (from a separate invocation of
I<daemon> with the C<--restart> option), it sends a C<SIGTERM> signal to the
client. If it was started with the C<--respawn> option, the client process
will be restarted after it is terminated by the C<SIGTERM> signal.
=item *
If the C<--foreground> option was supplied, the client process is run as a
foreground process, and is not turned into a daemon at all. If I<daemon> is
connected to a terminal, then the client process will also be connected to
it. If I<daemon> is not connected to a terminal, but the client needs to be
connected to a terminal, use the C<--pty> option.
=back
=head1 OPTIONS
=over 4
=item C<-h>, C<--help>
Display a help message and exit.
=item C<-V>, C<--version>
Display a version message and exit.
=item C<-v>I<[level]>, C<--verbose>I<[=level]>
Set the message verbosity level to I<level> (or 1 if I<level> is not
supplied). This only effects the C<--running> and C<--list> options.
=item C<-d>I<[level]>, C<--debug>I<[=level]>
Set the debug message level to I<level> (or 1 if I<level> is not supplied).
Level 1 traces high-level function calls. Level 2 traces lower-level
function calls and shows configuration information. Level 3 adds environment
variables. Level 9 adds every return value from I<select(2)>. Debug messages
are sent to the destination specified by the C<--dbglog> option (by default,
the I<syslog(3)> facility, C<daemon.debug>).
=item C<-C> I<path>, C<--config=>I<path>
Specify the system configuration file to use. By default,
C</etc/daemon.conf> is the system configuration file, if it exists and is
not group- or world-writable, and does not exist in a group- or
world-writable directory. The configuration file lets you predefine options
that apply to all clients, and to specifically named clients.
As well as the system configuration file, additional configuration files
will be read from the directory whose path matches the system configuration
file with C<".d"> appended to it (e.g. C</etc/daemon.conf.d>). Any file in
that directory whose name starts with a dot character (C<".">) is ignored.
The same checks as described above apply to these files as well.
On I<BSD> systems (except I<macOS>), the system configuration file(s) are
C</usr/local/etc/daemon.conf> and C</usr/local/etc/daemon.conf.d/*> by
default.
On I<macOS>, when installed via I<macports>, the system configuration
file(s) are C</opt/local/etc/daemon.conf> and
C</opt/local/etc/daemon.conf.d/*>.
=item C<-N>, C<--noconfig>
Bypass the system configuration files, C</etc/daemon.conf> and
C</etc/daemon.conf.d/*>. Only the user's C<~/.daemonrc> and
C<~/.daemonrc.d/*> configuration files will be read (if they exist).
=item C<-n> I<name>, C<--name=>I<name>
Create and lock a pidfile (I<name>C<.pid>), ensuring that only one daemon
with the given I<name> is active at the same time. The standard location of
the pidfile is C</var/run> for root (C</etc> on I<Solaris>,
C</opt/local/var/run> on I<macOS> when installed via I<macports>), and
C</tmp> for normal users. This location can be overridden with the
I<--pidfiles> option.
The name may only consist of the following characters:
-._abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
While a named daemon's client process is running, there will also be a
separate pidfile to record the process id of the client process. Its
filename will be the same as the I<daemon> pidfile's, except that the
filename extension will be C<.clientpid> rather than C<.pid>. The only
reason that there should be a C<.pid> file, with no C<.clientpid> file, is
during the delay between respawn attempts bursts.
=item C<-X> I<"cmd">, C<--command=>I<"cmd">
Specify the client command as an option. If a command is specified along
with its name in the configuration file, then a daemon can be invoked merely
by mentioning its name:
daemon --name ftumch
B<Note:> If the client command is specified with the C<--command> option,
either in the configuration file, or on the command line, then any
additional command line arguments on the I<daemon> command line are appended
to the client command that is specified with the C<--command> option.
=item C<-P> I</dir>, C<--pidfiles=>I</dir>
Override the standard pidfile location. The standard pidfile location is
C</var/run> for root (C</etc> on I<Solaris>, C</opt/local/var/run> on
I<macOS> when installed via I<macports>), and C</tmp> for normal users.
This option only affects the C<--name> and C<--list> options. Use this
option if these standard locations are unacceptable, but make sure that you
don't forget where you put your pidfiles. This option is best used in
configuration files, or in shell scripts, rather than on an interactive
command line.
The pidfile location will be created automatically only if it is within the
user's home directory.
=item C<-F> I</path>, C<--pidfile=>I</path>
Override the standard pidfile name and location. The standard pidfile
location is described immediately above. The standard pidfile name is the
argument of the C<--name> option followed by C<.pid>. Use this option if the
standard pidfile name and location are unacceptable, but make sure that you
don't forget where you put your pidfile. This option is best used in
configuration files, or in shell scripts, rather than on an interactive
command line.
The pidfile location will be created automatically only if it is within the
user's home directory.
=item C<-u> I<user[:[group]]>, C<--user=>I<user[:[group]]>
Run the client as a different user (and group). This only works for I<root>.
If the argument includes a I<:group> specifier, I<daemon> will assume the
specified group and no other. Otherwise, I<daemon> will assume all groups
that the specified user is in. For backwards compatibility, C<"."> may be
used instead of C<":"> to separate the user and group but since C<"."> can
appear in user and group names, ambiguities can arise such as using
C<--user=>I<u.g> when users I<u> and I<u.g> and group I<g> all exist. With
such an ambiguity, I<daemon> will assume the user I<u> and group I<g>. Use
C<--user=>I<u.g:> instead for the other interpretation.
=item C<-R> I<path>, C<--chroot=>I<path>
Change the root directory to I<path> before running the client. On some
systems, only I<root> can do this. Note that the path to the client program
and to the configuration file (if any) must be relative to the new root
path.
=item C<-D> I<path>, C<--chdir=>I<path>
Change the current directory to I<path> before running the client. The
default current directory is the root directory (possibly after I<chroot>).
=item C<-m> I<umask>, C<--umask=>I<umask>
Change the umask to I<umask> before running the client. I<umask> must
be a valid octal mode. The default umask is C<022>.
=item C<-e> I<"var=val">, C<--env=>I<"var=val">
Set an environment variable for the client process. This option can be used
any number of times. If it is used, only the supplied environment variables
are passed to the client process. Otherwise, the client process inherits the
current set of environment variables.
=item C<-i>, C<--inherit>
Explicitly inherit environment variables. This is only needed when the
C<--env> option is used. When this option is used, the C<--env> option adds
to the inherited environment, rather than replacing it.
=item C<-U>, C<--unsafe>
Allow reading an unsafe configuration file, and allow the execution of an
unsafe executable. A configuration file or executable is considered to be
unsafe if it is group- or world-writable or is in a directory that is group-
or world-writable (following symbolic links). If an executable is a script
that is interpreted by another executable, then it is considered to be
unsafe if the interpreter is unsafe. If the interpreter is C</usr/bin/env>
(with an argument that is a command name to be searched for in C<$PATH>),
then that command must be safe. By default, I<daemon(1)> will refuse to read
an unsafe configuration file or to execute an unsafe executable when run by
I<root>. This option overrides that behaviour and hence should never be
used.
=item C<-S>, C<--safe>
Disallow reading an unsafe configuration file, and disallow the execution of
an unsafe executable. By default, I<daemon(1)> will allow reading an unsafe
configuration file, and allow the execution of an unsafe executable, when
run by normal users. This option overrides that behaviour.
=item C<-c>, C<--core>
Allow the client to create a core file. This should only be used for
debugging, as it could lead to security-related information disclosures by
daemons run by I<root>.
=item C<--nocore>
By default, clients are prevented from creating a core file. If the
C<--core> option has been used in a configuration file to apply to all named
daemons, then this option can be used to restore the default behaviour for
specific named daemons.
=item C<-r>, C<--respawn>
Respawn the client when it terminates. Without this option, the termination
of a client process causes I<daemon> itself to terminate as well.
=item C<-a> I<#>, C<--acceptable=>I<#>
Specify the minimum acceptable duration of a client process, in seconds.
This option can only be used with the C<--respawn> option. If a client
process terminates before this threshold is reached, then it is considered
to have failed. The default value is C<300> seconds. It cannot be set to
less than C<10> seconds, except by I<root> when used in conjunction with the
C<--idiot> option.
=item C<-A> I<#>, C<--attempts=>I<#>
Specify the number of attempts to respawn before delaying. This option can
only be used with the C<--respawn> option. The default value is C<5>. It
cannot be set to more than C<100> attempts, except by I<root> when used in
conjunction with the C<--idiot> option.
=item C<-L> I<#>, C<--delay=>I<#>
Specify the delay in seconds between each burst of respawn attempts. This
option can only be used with the C<--respawn> option. The default value is
C<300> seconds. It cannot be set to less than C<10> seconds except by
I<root> when used in conjunction with the C<--idiot> option.
=item C<-M> I<#>, C<--limit=>I<#>
Specify a limit to the number of respawn attempt bursts. This option can
only be used with the C<--respawn> option. The default value is C<0>, which
means no limit.
=item C<--idiot>
Turn on idiot mode in which I<daemon> will not enforce the minimum or
maximum values normally imposed on the C<--acceptable>, C<--attempts> and
C<--delay> options. The C<--idiot> option must appear before any of these
options. Only the I<root> user may use this option, because it can turn a
slight misconfiguration into a lot of wasted CPU energy and log messages,
somewhat akin to a self-inflicted denial of service.
Idiot mode also allows the I<root> user to expand environment variable
notation (e.g. C<$VAR> and C<${VAR}>) in command line option arguments, and
in configuration files. By default, internal environment variable expansion
is only performed for normal users. Note that this doesn't apply to any such
expansion performed earlier by the shell that invokes I<daemon(1)>. See the
C<EXPANSION> section below for more details.
=item C<-f>, C<--foreground>
Run the client in the foreground. The client is not turned into a daemon.
=item C<-p>I<[noecho]>, C<--pty>I<[=noecho]>
Connect the client to a pseudo terminal. This option can only be used with
the C<--foreground> option. This is the default when the C<--foreground>
option is supplied and I<daemon>'s standard input is connected to a
terminal. This option is only necessary when the client process must be
connected to a controlling terminal, but I<daemon> itself has been run
without a controlling terminal (e.g. from I<cron(8)> or a pipeline).
If the C<noecho> argument is supplied with this option, the client's side of
the pseudo terminal will be set to C<noecho> mode. Use this only if there
really is a terminal involved and input is being echoed twice.
=item C<-B>, C<--bind>
Automatically terminate the client process (and I<daemon(1)> itself) as soon
as the user has no I<systemd-logind(8)> (or I<elogind(8)>) user sessions. In
other words, automatically terminate when the user logs out. If the user has
no sessions to start with, the client process will be terminated
immediately.
This option is only available on I<Linux> systems that have either
I<systemd(1)> (e.g. I<Debian>) or I<elogind(8)> (e.g. I<Slackware>). On
systems with I<systemd(1)>, you could instead use a I<systemd> user service,
particularly if your user account is not allowed to have user services that
I<linger>.
=item C<-l> I<spec>, C<--errlog=>I<spec>
Send I<daemon>'s standard output and standard error to the syslog
destination or file that is specified by I<spec>. If I<spec> is a syslog
destination of the form C<"facility.priority">, then output is sent to
I<syslog(3)>. Otherwise, output is appended to the file whose path is given
in I<spec>. By default, output is sent to the syslog destination,
C<daemon.err>. See the C<MESSAGING> section below for more details.
=item C<-b> I<spec>, C<--dbglog=>I<spec>
Send I<daemon>'s debug output to the syslog destination or file that is
specified by I<spec>. If I<spec> is a syslog destination of the form
C<"facility.priority">, then output is sent to I<syslog(3)>. Otherwise,
output is appended to the file whose path is given in I<spec>. By default,
output is sent to the syslog destination C<daemon.debug>. See the
C<MESSAGING> section below for more details.
=item C<-o> I<spec>, C<--output=>I<spec>
Capture the client's standard output and standard error, and send it to the
syslog destination or file that is specified by I<spec>. If I<spec> is a
syslog destination of the form C<"facility.priority">, then output is sent
to I<syslog(3)>. Otherwise, output is appended to the file whose path is
given in I<spec>. By default, output is discarded unless the C<--foreground>
option is present, in which case, the client's stdout and stderr are
propagated to I<daemon>'s stdout and stderr, respectively. See the
C<MESSAGING> section below for more details.
=item C<-O> I<spec>, C<--stdout=>I<spec>
Capture the client's standard output, and send it to the syslog destination
or file that is specified by I<spec>. If I<spec> is a syslog destination of
the form C<"facility.priority">, then output is sent to I<syslog(3)>.
Otherwise, stdout is appended to the file whose path is given in I<spec>. By
default, stdout is discarded unless the C<--foreground> option is present,
in which case, the client's stdout is propagated to I<daemon>'s stdout. See
the C<MESSAGING> section below for more details.
=item C<-E> I<spec>, C<--stderr=>I<spec>
Capture the client's standard error, and send it to the syslog destination
or file that is specified by I<spec>. If I<spec> is a syslog destination of
the form C<"facility.priority">, then stderr is sent to I<syslog(3)>.
Otherwise, stderr is appended to the file whose path is given in I<spec>. By
default, stderr is discarded unless the C<--foreground> option is present,
in which case, the client's stderr is propagated to I<daemon>'s stderr. See
the C<MESSAGING> section below for more details.
=item C<--ignore-eof>
After receiving a C<SIGCHLD> signal due to a stopped or restarted client
process, don't bother reading the client's output until the end-of-file is
reached before reaping the client process's termination status with
I<wait(2)>. Normally, there will be little or no output after the C<SIGCHLD>
signal, because the client process has just terminated. However, the client
process might have its own child processes keeping its output open long
after its own termination. When this happens, by default, the client process
remains as a zombie process until its child processes terminate and close
the output. Waiting for the client's child processes to terminate before
considering the client stopped, and before restarting a new invocation,
might be desirable. If not, this option can be used to consider the client
process as being terminated as soon as the C<SIGCHLD> signal has been
received, and reaping its termination status with I<wait(2)> immediately.
=item C<--read-eof>
After receiving a C<SIGCHLD> signal due to a stopped or restarted client
process, continue reading the client's output until the end-of-file is
reached before reaping the client process's termination status with
I<wait(2)>. This is the default behaviour. Normally, there will be little or
no output after the C<SIGCHLD> signal, because the client process has just
terminated. However, the client process might have its own child processes
keeping its output open long after its own termination. When this happens,
the client process remains as a zombie process until its child processes
terminate and close the output. Waiting for the client's child processes to
terminate before considering the client stopped, and before restarting a new
invocation, might be desirable. If so, but the C<--ignore-eof> option has
been used in a configuration file to apply to all named daemons, then this
option can be used to restore the default behaviour for specific named
daemons.
=item C<--running>
Check whether or not a named daemon is running, then I<exit(3)> with
C<EXIT_SUCCESS> if the named daemon is running or C<EXIT_FAILURE> if it
isn't.
If the C<--verbose> option is supplied, print a message before exiting. If
both the named daemon and its client process are running, the output will
look like this, showing both process IDs:
daemon: name is running (pid 7455) (clientpid 7457)
If the named daemon is running but its client process is not (there might be
a delay between respawn attempt bursts), the output will look like this,
showing only the daemon process's ID:
daemon: name is running (pid 7455) (client is not running)
If the named daemon is not running at all, the output will look
like this:
daemon: name is not running
This option can only be used with the C<--name> option. Note that the
C<--chroot>, C<--user>, C<--name>, C<--pidfiles> and C<--pidfile> (and
possibly C<--config>) options must be the same as for the target daemon.
=item C<--restart>
Instruct a named daemon to terminate and restart its client process, by
sending it a C<SIGUSR1> signal. This will cause the named daemon to send its
client process a C<SIGTERM> signal to stop it. If the named daemon had been
started with the C<--restart> option, the named daemon will then restart its
client process. Otherwise, this has the same effect as the C<--stop> option,
and the named daemon's client process is not restarted.
This option can only be used with the C<--name> option. Note that the
C<--chroot>, C<--user>, C<--name>, C<--pidfiles> and C<--pidfile> (and
possibly C<--config>) options must be the same as for the target daemon.
=item C<--stop>
Stop a named daemon by sending it a C<SIGTERM> signal. This will cause the
named daemon to send its client process a C<SIGTERM> option and then exit.
This option can only be used with the C<--name> option. Note that the
C<--chroot>, C<--user>, C<--name>, C<--pidfiles> and C<--pidfile> (and
possibly C<--config>) options must be the same as for the target daemon.
=item C<--signal=>I<signame>
Send the given signal to a named daemon's client process. The signal can be
specified either by number or by name (with or without the "sig" prefix).
Any signal may be sent. However, the named daemon's client process might be
ignoring some signals. For example, C<SIGHUP> will be ignored by default
unless the client process has installed a signal handler for it.
The known list of signals are: C<hup>, C<int>, C<quit>, C<ill>, C<trap>,
C<abrt>, C<iot>, C<bus>, C<fpe>, C<kill>, C<usr1>, C<segv>, C<usr2>,
C<pipe>, C<alrm>, C<term>, C<stkflt>, C<cld>, C<chld>, C<cont>, C<stop>,
C<tstp>, C<ttin>, C<ttou>, C<urg>, C<xcpu>, C<xfsz>, C<vtalrm>, C<prof>,
C<winch>, C<poll>, C<io>, C<pwr>, C<sys>, C<emt> and C<info>. Not all of
them are available on all platforms.
=item C<--list>
Print a list of the currently running named daemons whose pidfiles are in
the applicable pidfile directory which will either be the default (i.e.
C</var/run> for I<root> (C</etc> on I<Solaris>, C</opt/local/var/run> on
I<macOS> when installed via I<macports>), and C</tmp> for normal users), or
it will be specified by the C<--pidfiles> option. Then exit.
Without the C<--verbose> option, this will only list the names of daemons
whose pidfiles are locked, as this implies that the corresponding daemon
must still be running. Note that pidfiles for daemons that were not started
by I<daemon(1)> might not be locked. An unlocked pidfile might indicate that
I<daemon(1)> has died unexpectedly, or it might just be a pidfile for a
daemon that was not started by I<daemon(1)>. If this might lead to
confusion, you might want to consider using a dedicated pidfiles directory
for named daemons started by I<daemon(1)>, and leave the default pidfiles
directories for other daemons that were started independently of
I<daemon(1)>.
With the C<--verbose> option, the items in the list will look like the
output of the C<--running> option with C<--verbose>, but with more detail.
If there are no pidfiles at all, the output will look like this:
No named daemons are running
If a pidfile is locked, and there is a corresponding client pidfile, that
indicates that the named daemon and its client are both running, and the
output will look like this, showing both process IDs:
name is running (pid ####) (client pid ####)
If a pidfile is locked, but there is no client pidfile, that indicates that
the named daemon is running, but its client is not (e.g. during a delay
between respawn attempt bursts when the client is failing to start
successfully), and the output will look like one of the following three
options:
When we can tell that the pidfile is for a process whose executable name is
I<daemon>:
name is running (pid ####) (client is not running)
When we can tell that the pidfile is for a process whose executable name is
something other than I<daemon> (i.e. is independent of I<daemon(1)>):
name is running (pid ####) (independent)
When it's not possible to determine the name of the executable associated
with the I<pidfile> (i.e. On systems other than I<Linux> without a C</proc>
file system):
name is running (pid ####) (client is not running or is independent)
If a pidfile is not locked, and the applicable pidfiles directory is the
default, that indicates either that the daemon has unexpectedly terminated,
or just that the pidfile is for a daemon that was not started by
I<daemon(1)>, and the output will look like this:
name is not running (or is independent)
If a pidfile is not locked, and the applicable pidfiles directory is not the
default, then it is assumed that all pidfiles are for daemons that were
started by I<daemon(1)>, and the output will look like this:
name is not running
=back
As with all other programs, a C<--> argument signifies the end of options.
Any options that appear on the command line after C<--> are part of the
client command.
=head1 EXPANSION
Some simple shell-like expansion is performed internally on the arguments of
the command line options with a text argument (but not the options with a
numeric argument).
Environment variable notation, such as C<$VAR> or C<${VAR}>, is expanded.
Then user home directory notation, such as C<~> or C<~user>, is expanded.
File name expansion (i.e. globbing) is NOT performed internally. Neither are
any of your login shell's other wonderful expansions. This is very basic.
This might not be of much use on the command line, since I<daemon> is
normally invoked via a shell, which will first perform all of its usual
expansions. It might even be undesirable to perform expansion internally
after the shell has already done so (e.g. if you refer to any directory
names that actually contain the C<'$'> character, or if you use any
environment variables whose values contain the C<'$'> character, which is
unlikely).
But it can be useful in configuration files. See the C<FILES> section below
for more details. It can also be useful when I<daemon> is invoked directly
by another program without the use of a shell.
By default, environment variable expansion is not performed for the I<root>
user, even if the environment variable was defined in the configuration
files. The C<--idiot> option can be used to change this behaviour, and allow
the expansion of environment variables for the I<root> user. Home directory
notation expansion is performed for all users.
=head1 FILES
C</etc/daemon.conf>, C</etc/daemon.conf.d/*> - system-wide default options
C</usr/local/etc/daemon.conf>, C</usr/local/etc/daemon.conf.d/*> -
system-wide default options on I<BSD> systems (except I<macOS>).
C</opt/local/etc/daemon.conf>, C</opt/local/etc/daemon.conf.d/*> -
system-wide default options on I<macOS> when installed via I<macports>.
C<~/.daemonrc>, C<~/.daemonrc.d/*> - user-specific default options
Each line of the configuration file is either an environment variable
definition, or a configuration directive.
Environment variable definitions consist of the variable name, followed
immediately by C<'='> and the value of the variable. They look like they do
in shell, except that there is no quoting or other shell syntax. Environment
variable values can include simple environment variable notation (e.g.
C<$VAR> or C<${VAR}>), and user home directory notation (e.g. C<~> or
C<~user>). These will be expanded internally by I<daemon>. See the
C<EXPANSION> section above for more details.
Note that any environment variables that are defined in the configuration
file, which are subsequently used explicitly in another environment variable
definition or in an option argument, will have these expansions performed
multiple times. Avoid environment variables whose values can change again if
expansion is performed multiple times.
Example:
PATH=/usr/bin:/usr/sbin:$HOME/bin:~app/bin
PIDFILES=~/.run
Configuration directives consist of a client name (for options that apply to
a single client), or C<'*'> (for generic options that apply to all clients),
followed by spaces and/or tabs, followed by a comma-separated list of
options. Any option arguments must not contain any commas. The commas that
separate options can have spaces and tabs before and after them. Option
arguments that are text (but not numbers) can include simple environment
variable notation (e.g. C<$VAR> or C<${VAR}>), and user home directory
notation (e.g. C<~> or C<~user>). These will be expanded internally by
I<daemon>. See the C<EXPANSION> section above for more details.
Blank lines and comments (C<'#'> to end of the line) are ignored. Lines can
be continued with a C<'\'> character at the end of the line.
Example:
* errlog=daemon.err,output=local0.err,core
test1 syslog=local0.debug,debug=9,verbose=9,respawn
test2 syslog=local0.debug,debug=9, \
verbose=9,respawn, \
pidfiles=$PIDFILES
The command line options are processed first, to look for a C<--config>
option. If no C<--config> option was supplied, the default configuration
files, C</etc/daemon.conf> and C</etc/daemon.conf.d/*>, are used. On I<BSD>
systems (except I<macOS>), the default configuration files are
C</usr/local/etc/daemon.conf> and C</usr/local/etc/daemon.conf.d/*>. On
I<macOS> when installed via I<macports>, the default configuration files are
C</opt/local/etc/daemon.conf> and C</opt/local/etc/daemon.conf.d/*>.
If the user has their own configuration files, C<~/.daemonrc> and
C<~/.daemonrc.d/*>, they are also used.
If the configuration files contain any generic (C<'*'>) entries, their
options are applied in order of appearance. If the C<--name> option was
supplied, and the configuration files contain any entries for the given
name, those options are then applied in order of appearance.
Finally, the command line options are applied again. This ensures that any
generic options apply to all clients by default. Client-specific options
override generic options. User options override system-wide options. Command
line options override everything else.
Note that the configuration files are not opened and read until after any
C<--chroot> and/or C<--user> command line options are processed. This means
that the configuration file paths and the client's file path must be
relative to the C<--chroot> argument. It also means that the configuration
files and the client executable must be readable/executable by the user
specified by the C<--user> argument. It also means that the C<--chroot> and
C<--user> options must not appear in the configuration file. Also note that
the C<--name> option must not appear on the right hand side in the
configuration file either.
=head1 MESSAGING
The C<--errlog>, C<--dbglog>, C<--output>, C<--stdout> and C<--stderr>
options all take an argument that can be either a syslog destination of the
form C<"facility.priority"> or the path to a file. Here are the lists of
syslog facilities and priorities:
Facilities:
kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron,
local0, local1, local2, local3, local4, local5, local6, local7.
Priorities:
emerg, alert, crit, err, warning, notice (on some systems), info, debug.
If the path to a file is supplied instead, bear in mind the fact that
I<daemon(1)> changes to the root directory by default, and so the file path
should be an absolute path (or relative to the C<--chroot> and/or C<--chdir>
option argument). Otherwise, I<daemon(1)> will attempt to create the file
relative to its current directory. You might not have permissions to do
that, or want to even if you do.
=head1 CAVEAT
Clients can only be restarted if they were started with the C<--respawn>
option. Using C<--restart> on a non-respawning daemon client is equivalent
to using C<--stop>. If you try to restart a named daemon, and it stops
instead, then it probably wasn't started with the C<--respawn> option.
Clients that are run in the foreground with a pseudo terminal don't respond
to job control (i.e. suspending with Control-Z doesn't work). This is
because the client belongs to an orphaned process group (it starts in its
own process session), so the kernel won't send it C<SIGSTOP> signals.
However, if the client is a shell that supports job control, then its
subprocesses can be suspended.
In KDE, if you use C<"exec daemon"> (or just C<"exec"> without C<daemon>) in
a shell, to run a KDE application, you might find that the KDE application
sometimes doesn't run. This problem has only been seen with I<konsole(1)>,
but it might happen with other KDE applications as well. Capturing the
standard error of the KDE application might show something like:
unnamed app(9697): KUniqueApplication: Registering failed!
unnamed app(9697): Communication problem with "konsole" , it probably crashed.
Error message was: "org.freedesktop.DBus.Error.ServiceUnknown" : " "The name
org.kde.konsole was not provided by any .service files"
A workaround seems to be to delay the termination of the initial
I<daemon(1)> process by at least 0.4 seconds. To make this happen, set the
environment variable C<DAEMON_INIT_EXIT_DELAY_MSEC> to the number of
milliseconds by which to delay. For example:
C<DAEMON_INIT_EXIT_DELAY_MSEC=400>. Or you could just avoid using C<exec>
when starting I<KDE> applications.
On I<Linux> systems that have I<systemd(1)> or I<elogind(8)>, you might find
that your I<daemon> processes and their client processes are terminated when
you logout, even though they are in a different process session, and so
should be unaffected. This is because I<systemd> has the ability to
terminate all of your processes when you logout. Luckily, this feature is
turned off by default in some I<Linux> distributions. However, if it is on,
you can turn it off by adding the following line to
C</etc/systemd/logind.conf> (or C</etc/elogind/logind.conf>):
KillUserProcesses=no
=head1 SEE ALSO
I<libslack(3)>,
I<daemon(3)>,
I<coproc(3)>,
I<pseudo(3)>,
I<init(8)>,
I<inetd(8)>,
I<fork(2)>,
I<umask(2)>,
I<setsid(2)>,
I<chdir(2)>,
I<chroot(2)>,
I<setrlimit(2)>,
I<setgid(2)>,
I<setuid(2)>,
I<setgroups(2)>,
I<initgroups(3)>,
I<syslog(3)>,
I<kill(2)>,
I<wait(2)>,
I<systemd-logind(8)>,
I<elogind(8)>
=head1 AUTHOR
20230824 raf <[email protected]>
=cut
*/
#ifndef _BSD_SOURCE
#define _BSD_SOURCE /* For SIGWINCH and CEOF on OpenBSD-4.7 */
#endif
#ifndef _DEFAULT_SOURCE
#define _DEFAULT_SOURCE /* New name for _BSD_SOURCE */
#endif
#ifndef __BSD_VISIBLE
#define __BSD_VISIBLE 1 /* For SIGWINCH on FreeBSD-8.0 */
#endif
#ifndef _NETBSD_SOURCE
#define _NETBSD_SOURCE /* For CEOF, chroot() on NetBSD-5.0.2 */
#endif
#include <slack/std.h>