lib/App/Syslogd.pm

filter: Statementstmt 99.6% 290 / 291 Branchbran 96.8% 91 / 94 Conditioncond 97.2% 70 / 72 MC/DCmcdc 95.3% 41 / 43 Subroutinesub 100% 50 / 50 Podpod 100% 11 / 11 totaltotal 98.5% 553 / 561 CC 71 SCAR 15.7
CC
71
Cov
99%
_open_log
10.0
run
10.0
parse_message
9.0
CRAP 4.8
« lib/App/Syslogd/I18N.pm ↑ Summary etc/syslogd »
1 package App::Syslogd;
2  
3 51 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 51 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 51 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 # Encapsulation of the _helpers. Sub::Private's enforce mode must be
8 # chosen before the module is loaded, otherwise private subs are removed
9 # from the stash and $self->_x() breaks.
10 #
11 # Both modules declare a CHECK block. When this module is loaded at run
12 # time (require, a plugin loader), CHECK has already happened, so Perl
13 # warns "Too late to run CHECK block" while compiling them; the warning is
14 # about their internals, so it is filtered here and nothing else is.
15 # The helpers are protected at the bottom of this file; see there for why.
16 51 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
17 # TODO: Data Flow Anomaly - this global is defined here and never restored, so every
18 # package loaded later in the same process that uses Sub::Private also gets enforce
19 # mode instead of the default namespace mode. It cannot be localised: Sub::Private
20 # reads it when it wraps the subs, at CHECK time. Needs a per-package mode in
21 # Sub::Private (e.g. "use Sub::Private { mode => 'enforce' }").
22 51 $Sub::Private::config{mode} = 'enforce';
23 # The text matched here is Perl's own. If a later Perl words it differently
24 # the warning shows again, which is harmless; t/extended_tests.t checks that
25 # every other warning still gets through.
26 51 ▶ local $SIG{__WARN__} = sub { warn(@_) unless($_[0] =~ /\AToo late to run CHECK block /) };
Subroutine __ANON__: called CC=2 SCAR=7.2
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] =~ /\AToo late to run CHECK block / 1 0 1
27 51 require Sub::Private;
28 51 require Sub::Protected;
29 }
30  
31 51 ▶use Carp qw(carp croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
32 51 ▶use Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 51 ▶use Fcntl qw(O_RDWR O_APPEND O_CREAT SEEK_SET SEEK_END);
Subroutine BEGIN: called CC=1 SCAR=0.0
34 51 ▶use IO::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 51 ▶use IO::Socket::IP (); # (): IO::Socket would export all of Socket's constants as methods
Subroutine BEGIN: called CC=1 SCAR=0.0
36 51 ▶use Object::Configure;
Subroutine BEGIN: called CC=1 SCAR=0.0
37 51 ▶use overload ();
Subroutine BEGIN: called CC=1 SCAR=0.0
38 51 ▶use Params::Get;
Subroutine BEGIN: called CC=1 SCAR=0.0
39 51 ▶use Params::Validate::Strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
40 51 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
41 51 ▶use Socket qw(getnameinfo NI_NAMEREQD NI_NUMERICHOST NIx_NOSERV);
Subroutine BEGIN: called CC=1 SCAR=0.0
42 51 ▶use Text::CSV;
Subroutine BEGIN: called CC=1 SCAR=0.0
43  
44 50 ▶use App::Syslogd::Cache;
Subroutine BEGIN: called CC=1 SCAR=0.0
45 50 ▶use App::Syslogd::I18N;
Subroutine BEGIN: called CC=1 SCAR=0.0
46  
47 50 our $VERSION = '0.002.1';
48  
49 # Every tunable lives here, so it can be overridden from new() and so
50 # nothing in the code below is a magic number
51 50 Readonly our %DEFAULTS => (
52 port => 514, # RFC 5426 well-known port
53 address => '0.0.0.0', # IPv4 wildcard, as the original script used
54 file => '/var/log/syslog/syslog.csv', # The directory must exist; see INSTALLATION
55 resolve => 1, # Log host names rather than addresses
56 dns_ttl => 300, # Seconds to remember a reverse lookup
57 dns_cache_bytes => 262_144, # Upper bound on the reverse-lookup cache
58 );
59  
60 # Scalar constants use Readonly::Scalar: "Readonly my $x" makes a tied
61 # scalar, and every read then costs a tied FETCH (about 45 times slower).
62 # Several of these are read for every datagram.
63  
64 # Largest possible UDP payload, so datagrams are never silently truncated
65 # (RFC 5426 section 3.2 asks receivers to accept at least 2048 octets)
66 50 Readonly::Scalar my $RECV_BUFFER => 65_535;
67  
68 # One-character datagrams are keep-alives or noise, never a log line
69 50 Readonly::Scalar my $MIN_MESSAGE_LENGTH => 2;
70  
71 # PRI = facility * 8 + severity; RFC 5424 section 6.2.1 caps it at 191
72 50 Readonly::Scalar my $SEVERITIES_PER_FACILITY => 8;
73 50 Readonly::Scalar my $MAX_PRI => 191;
74  
75 # RFC 3164 section 4.3.3: a message without a valid PRI is user.notice
76 50 Readonly::Scalar my $DEFAULT_PRI => 13;
77  
78 # The log holds other hosts' messages, so only its owner may read it
79 50 Readonly::Scalar my $LOG_MODE => 0600; ## no critic (ProhibitLeadingZeros): a file mode is octal
80  
81 # O_NOFOLLOW is not defined everywhere: on Windows, Fcntl exports the name
82 # but calling it dies ("Your vendor has not defined Fcntl macro"). Where it
83 # is missing, 0 leaves the open flags unchanged. Windows symbolic links
84 # need administrator rights to create, so the attack it prevents is rare
85 # there; see LIMITATIONS.
86 50 ▶Readonly::Scalar my $O_NOFOLLOW => eval { Fcntl::O_NOFOLLOW() } // 0;
Condition50%1/2
eval { do { 131072 } } // 0
l!l
500
MC/DC0%0/1
eval { do { 131072 } } // 0
eval { do { 131072 } }
Truth table50%1/2
A
A= eval { do { 131072 } }
Aresult
11
00
87  
88 # O_NONBLOCK makes opening a FIFO fail at once (ENXIO) instead of waiting
89 # for a reader. Without it anyone able to create a FIFO where the log
90 # goes (a shared directory such as /tmp) could make the server hang for
91 # ever at start-up. It has
92 # no effect on the regular files we accept. Not defined on Windows.
93 50 ▶Readonly::Scalar my $O_NONBLOCK => eval { Fcntl::O_NONBLOCK() } // 0;
Condition50%1/2
eval { do { 2048 } } // 0
l!l
500
MC/DC0%0/1
eval { do { 2048 } } // 0
eval { do { 2048 } }
Truth table50%1/2
A
A= eval { do { 2048 } }
Aresult
11
00
94  
95 # chmod() on a filehandle needs fchmod(), which Windows Perl does not have
96 # ("The fchmod function is unimplemented"). Windows does not use Unix
97 # permission bits anyway, so there is nothing to tighten; see LIMITATIONS.
98 # chmod() by name is not a substitute: the name may no longer be the file
99 # we checked.
100 50 ▶Readonly::Scalar my $HAVE_FCHMOD => $Config{d_fchmod} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$App::Syslogd::Config{'d_fchmod'} ? : 50 0 50
101  
102 # Column headings written to a brand-new log file. VWF::Data::syslog_log
103 # reads these as its column names, so do not change them lightly.
104 50 Readonly my @CSV_HEADER => qw(Host facility severity msg);
105  
106 # What Object::Configure adds that is kept on the object, besides settings
107 50 Readonly my @CONFIGURE_EXTRAS => qw(logger config_path);
108  
109 # Strings that reach the C library (bind, open, the locale) must not hold
110 # a NUL: C stops reading there, so "127.0.0.1\0.evil" would bind to
111 # 127.0.0.1 while the object (and every message) named something else.
112 50 Readonly::Scalar my $NO_NUL => qr/\A[^\x00]+\z/;
113  
114 # Parameter schema shared by new() and the API SPECIFICATION in the POD
115 50 Readonly my %NEW_SCHEMA => (
116 port => { type => 'integer', min => 0, max => 65_535, optional => 1 },
117 address => { type => 'string', min => 1, matches => $NO_NUL, optional => 1 },
118 file => { type => 'string', min => 1, matches => $NO_NUL, optional => 1 },
119 resolve => { type => 'boolean', optional => 1 },
120 dns_ttl => { type => 'integer', min => 0, optional => 1 },
121 dns_cache_bytes => { type => 'integer', min => 1, optional => 1 },
122 language => { type => 'string', min => 1, matches => $NO_NUL, optional => 1 },
123 cache => { type => 'object', can => ['compute'], optional => 1 },
124 socket => { type => 'object', can => ['recv'], optional => 1 },
125 );
126  
127 =head1 NAME
128  
129 App::Syslogd - A small UDP syslog receiver that writes a CSV file
130  
131 =head1 VERSION
132  
133 Version 0.002.1
134  
135 =head1 SYNOPSIS
136  
137 =head2 1. Run a syslog server
138  
139 This is what the program F<etc/syslogd> does. It listens for messages
140 until it receives SIGTERM or SIGINT (Ctrl-C).
141  
142 use App::Syslogd;
143  
144 my $server = App::Syslogd->new(
145 port => 5514, # 514 needs root
146 file => '/var/log/syslogd/remote.csv',
147 );
148 $server->open_socket()->reopen_log(); # fail now, not later
149 print $server->i18n('listening', {
150 address => $server->address(),
151 port => $server->port(),
152 }), "\n";
153 $server->run(); # waits here until stopped
154 print $server->i18n('shutdown', { count => $server->count() }), "\n";
155  
156 =head2 2. Decode one message, without a network or a file
157  
158 C<parse_message()> uses no state, so you can call it on the class.
159  
160 use App::Syslogd;
161  
162 my $record = App::Syslogd->parse_message('<34>su: authentication failure');
163 print "facility $record->{facility}, severity $record->{severity}\n";
164 # facility 4, severity 2
165  
166 =head2 3. Record messages that your own code received
167  
168 Use this when your program already has a socket loop, for example an event
169 loop that watches many sockets.
170  
171 use App::Syslogd;
172 use IO::Socket::IP;
173  
174 my $recorder = App::Syslogd->new(file => '/var/log/remote.csv', resolve => 0);
175 $recorder->reopen_log();
176  
177 my $socket = IO::Socket::IP->new(LocalPort => 5514, Proto => 'udp')
178 or die "Cannot listen: $IO::Socket::errstr";
179 while(my $peer = $socket->recv(my $datagram, 65535)) {
180 $recorder->process($datagram, $peer);
181 }
182  
183 =head2 4. Use a socket that someone else opened, for a fixed time
184  
185 Pass the socket to C<new()>, for example one received from systemd socket
186 activation, or one opened before giving up root. C<stop()> ends C<run()>.
187  
188 my $server = App::Syslogd->new(socket => $already_bound_socket, file => $file);
189  
190 local $SIG{ALRM} = sub { $server->stop() };
191 alarm(3600); # stop after one hour
192 $server->run();
193  
194 =head2 5. Change how the sender is written in the log
195  
196 C<_peer_name()> is protected: a subclass may replace it.
197  
198 package My::Syslogd;
199 use parent 'App::Syslogd';
200 use Socket ();
201  
202 # Write "name [address]" instead of just the name
203 sub _peer_name {
204 my ($self, $peer) = @_;
205 my $name = $self->SUPER::_peer_name($peer);
206 my (undef, $address) = Socket::getnameinfo($peer, Socket::NI_NUMERICHOST());
207 return "$name [$address]";
208 }
209  
210 =head1 DESCRIPTION
211  
212 This distribution has two parts: the module App::Syslogd, and the program
213 F<etc/syslogd> that wraps it. Installing from CPAN installs only the
214 module. The program is not installed by C<make install>; copy it by hand
215 (see L</INSTALLATION>).
216  
217 =head2 What syslog is
218  
219 Many machines (servers, routers, printers, firewalls) can send their log
220 messages over the network with the I<syslog> protocol. Each message is one
221 UDP packet, called a I<datagram>. A message usually starts with a number in
222 angle brackets, the I<PRI> (priority), for example C<< <34> >>. The PRI
223 holds two smaller numbers:
224  
225 =over 4
226  
227 =item * B<facility> = PRI divided by 8, rounded down (0 to 23). It says which
228 part of the system sent the message, for example 4 means "security".
229  
230 =item * B<severity> = the remainder of PRI divided by 8 (0 to 7). It says how
231 serious the message is: 0 is "emergency" and 7 is "debug".
232  
233 =back
234  
235 So C<< <34> >> means facility 4 (34 / 8 = 4) and severity 2 (34 - 32 = 2).
236  
237 =head2 What this module does
238  
239 It waits for syslog datagrams and adds one line to a CSV file for each one.
240 The first line of a new file names the columns:
241  
242 "Host","facility","severity","msg"
243 "router.example.com","4","2","su: authentication failure"
244  
245 =over 4
246  
247 =item * B<Host> is the name of the machine that sent the message. The name
248 is found with the normal system lookup (F</etc/hosts>, then DNS) and
249 remembered for a few minutes. If no name is found, or if you turn names
250 off, the IP address is written instead. IPv4 and IPv6 both work. Whoever
251 controls an address controls its reverse-DNS name, so control characters in
252 a name are written as C<\xNN>, as in the message.
253  
254 =item * B<facility> and B<severity> come from the PRI. If the PRI is missing
255 or not valid, the message is still kept: it is recorded as facility 1,
256 severity 5 ("user.notice"), and the whole datagram becomes the message.
257 RFC 3164 section 4.3.3 asks for this. A valid PRI is a number from 0 to 191
258 with no extra leading zeros.
259  
260 =item * B<msg> is the rest of the datagram. Line endings at the end are
261 removed. Other control characters, including a newline in the middle, are
262 written as C<\xNN> (for example C<\x0A>). So every message is exactly one
263 line, and nobody can create a fake extra line by sending a newline.
264  
265 =back
266  
267 =head2 Other behaviour
268  
269 =over 4
270  
271 =item * Signal B<SIGHUP> closes and reopens the log file. Log rotation tools
272 such as logrotate use this: they rename the file, then send SIGHUP, and the
273 server starts a new file.
274  
275 =item * Signals B<SIGTERM> and B<SIGINT> stop the server cleanly.
276  
277 =item * The log file is created so that only its owner can read it (mode
278 0600). The server will not write through a symbolic link or a hard link, or
279 into a file that another user owns. An existing file that is not empty
280 must start with the column-names line, so the server only ever adds to its
281 own logs: even as root, a wrong setting cannot make it append to (or change
282 the permissions of) some other file, such as F</etc/passwd>. This protects
283 against attacks that trick a root process into overwriting a file. (Windows
284 is weaker here: see L</LIMITATIONS>.)
285  
286 =item * Datagrams up to 65535 bytes (the largest UDP size) are read
287 completely. Datagrams shorter than 2 characters are ignored.
288  
289 =back
290  
291 =head1 COMMAND LINE
292  
293 The program F<etc/syslogd> is a small wrapper around this module:
294  
295 /usr/local/etc/syslogd [--port 514] [--address 0.0.0.0] [--file /var/log/syslog/syslog.csv]
296 [--no-resolve] [--language en]
297  
298 =over 4
299  
300 =item C<--port> - the UDP port to listen on. The default is 514, the
301 standard syslog port. Ports below 1024 need root.
302  
303 =item C<--address> - the local address to listen on. The default
304 C<0.0.0.0> means "every IPv4 address of this machine". Use C<::> for IPv6.
305  
306 =item C<--file> - the CSV log file. The default is
307 F</var/log/syslog/syslog.csv>. The directory must exist and be writable by
308 the user that runs the server (see L</INSTALLATION>). On Debian, Ubuntu and
309 their derivatives F</var/log/syslog> is the system log file, so give
310 C<--file> there (see L</LIMITATIONS>).
311  
312 =item C<--no-resolve> - write IP addresses instead of host names. This is
313 faster on a busy server.
314  
315 =item C<--language> - the language of the program's own messages, for example
316 C<en>. By default it comes from the environment (C<LANG> and similar).
317  
318 =back
319  
320 Send B<SIGHUP> to reopen the log file. Send B<SIGTERM>, or press Ctrl-C, to
321 stop.
322  
323 =head2 Log rotation
324  
325 Rotate the log by renaming it and then sending SIGHUP, so that the server
326 starts a new file. See L</SAMPLE CONFIGURATION> for logrotate and
327 newsyslog settings.
328  
329 =head1 INSTALLATION
330  
331 Install the module from CPAN:
332  
333 cpanm App::Syslogd
334  
335 or from a git checkout:
336  
337 perl Makefile.PL && make && make test && sudo make install
338  
339 Then copy the program by hand, and create the directory for the default
340 log file (the server does not create directories):
341  
342 sudo cp etc/syslogd /usr/local/etc/
343 sudo mkdir -m 700 /var/log/syslog
344  
345 Make that directory belong to the user that runs the server, if it is not
346 root. On Debian and Ubuntu F</var/log/syslog> is already a file; use
347 another directory and C<--file> there.
348  
349 C<make install> does not install the program on purpose. It would put it in
350 a F<bin> directory, and a program called F<syslogd> there could hide the
351 system's own F</usr/sbin/syslogd>.
352  
353 To use a git checkout without installing the module, copy the module next to
354 the program:
355  
356 sudo cp -r lib/App /usr/local/lib/
357  
358 The program looks for modules in F<../lib> relative to itself (that is
359 F</usr/local/lib> after installation, or F<lib/> in a git checkout), and also
360 in Perl's normal module directories.
361  
362 =head1 SAMPLE CONFIGURATION
363  
364 These samples run the server as its own user, C<syslogd>, writing to
365 F</var/log/syslog/remote.csv>. Adjust the names and paths to suit.
366  
367 Three things shape them:
368  
369 =over 4
370  
371 =item * The server only writes to a log file that it owns (see
372 L</DESCRIPTION>), so the file must live in a directory the C<syslogd> user
373 can write to.
374  
375 =item * The server does not put itself in the background and writes no
376 process-id file: run it under a service manager that keeps it in the
377 foreground (systemd), or through F<daemon(8)> (FreeBSD).
378  
379 =item * The service is called C<app-syslogd> (C<app_syslogd> on FreeBSD)
380 so that it does not clash with the operating system's own syslog daemon.
381  
382 =back
383  
384 Create the user first, for example:
385  
386 # Linux
387 useradd --system --no-create-home --shell /usr/sbin/nologin syslogd
388  
389 # FreeBSD
390 pw useradd syslogd -d /nonexistent -s /usr/sbin/nologin -c "App::Syslogd"
391 mkdir -p /var/log/syslog && chown syslogd /var/log/syslog && chmod 700 /var/log/syslog
392  
393 =head2 systemd (Linux)
394  
395 Save as F</etc/systemd/system/app-syslogd.service>, then run
396 C<systemctl daemon-reload> and C<systemctl enable --now app-syslogd>.
397  
398 [Unit]
399 Description=App::Syslogd UDP syslog receiver
400 Documentation=https://metacpan.org/pod/App::Syslogd
401 After=network-online.target
402 Wants=network-online.target
403  
404 [Service]
405 Type=simple
406 User=syslogd
407 Group=syslogd
408 # Port 514 is below 1024: grant just that right, not root
409 AmbientCapabilities=CAP_NET_BIND_SERVICE
410 CapabilityBoundingSet=CAP_NET_BIND_SERVICE
411 # Creates /var/log/syslog, owned by the user above
412 LogsDirectory=syslog
413 LogsDirectoryMode=0700
414 ExecStart=/usr/local/etc/syslogd --port 514 --file /var/log/syslog/remote.csv
415 # SIGHUP reopens the log after rotation
416 ExecReload=/bin/kill -HUP $MAINPID
417 Restart=on-failure
418 RestartSec=5
419 # Hardening: the server needs nothing more
420 NoNewPrivileges=yes
421 ProtectSystem=strict
422 ProtectHome=yes
423 PrivateTmp=yes
424 PrivateDevices=yes
425 RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
426  
427 [Install]
428 WantedBy=multi-user.target
429  
430 SIGTERM (C<systemctl stop>) stops the server cleanly with exit status 0.
431 The server's start-up and shutdown lines go to the journal
432 (C<journalctl -u app-syslogd>).
433  
434 =head2 rc.d and service (FreeBSD)
435  
436 Save as F</usr/local/etc/rc.d/app_syslogd> (mode 0555), then add
437 C<app_syslogd_enable="YES"> to F</etc/rc.conf> and run
438 C<service app_syslogd start>.
439  
440 #!/bin/sh
441  
442 # PROVIDE: app_syslogd
443 # REQUIRE: NETWORKING
444 # KEYWORD: shutdown
445  
446 . /etc/rc.subr
447  
448 name="app_syslogd"
449 rcvar="app_syslogd_enable"
450  
451 load_rc_config $name
452  
453 : ${app_syslogd_enable:="NO"}
454 : ${app_syslogd_user:="root"}
455 : ${app_syslogd_options:="--port 514 --file /var/log/syslog/remote.csv"}
456  
457 pidfile="/var/run/${name}.pid"
458  
459 # daemon(8) puts the server in the background and writes the pid
460 # file (-p: the server's own pid, so SIGHUP reaches it)
461 command="/usr/sbin/daemon"
462 command_args="-f -p ${pidfile} -u ${app_syslogd_user} /usr/local/etc/syslogd ${app_syslogd_options}"
463  
464 # The running process is "perl /usr/local/etc/syslogd ..."
465 procname="/usr/local/etc/syslogd"
466 command_interpreter="/usr/local/bin/perl"
467  
468 # service app_syslogd reload: reopen the log
469 extra_commands="reload"
470 sig_reload="HUP"
471  
472 run_rc_command "$1"
473  
474 The options go in C<app_syslogd_options>, not C<app_syslogd_flags>:
475 F<rc.subr> would put C<_flags> before C<command_args>, that is, give them to
476 F<daemon(8)>. Binding port 514 needs root on FreeBSD, so the sample runs as
477 root; to run as C<syslogd>, use a port above 1023 (or
478 L<mac_portacl(4)>) and set C<app_syslogd_user="syslogd">. The log file
479 must belong to whichever user runs the server.
480  
481 =head2 logrotate (Linux)
482  
483 Save as F</etc/logrotate.d/app-syslogd>.
484  
485 /var/log/syslog/remote.csv {
486 weekly
487 rotate 8
488 compress
489 delaycompress
490 missingok
491 # The directory belongs to syslogd, so rotate as that user
492 su syslogd syslogd
493 # Never copytruncate: see below
494 create 0600 syslogd syslogd
495 postrotate
496 systemctl reload app-syslogd.service
497 endscript
498 }
499  
500 Do not use C<copytruncate>. It empties the log in place without telling
501 the server, which then carries on writing rows to a file with no column
502 names; at the next reopen the server would refuse that file, because it no
503 longer starts with the header line. C<create> (or no C<create>: the server
504 makes the file itself on SIGHUP) is what the server expects.
505  
506 =head2 newsyslog (FreeBSD)
507  
508 Add to F</etc/newsyslog.conf> (or a file in F</usr/local/etc/newsyslog.conf.d/>):
509  
510 # logfilename owner:group mode count size when flags pid_file sig
511 /var/log/syslog/remote.csv root:wheel 600 8 * @T00 JC /var/run/app_syslogd.pid 1
512  
513 Creates the new, empty file; signal 1 (SIGHUP) makes the server
514 reopen it. Use the owner that runs the server.
515  
516 =head2 Monit and M/Monit
517  
518 Add to F</etc/monit/monitrc> (Linux) or F</usr/local/etc/monitrc>
519 (FreeBSD). M/Monit collects the results when F<monitrc> names it with
520 C<set mmonit>.
521  
522 # Report to M/Monit (optional)
523 set mmonit https://monit:monit@mmonit.example.com:8443/collector
524  
525 # Linux, with the systemd unit above
526 check process app-syslogd matching "/usr/local/etc/syslogd"
527 start program = "/bin/systemctl start app-syslogd"
528 stop program = "/bin/systemctl stop app-syslogd"
529 if 5 restarts within 5 cycles then alert
530  
531 # FreeBSD, with the rc.d script above, use instead:
532 # check process app_syslogd with pidfile /var/run/app_syslogd.pid
533 # start program = "/usr/sbin/service app_syslogd start"
534 # stop program = "/usr/sbin/service app_syslogd stop"
535  
536 # The log must stay private and be written to
537 check file app-syslogd-log with path /var/log/syslog/remote.csv
538 if failed permission 600 then alert
539 if failed uid "syslogd" then alert
540 if timestamp > 1 hour then alert
541  
542 Monit's UDP port test is not used: syslog never answers, so a port test
543 cannot show that messages are being recorded. The timestamp check does:
544 change C<1 hour> to suit how often your hosts send messages.
545  
546 =head1 COOKBOOK
547  
548 =head2 Look at the log with Database::BI
549  
550 L<Database::BI> is a separate program (install it from CPAN) that shows a
551 data file as a table in your web browser. You can sort, filter and count the
552 rows without writing any code. It reads the file again for every page, so
553 it always shows the messages that have arrived so far, and the two programs
554 do not need to know about each other.
555  
556 The log has four columns: C<Host>, C<facility>, C<severity> and C<msg>.
557 C<facility> and C<severity> are numbers; see L</What syslog is>. These
558 severity numbers are the ones you will use most:
559  
560 0 emergency 1 alert 2 critical 3 error
561 4 warning 5 notice 6 info 7 debug
562  
563 The examples below use the web addresses that Database::BI shows in its
564 browser. Replace C<syslog> in each address with the name of your log file
565 without C<.csv>. Database::BI names a table after its file, so
566 C</var/log/syslog/syslog.csv> is the table C<syslog>, and F<remote.csv>
567 would be the table C<remote>. The file name must be in lower case
568 (F<remote.csv>, not F<Remote.csv>), because Database::BI looks the table up
569 in lower case.
570  
571 =head3 Recipe 1: show the log
572  
573 Create F<database_bi.conf> in the folder that holds Database::BI's
574 F<script/> directory. Point C<data_dir> at the directory that holds the log:
575  
576 { data_dir => '/var/log/syslog' }
577  
578 Start Database::BI as the same user that runs the syslog server, then open
579 C<http://127.0.0.1:3000/view/syslog> in a browser:
580  
581 script/database-bi
582  
583 The same user is needed because the server keeps the log private (mode
584 0600): nobody else can read it. Do not make the log readable by everyone
585 to get around this; it holds other machines' messages. Database::BI
586 listens on this machine only until you change its C<listen> setting, and it
587 will not listen on other machines unless you also set a password (see its
588 manual). Keep it that way unless you have a reason not to.
589  
590 =head3 Recipe 2: which machine sends the most messages?
591  
592 Open this address. It counts the messages from each host and adds a total:
593  
594 http://127.0.0.1:3000/pivot?l=table:syslog&rows=Host&m=msg:count:messages&totals=1
595  
596 To count by how serious the messages are, use C<rows=severity>. To see
597 hosts and severities together, use C<rows=Host,severity>.
598  
599 =head3 Recipe 3: show only the serious messages
600  
601 A filter is written C<f=column:operator:value>. Severity 3 (error) and
602 below are the serious ones, so keep every row whose severity is at most 3:
603  
604 http://127.0.0.1:3000/view/syslog?f=severity:le:3
605  
606 The same filter also works on a pivot, so you can count only the serious
607 messages by host:
608  
609 http://127.0.0.1:3000/pivot?l=table:syslog&rows=Host&m=msg:count:errors&f=severity:le:3
610  
611 =head3 Recipe 4: find a word from one machine
612  
613 Give C<f=> more than once to apply every condition. This keeps the rows
614 from host 192.0.2.1 whose message contains "disk":
615  
616 http://127.0.0.1:3000/view/syslog?f=Host:eq:192.0.2.1&f=msg:contains:disk
617  
618 If the server runs with C<--no-resolve>, C<Host> holds an address, as above.
619 Otherwise it holds the host name, so use that name in the filter.
620  
621 =head3 Recipe 5: summarise every column
622  
623 This shows one row for each column: how many rows, how many different
624 values, and the first and last value. It is a quick way to see which
625 severities occur at all:
626  
627 http://127.0.0.1:3000/stats?l=table:syslog
628  
629 =head3 Recipe 6: log rotation
630  
631 You do not need to change anything. The syslog server reopens the log on
632 SIGHUP (see L</Log rotation>), and Database::BI reads whatever file has the
633 name at the time of each request. Right after a rotation the new file holds
634 only the header line, so the table is empty until a message arrives.
635  
636 A rotated copy has a different name, such as F<remote.csv.1>, which
637 Database::BI does not recognise. To look at it, make an uncompressed copy
638 whose name ends in C<.csv> in a directory that Database::BI reads.
639  
640 =head3 What this cannot do
641  
642 The log has no time column: the server does not write the time a message
643 arrived, so Database::BI cannot draw a graph over time or limit the rows to
644 "the last hour". Use the order of the rows, which is the order of arrival,
645 or add a time stamp at the sender if you need one.
646  
647 =head1 DEPENDENCIES
648  
649 Perl 5.14 or later, and these modules: L<autodie> (which needs
650 L<IPC::System::Simple>), L<Carp>, L<Config>, L<Fcntl>, L<IO::Handle>,
651 L<IO::Socket::IP>, L<Locale::Maketext>, L<Object::Configure>, L<overload>,
652 L<parent>, L<Params::Get>, L<Params::Validate::Strict>, L<Readonly>,
653 L<Socket>, L<Sub::Private>, L<Sub::Protected> and L<Text::CSV>. The
654 program F<etc/syslogd> also uses L<FindBin> and L<Getopt::Long>. Most of
655 these come with Perl. F<Makefile.PL> lists the minimum versions.
656  
657 =head1 FILES
658  
659 =over 4
660  
661 =item F<etc/syslogd> - the command-line program. Install it as
662 F</usr/local/etc/syslogd>.
663  
664 =item F<lib/App/Syslogd.pm> - this module.
665  
666 =item F<lib/App/Syslogd/I18N.pm> and F<lib/App/Syslogd/I18N/en.pm> - the
667 messages that people see, and their English text.
668  
669 =item F<lib/App/Syslogd/Cache.pm> - the built-in cache for host names.
670  
671 =item F<t/> - the tests. Run them with C<prove -l t/>.
672  
673 =item F<www/> - a web page that shows the log. It is only in the git
674 repository, not in the CPAN distribution.
675  
676 =back
677  
678 =head1 ENCODING
679  
680 The module works with B<bytes>, not with decoded text. It never decodes or
681 encodes anything itself.
682  
683 =over 4
684  
685 =item * B<Datagrams> (C<parse_message()>, C<process()>, and everything that
686 C<run()> receives) can contain any bytes. UTF-8 text, other non-ASCII text
687 and emoji are written to the file exactly as they arrived. Invalid UTF-8 is
688 also written unchanged. Only bytes 0x00 to 0x1F and 0x7F are changed (to
689 C<\xNN>). Bytes 0x80 to 0x9F are not changed, so a UTF-8 character is never
690 broken.
691  
692 =item * If you call C<parse_message()> or C<process()> yourself with a Perl
693 I<character> string (text that came from C<decode()>, or that contains a
694 character above 255, such as an emoji written as C<"\x{1F600}">), first
695 encode it to bytes, for example with C<Encode::encode('UTF-8', $text)>.
696 Otherwise Perl prints a "Wide character" warning when the line is written.
697  
698 =item * B<The file name> (C<file>) is passed to the operating system as
699 bytes. A name with non-ASCII characters must be given as encoded bytes
700 (normally UTF-8 on Unix).
701  
702 =item * B<Host names> come from the system resolver. An international domain
703 name normally arrives in its ASCII form (C<xn--...>).
704  
705 =item * B<The language tag> (C<language>) must be ASCII, for example C<en-gb>.
706  
707 =item * B<Messages from i18n()> are Perl strings. The English messages are
708 ASCII, but a value you pass in (for example a file name) is copied into the
709 message as it is. If you print a message that contains wide characters,
710 set an output layer first: C<binmode(STDOUT, ':encoding(UTF-8)')>.
711  
712 =back
713  
714 =head1 COMMON PITFALLS
715  
716 =over 4
717  
718 =item * B<undef means "use the default".> C<< new(file => undef) >> gives the
719 default file, not an empty file name. This is useful when you pass options
720 straight from L<Getopt::Long>, but it means you cannot use C<undef> to switch
721 something off. To turn off host names, use C<< resolve => 0 >>.
722  
723 =item * B<The environment wins over your arguments.> An
724 C<App__Syslogd__port> environment variable, or a configuration file, changes
725 the port even when you pass C<port> to C<new()>. This is how
726 L<Object::Configure> works. Check the environment when a setting seems to
727 be ignored.
728  
729 =item * B<The options are merged one level deep only.> Each option you give
730 replaces the default with the same name; nothing is merged inside a value.
731 Objects you pass (C<cache>, C<socket>) are shared, not copied: two servers
732 given the same C<cache> object share their host name answers.
733  
734 =item * B<True and false.> C<resolve> accepts 1, 0, and the words C<true>,
735 C<false>, C<yes>, C<no>, C<on> and C<off>. Any other value, such as 2, is an
736 error.
737  
738 =item * B<Order of calls.> C<process()> needs an open log, so call
739 C<reopen_log()> first. C<run()> opens the socket and the log by itself if
740 you have not.
741  
742 =item * B<Signals are handled only inside run().> Before C<run()> starts and
743 after it returns, SIGHUP has its normal effect, which is to end the program.
744 C<run()> puts back your own signal handlers when it returns.
745  
746 =item * B<stop() before run() does nothing.> C<run()> sets the "running"
747 flag when it starts, so an earlier C<stop()> is forgotten.
748  
749 =item * B<run() closes everything when it returns.> If you call C<run()>
750 again, it opens a new socket. With C<< port => 0 >>, the new socket can get
751 a different port number.
752  
753 =item * B<A failed reopen stops run().> If SIGHUP arrives and the log file
754 cannot be opened (for example, the directory was removed), C<run()> dies
755 with the error. The socket stays open and the log stays closed.
756  
757 =item * B<An existing log file is made private.> C<reopen_log()> changes the
758 file's permissions to 0600 without asking (except on Windows; see
759 L</LIMITATIONS>).
760  
761 =item * B<Do not rotate with copytruncate.> Emptying the log in place
762 leaves the server writing rows with no column names, and the next reopen
763 then refuses the file. Rename and send SIGHUP instead (see
764 L</SAMPLE CONFIGURATION>).
765  
766 =item * B<Only an empty file or one of its own logs is accepted.> A file
767 with content must start with the line C<"Host","facility","severity","msg">
768 (with a Unix or Windows line end), or C<reopen_log()> refuses it and leaves
769 it untouched. Logs from older versions start with that line too. To reuse
770 a file that does not, empty it or remove it first.
771  
772 =item * B<A short datagram is ignored silently.> After removing line endings
773 at the end, a datagram must have at least 2 characters. C<parse_message()>
774 then returns C<undef>, and C<process()> writes nothing and does not count it.
775  
776 =item * B<A missing sender is not an error.> C<process($datagram, undef)>
777 writes the message with an empty Host column.
778  
779 =item * B<port() and address() change meaning.> Before C<open_socket()> they
780 return what you asked for. After it they return what the system actually
781 gave, so C<< port => 0 >> becomes a real port number.
782  
783 =item * B<Backslashes are not escaped.> A message that really contains the
784 four characters C<\x0A> looks the same in the file as an escaped newline.
785  
786 =back
787  
788 =head1 METHODS
789  
790 Every method except C<parse_message()> and C<i18n()> needs an object made by
791 C<new()>; those two also work on the class. Methods that have nothing
792 useful to return give back the object, so you can chain calls:
793  
794 App::Syslogd->new(port => 5514)->open_socket()->reopen_log()->run();
795  
796 No method changes the caller's C<$_>, C<$!> or C<$@>, or an C<alarm()>
797 that is counting down. (A method that dies sets C<$@>, as C<die> always
798 does.)
799  
800 The mathematical description of each method is in
801 L</FORMAL SPECIFICATION>, and the life cycle of an object is in
802 L</STATE DIAGRAM>, both at the end of this document.
803  
804 =head2 new
805  
806 Purpose: make a new server object. It does not open the network or the
807 file yet, so you can create and inspect it without any special permissions.
808  
809 Args: all optional, given as a list of pairs or as one hash reference. An
810 option given as C<undef> uses its default.
811  
812 Every option can also be set outside the program, through
813 L<Object::Configure>: in a configuration file (for example
814 F<~/.conf/app-syslogd.yml>), or in an environment variable named
815 C<App__Syslogd__> followed by the option, such as
816 C<App__Syslogd__port=5514>. B<Those settings win over the arguments given
817 to new()>. They are checked in exactly the same way as arguments.
818  
819 =over 4
820  
821 =item * C<port> - the UDP port number, 0 to 65535. Default 514. 0 means
822 "let the system choose a free port"; call C<port()> after C<open_socket()>
823 to find out which one.
824  
825 =item * C<address> - the local address to listen on. Default C<0.0.0.0> (all
826 IPv4 addresses). Use C<::> for IPv6.
827  
828 =item * C<file> - the CSV log file. Default F</var/log/syslog/syslog.csv>;
829 its directory must already exist.
830  
831 =item * C<resolve> - true (the default) to write host names, false to write
832 IP addresses.
833  
834 =item * C<dns_ttl> - how many seconds to remember a host name. Default 300.
835  
836 =item * C<dns_cache_bytes> - the most memory, in bytes, used to remember host
837 names. Default 262144. An estimate: see L<App::Syslogd::Cache/new>. It
838 does not apply to a C<cache> you supply.
839  
840 =item * C<language> - the language of messages, such as C<en>. Default: from
841 the environment.
842  
843 =item * C<cache> - your own cache for host names, instead of the built-in
844 L<App::Syslogd::Cache>. Any object with a L<CHI>-style C<compute()> method,
845 for example a L<CHI> cache shared between several servers.
846  
847 =item * C<socket> - a socket that is already open, instead of opening one.
848 Any object with a C<recv()> method.
849  
850 =back
851  
852 Returns: the new object. Besides the options, it holds the C<logger> (a
853 L<Log::Abstraction> object) and C<config_path> that L<Object::Configure>
854 provides.
855  
856 Side Effects: reads configuration files and environment variables (see
857 above). Does not open the network or the log. Dies if an option is
858 unknown, or if an option has a wrong value, wherever the value came from.
859  
860 Usage:
861  
862 my $server = App::Syslogd->new({ port => 514, resolve => 0 });
863  
864 =head3 EXAMPLE
865  
866 # Listen on a port that does not need root, and write addresses only
867 my $server = App::Syslogd->new(port => 5514, resolve => 0);
868  
869 # Options from Getopt::Long: options not given stay undef = default
870 my %opts;
871 GetOptions(\%opts, 'port=i', 'file=s');
872 my $server2 = App::Syslogd->new(\%opts);
873  
874 =head3 API SPECIFICATION
875  
876 =head4 INPUT
877  
878 {
879 port => { type => 'integer', min => 0, max => 65535, optional => 1 },
880 address => { type => 'string', min => 1, optional => 1 },
881 file => { type => 'string', min => 1, optional => 1 },
882 resolve => { type => 'boolean', optional => 1 },
883 dns_ttl => { type => 'integer', min => 0, optional => 1 },
884 dns_cache_bytes => { type => 'integer', min => 1, optional => 1 },
885 language => { type => 'string', min => 1, optional => 1 },
886 cache => { type => 'object', can => ['compute'], optional => 1 },
887 socket => { type => 'object', can => ['recv'], optional => 1 },
888 }
889  
890 Domains (equivalence partitions and boundaries; t/domain.t tests each):
891  
892 +-----------------+--------------------------------+-----------------------+-------------------------------+
893 | Option | Valid partitions | Boundaries | Invalid partitions |
894 +-----------------+--------------------------------+-----------------------+-------------------------------+
895 | port | 0 (the kernel chooses); | -1 no, 0 yes, | fractions (514.5), hex |
896 | | 1-1023 (needs root); | 65535 yes, 65536 no | (0x10), "1_000", text, "", |
897 | | 1024-65535. A numeric string | | non-ASCII digits, references |
898 | | is read as its number: " 514 ",| | |
899 | | "+514", "0514", "5e2", "5.0" | | |
900 | address | IPv4 or IPv6 literal, or a | 1 character is | "" (new()); an address this |
901 | | host name: any non-empty | accepted by new() | machine does not have (fails |
902 | | string here | | in open_socket()) |
903 | file | any non-empty string of bytes; | 1 byte; the system's | ""; references. A name over |
904 | | non-ASCII names as encoded | name limit (usually | the system limit, or an |
905 | | (UTF-8) bytes | 255 bytes) | existing file with content |
906 | | | | that does not start with the |
907 | | | | header, fails in reopen_log() |
908 | resolve | true: 1 true TRUE yes on; | - | any other spelling: "", 2, |
909 | | false: 0 false FALSE no off | | "Yes", "On", " 1", "t" |
910 | dns_ttl | whole seconds, 0 or more (0: | -1 no, 0 yes; no | fractions, text, references |
911 | | names are not reused) | upper limit | |
912 | dns_cache_bytes | whole bytes, 1 or more | 0 no, 1 yes; no upper | fractions, text, references |
913 | | | limit | |
914 | language | any non-empty tag; tags with | 1 character is | "" (refused); unknown or |
915 | | no lexicon (fr, x, i-klingon) | accepted | malformed tags are not an |
916 | | fall back to English | | error: they give English |
917 | cache, socket | an object with compute() / | - | plain hashes, code, globs, an |
918 | | recv() | | object without the method |
919 +-----------------+--------------------------------+-----------------------+-------------------------------+
920  
921 C<address>, C<file> and C<language> must not contain a NUL byte (refused:
922 "must match pattern"): the C library would stop reading at the NUL, so the
923 server would bind or write somewhere other than the value it reports.
924  
925 An undef value is in no partition: it means "use the default". Options
926 are checked one by one, so the error names the first invalid option even
927 when the others are at their limits.
928  
929 =head4 OUTPUT
930  
931 { type => 'object', isa => 'App::Syslogd' }
932  
933 =head3 MESSAGES
934  
935 +------------------------------------+--------------------------+-----------------------------+
936 | Message (dies) | Meaning | What to do |
937 +------------------------------------+--------------------------+-----------------------------+
938 | validate_strict: Unknown parameter | An option name is wrong | Check the spelling against |
939 | 'x' | | the list above |
940 | validate_strict: Parameter 'port' | A value is the wrong | Use a whole number from 0 |
941 | (x) must be an integer | type | to 65535 |
942 | validate_strict: Parameter 'port' | A number is out of range | Use a value inside the |
943 | (x) must be no more than 65535 | | range shown above |
944 | validate_strict: Parameter 'X' | A number is below its | Use a value inside the |
945 | (x) must be at least 0, or must | minimum (port, dns_ttl | range in the Domains |
946 | be a positive number | at 0; dns_cache_bytes | table |
947 | | at 1) | |
948 | validate_strict: Parameter | Not a true/false value | Use 1, 0, true, false, yes, |
949 | 'resolve' (x) must be a boolean | | no, on, off, TRUE, FALSE |
950 | validate_strict: Parameter 'X' | address, file or language| Remove the NUL byte |
951 | (x) must match pattern ... | contains a NUL byte | |
952 +------------------------------------+--------------------------+-----------------------------+
953  
954 =head3 PSEUDOCODE
955  
956 check the options against the schema (die if one is wrong)
957 remove options whose value is undef
958 start from the defaults, then copy the options over them
959 set the message counter to 0
960 choose the message language
961 if no cache was given, make an in-memory cache
962 make the CSV writer
963 return the object
964  
965 =cut
966  
967 sub new
968 669 ▶{
Subroutine new: called CC=5 SCAR=16.1
Pod documented
969 669 my $class = shift;
970  
971 # Keep the caller's $! and $@: system calls and modules used below
972 # (Params::Validate::Strict, sockets, files) change them. A
973 # croak still reaches the caller: since Perl 5.14 die sets $@ after
974 # locals are restored.
975 669 local ($!, $@);
976  
977 # Check the caller's own arguments first, so that a misspelt option
978 # is reported as such. Accept a hash, a hashref or nothing at all.
979 669 ▶ my $params = Params::Validate::Strict::validate_strict({
Condition100%2/2
Params::Get::get_params(undef, \@_) || {}
l!l
61057
MC/DC100%1/1
Params::Get::get_params(undef, \@_) || {}
Params::Get::get_params(undef, \@_)
Truth table100%2/2
A
A= Params::Get::get_params(undef, \@_)
Aresult
11
00
980 schema => \%NEW_SCHEMA,
981 input => Params::Get::get_params(undef, \@_) || {},
982 });
983  
984 # Object::Configure merges in configuration files and App__Syslogd__*
985 # environment variables (which win over the arguments) and adds a
986 # logger. Settings from there are validated too: they used to go in
987 # unchecked, so App__Syslogd__port=70000 was accepted. Only the
988 # settings this module uses are checked and kept, plus the logger and
989 # config_path that Object::Configure provides; sections meant for other
990 # classes are dropped.
991 550 my $configured = Object::Configure::configure($class, { %{$params} });
992 my $args = Params::Validate::Strict::validate_strict({
993 schema => \%NEW_SCHEMA,
994 550 input => { map { $_ => $configured->{$_} } grep { exists($NEW_SCHEMA{$_}) } keys %{$configured} },
995 });
996 538 foreach my $key (@CONFIGURE_EXTRAS) {
997 1076 ▶ $args->{$key} = $configured->{$key} if(defined($configured->{$key}));
Branch: 1 branch
BranchTrueFalseTotal
if defined $configured->{$key} 537 539 1076
998 }
999  
1000 # An undef value means "use the default": without this,
1001 # new(file => undef) replaced the default with undef and failed later,
1002 # far from the mistake
1003 538 delete @{$args}{grep { !defined($args->{$_}) } keys %{$args}};
1004  
1005 # Caller's values win over defaults (a one-level merge: nothing nested)
1006 538 my $self = bless { %DEFAULTS, %{$args}, count => 0 }, $class;
1007  
1008 # One handle per object: two servers in one process may speak
1009 # different languages
1010 538 $self->{lh} = App::Syslogd::I18N->handle($self->{language});
1011  
1012 # Reverse DNS is synchronous; without a cache one slow resolver would
1013 # stall the receive loop for every packet from that host. The built-in
1014 # cache answers a hit with one hash lookup (a CHI Memory cache took
1015 # about 17 microseconds, a third of the time per datagram); a CHI
1016 # object can still be passed in as "cache".
1017 538 ▶ $self->{cache} ||= App::Syslogd::Cache->new(max_bytes => $self->{dns_cache_bytes});
Condition100%3/3
$self->{"cache"} ||= "App::Syslogd::Cache"->new("max_bytes", $self->{"dns_cache_bytes"})
l!l&&r!l&&!r
404971
MC/DC100%2/2
$self->{"cache"} ||= "App::Syslogd::Cache"->new("max_bytes", $self->{"dns_cache_bytes"})
$self->{"cache"} "App::Syslogd::Cache"->new("max_bytes", $self->{"dns_cache_bytes"})
Truth table100%3/3
A ||= B
A= $self->{"cache"}B= "App::Syslogd::Cache"->new("max_bytes", $self->{"dns_cache_bytes"})
ABresult
1X1
011
000
1018  
1019 # binary => 1 permits non-ASCII bytes; always_quote matches the
1020 # header row style the original script wrote
1021 538 $self->{csv} = Text::CSV->new({ binary => 1, eol => "\n", always_quote => 1 });
1022  
1023 538 return $self;
1024 }
1025  
1026 =head2 open_socket
1027  
1028 Purpose: start listening for UDP datagrams on the configured address and
1029 port. If the port is below 1024, do this before your program gives up root.
1030  
1031 Args: none.
1032  
1033 Returns: the object, so you can chain another call.
1034  
1035 Side Effects: opens a UDP socket. Does nothing if a socket is already open,
1036 including one given to C<new()>.
1037  
1038 Usage:
1039  
1040 $server->open_socket();
1041  
1042 =head3 EXAMPLE
1043  
1044 # Let the system choose a free port, then ask which one it chose
1045 my $server = App::Syslogd->new(port => 0)->open_socket();
1046 print 'Listening on port ', $server->port(), "\n";
1047  
1048 =head3 API SPECIFICATION
1049  
1050 =head4 INPUT
1051  
1052 {}
1053  
1054 =head4 OUTPUT
1055  
1056 { type => 'object', isa => 'App::Syslogd' }
1057  
1058 =head3 MESSAGES
1059  
1060 +---------------------------------+---------------------------+------------------------------+
1061 | Message (dies) | Meaning | What to do |
1062 +---------------------------------+---------------------------+------------------------------+
1063 | Could not create a UDP socket | The system refused: the | Run as root for ports below |
1064 | on ADDR port N: ERROR | port is in use, needs | 1024, stop the other |
1065 | | root, or the address is | syslog server, or correct |
1066 | | wrong | the address |
1067 +---------------------------------+---------------------------+------------------------------+
1068  
1069 =cut
1070  
1071 sub open_socket
1072 154 ▶{
Subroutine open_socket: called CC=4 SCAR=13.9
Pod documented
1073 154 my $self = shift;
1074  
1075 # Keep the caller's $! and $@ (see new()). $IO::Socket::errstr is a
1076 # global too: start it empty, or a constructor that fails without
1077 # setting it would report an older, unrelated socket error.
1078 154 local ($!, $@);
1079 154 local $IO::Socket::errstr = '';
1080  
1081 # IO::Socket::IP handles both families; IO::Socket::INET is IPv4-only
1082 $self->{socket} ||= IO::Socket::IP->new(
1083 LocalHost => $self->{address},
1084 LocalPort => $self->{port},
1085 Proto => 'udp',
1086 ) || croak($self->i18n('socket_failed', {
1087 address => $self->{address},
1088 port => $self->{port},
1089 154 ▶ error => $IO::Socket::errstr || "$!",
Condition100%8/8
$self->{"socket"} ||= "IO::Socket::IP"->new("LocalHost", $self->{"address"}, "LocalPort", $self->{"port"}, "Proto", "udp") || croak($self->i18n("socket_failed", {"address", $self->{"address"}, "port", $self->{"port"}, "error", $IO::Socket::errstr || "$!"}))
l!l&&r!l&&!r
736417
'IO::Socket::IP'->new('LocalHost', $self->{'address'}, 'LocalPort', $self->{'port'}, 'Proto', 'udp') || croak($self->i18n('socket_failed', {'address', $self->{'address'}, 'port', $self->{'port'}, 'error', $IO::Socket::errstr || "$!"}))
l!l
4041
$IO::Socket::errstr || "$!"
l!l&&r!l&&!r
3434
MC/DC100%2/2
$self->{"socket"} ||= "IO::Socket::IP"->new("LocalHost", $self->{"address"}, "LocalPort", $self->{"port"}, "Proto", "udp") || croak($self->i18n("socket_failed", {"address", $self->{"address"}, "port", $self->{"port"}, "error", $IO::Socket::errstr || "$!"}))
$self->{"socket"} 'IO::Socket::IP'->new('LocalHost', $self->{'address'}, 'LocalPort', $self->{'port'}, 'Proto', 'udp')
MC/DC100%2/2
$IO::Socket::errstr || "$!"
$IO::Socket::errstr "$!"
Truth table100%3/3
A ||= B
A= $self->{"socket"}B= 'IO::Socket::IP'->new('LocalHost', $self->{'address'}, 'LocalPort', $self->{'port'}, 'Proto', 'udp')
ABresult
1X1
011
000
Truth table100%3/3
A || B
A= $IO::Socket::errstrB= "$!"
ABresult
1X1
011
000
1090 }));
1091  
1092 113 return $self;
1093 }
1094  
1095 =head2 port
1096  
1097 Purpose: tell you the UDP port number.
1098  
1099 Args: none.
1100  
1101 Returns: a whole number from 0 to 65535. Before C<open_socket()> it is the
1102 port you asked for. After it, it is the port really in use, so
1103 C<< port => 0 >> becomes the number the system chose. If the socket was
1104 given to C<new()> and has no C<sockport()> method (a simple test double, for
1105 example), it is the port you asked for.
1106  
1107 Side Effects: none.
1108  
1109 Usage:
1110  
1111 my $port = $server->port();
1112  
1113 =head3 EXAMPLE
1114  
1115 print App::Syslogd->new()->port(), "\n"; # 514
1116  
1117 =head3 API SPECIFICATION
1118  
1119 =head4 INPUT
1120  
1121 {}
1122  
1123 =head4 OUTPUT
1124  
1125 { type => 'integer', min => 0, max => 65535 }
1126  
1127 Domain: 0 to 65535. 0 only before open_socket() with C<< port => 0 >>;
1128 after open_socket(), 1 to 65535.
1129  
1130 =head3 MESSAGES
1131  
1132 None.
1133  
1134 =cut
1135  
1136 sub port
1137 68 ▶{
Subroutine port: called CC=3 SCAR=11.0
Pod documented
1138 68 my $self = shift;
1139  
1140 # An injected test socket may not know its port, so ask only real ones
1141 68 my $socket = $self->{socket};
1142  
1143 68 ▶ return ($socket && $socket->can('sockport')) ? $socket->sockport() : $self->{port};
Branch: 1 branch
BranchTrueFalseTotal
$socket && $socket->can('sockport') ? : 20 48 68
Condition100%3/3
$socket and $socket->can("sockport")
!ll&&!rl&&r
44420
MC/DC100%2/2
$socket and $socket->can("sockport")
$socket $socket->can("sockport")
Truth table100%3/3
A and B
A= $socketB= $socket->can("sockport")
ABresult
0X0
100
111
1144 }
1145  
1146 =head2 address
1147  
1148 Purpose: tell you the local address the server listens on.
1149  
1150 Args: none.
1151  
1152 Returns: a string, such as C<0.0.0.0> or C<::1>. Before C<open_socket()> it
1153 is the address you asked for. After it, it is the address the system reports.
1154 If the socket was given to C<new()> and has no C<sockhost()> method, it is
1155 the address you asked for.
1156  
1157 Side Effects: none.
1158  
1159 Usage:
1160  
1161 my $address = $server->address();
1162  
1163 =head3 EXAMPLE
1164  
1165 print App::Syslogd->new(address => '::')->address(), "\n"; # ::
1166  
1167 =head3 API SPECIFICATION
1168  
1169 =head4 INPUT
1170  
1171 {}
1172  
1173 =head4 OUTPUT
1174  
1175 { type => 'string', min => 1 }
1176  
1177 =head3 MESSAGES
1178  
1179 None.
1180  
1181 =cut
1182  
1183 sub address
1184 33 ▶{
Subroutine address: called CC=3 SCAR=11.0
Pod documented
1185 33 my $self = shift;
1186  
1187 # Mirrors port(): injected test sockets need not know their address
1188 33 my $socket = $self->{socket};
1189  
1190 33 ▶ return ($socket && $socket->can("sockhost")) ? $socket->sockhost() : $self->{address};
Branch: 1 branch
BranchTrueFalseTotal
$socket && $socket->can('sockhost') ? : 11 22 33
Condition100%3/3
$socket and $socket->can("sockhost")
!ll&&!rl&&r
18411
MC/DC100%2/2
$socket and $socket->can("sockhost")
$socket $socket->can("sockhost")
Truth table100%3/3
A and B
A= $socketB= $socket->can("sockhost")
ABresult
0X0
100
111
1191 }
1192  
1193 =head2 count
1194  
1195 Purpose: tell you how many datagrams have been written to the log.
1196  
1197 Args: none.
1198  
1199 Returns: a whole number, 0 or more. Ignored datagrams (shorter than 2
1200 characters) are not counted. A datagram that could not be written because
1201 the disk was full is counted.
1202  
1203 Side Effects: none.
1204  
1205 Usage:
1206  
1207 print $server->count(), " messages\n";
1208  
1209 =head3 EXAMPLE
1210  
1211 $server->reopen_log()->process('<13>hello', $peer);
1212 print $server->count(), "\n"; # 1
1213  
1214 =head3 API SPECIFICATION
1215  
1216 =head4 INPUT
1217  
1218 {}
1219  
1220 =head4 OUTPUT
1221  
1222 { type => 'integer', min => 0 }
1223  
1224 Domain: 0 or more; it only ever grows, by one for each datagram that was
1225 not too short.
1226  
1227 =head3 MESSAGES
1228  
1229 None.
1230  
1231 =cut
1232  
1233 sub count
1234 65 ▶{
Subroutine count: called CC=1 SCAR=0.0
Pod documented
1235 65 my $self = shift;
1236  
1237 65 return $self->{count};
1238 }
1239  
1240 =head2 reopen_log
1241  
1242 Purpose: open the CSV log file, closing it first if it is already open. Use
1243 it once at the start. C<run()> also calls it when SIGHUP arrives, so that
1244 after a log rotation tool renames the file, a new file is started.
1245  
1246 Args: none.
1247  
1248 Returns: the object, so you can chain another call.
1249  
1250 Side Effects:
1251  
1252 =over 4
1253  
1254 =item * Closes the log file if it is open.
1255  
1256 =item * Creates the file if it does not exist, readable only by its owner.
1257  
1258 =item * Writes the column names if the file is empty.
1259  
1260 =item * Refuses (and does not change) a file with content that does not
1261 start with the column names: only the server's own logs are reused.
1262  
1263 =item * Changes an existing file's permissions to 0600 (not on Windows),
1264 after the checks above.
1265  
1266 =item * Dies, leaving no log open, if the file cannot be used safely.
1267  
1268 =back
1269  
1270 Usage:
1271  
1272 $server->reopen_log();
1273  
1274 =head3 EXAMPLE
1275  
1276 # Open the log before starting, so that a problem is reported at once
1277 my $server = App::Syslogd->new(file => '/var/log/remote.csv');
1278 eval { $server->reopen_log(); 1 } or die "Cannot start: $@";
1279  
1280 =head3 API SPECIFICATION
1281  
1282 =head4 INPUT
1283  
1284 {}
1285  
1286 =head4 OUTPUT
1287  
1288 { type => 'object', isa => 'App::Syslogd' }
1289  
1290 =head3 MESSAGES
1291  
1292 +-------------------------------+--------------------------------+-------------------------------+
1293 | Message (dies) | Meaning | What to do |
1294 +-------------------------------+--------------------------------+-------------------------------+
1295 | Could not open log file F: | The system could not open the | Create the directory, or fix |
1296 | ERROR | file. ERROR is the system's | its permissions. Remove a |
1297 | | reason. A symbolic link, a | symbolic link or FIFO; give |
1298 | | directory or a FIFO (named | a file name, not a |
1299 | | pipe) also gives this | directory. Give a regular |
1300 | | message. So does a device | file for a device |
1301 | | file such as /dev/urandom | |
1302 | | when the system will not | |
1303 | | open it for writing (an | |
1304 | | ordinary user may not; on | |
1305 | | FreeBSD it is a symbolic | |
1306 | | link). Otherwise a device | |
1307 | | gets the "Refusing" message | |
1308 | | below | |
1309 | Refusing to log to F: it must | F is a hard link or another | Remove F and let the server |
1310 | be a regular file, owned by | user's file | create it again |
1311 | this user, with exactly one | | |
1312 | link | | |
1313 | Refusing to log to F: it is | F has content but is not one | Check the file setting; empty |
1314 | not empty and does not | of the server's logs (it | or remove F if it really is |
1315 | start with the syslog | does not start with the | meant to be the log |
1316 | header line | column names) | |
1317 | Could not write to log file | The column names could not be | Free some disk space |
1318 | F: ERROR | written to a new file | |
1319 +-------------------------------+--------------------------------+-------------------------------+
1320  
1321 =cut
1322  
1323 sub reopen_log
1324 305 ▶{
Subroutine reopen_log: called CC=1 SCAR=0.0
Pod documented
1325 305 my $self = shift;
1326  
1327 # Keep the caller's $! and $@ (see new())
1328 305 local ($!, $@);
1329  
1330 # Closing first means a failed reopen leaves no stale handle that
1331 # would silently keep writing to the rotated file
1332 305 $self->_close_log();
1333 305 $self->{fh} = $self->_open_log();
1334  
1335 228 return $self;
1336 }
1337  
1338 =head2 parse_message
1339  
1340 Purpose: split one datagram into its facility, severity and message text.
1341 It uses no state and writes nothing, so you can call it on the class and use
1342 it on its own.
1343  
1344 Args: one datagram, as a string of bytes.
1345  
1346 Returns: C<undef> if the datagram is too short to be a message (fewer than 2
1347 characters after removing line endings at the end). Otherwise a hash
1348 reference with these keys:
1349  
1350 =over 4
1351  
1352 =item * C<facility> - 0 to 23.
1353  
1354 =item * C<severity> - 0 to 7.
1355  
1356 =item * C<message> - the text after the PRI, with control characters
1357 written as C<\xNN>.
1358  
1359 =item * C<valid> - 1 if the datagram had a valid PRI. 0 if not; then facility
1360 is 1, severity is 5, and C<message> is the whole datagram.
1361  
1362 =back
1363  
1364 Side Effects: none.
1365  
1366 Usage:
1367  
1368 my $record = App::Syslogd->parse_message($datagram);
1369  
1370 =head3 EXAMPLE
1371  
1372 my $r = App::Syslogd->parse_message("<34>su: 'su root' failed\n");
1373 # { facility => 4, severity => 2, message => "su: 'su root' failed", valid => 1 }
1374  
1375 $r = App::Syslogd->parse_message("no pri\there");
1376 # { facility => 1, severity => 5, message => 'no pri\x09here', valid => 0 }
1377  
1378 $r = App::Syslogd->parse_message("x\n");
1379 # undef: too short
1380  
1381 =head3 API SPECIFICATION
1382  
1383 =head4 INPUT
1384  
1385 {
1386 datagram => { type => 'string', optional => 1, position => 0 },
1387 }
1388  
1389 Domains of the datagram (C<message> is the part after the PRI):
1390  
1391 +-----------------+-----------------------------------+----------------------------------+
1392 | Partition | Examples | Result |
1393 +-----------------+-----------------------------------+----------------------------------+
1394 | too short | undef, "", "x", "x\n" (fewer than | undef |
1395 | | 2 characters after removing | |
1396 | | trailing CR, LF and NUL) | |
1397 | valid PRI | "<0>" to "<191>", no extra | facility = PRI div 8 (0-23), |
1398 | | leading zeros | severity = PRI mod 8 (0-7), |
1399 | | | valid 1 |
1400 | invalid PRI | "<192>", "<013>", "<1000>", "<>", | facility 1, severity 5, the |
1401 | | no PRI at all | whole text, valid 0 |
1402 | control bytes | 0x00-0x1F and 0x7F | written as \xNN |
1403 | other bytes | UTF-8 (umlauts, emoji, combining | unchanged, same length |
1404 | | "Zalgo" marks, the RTL override | |
1405 | | U+202E), invalid UTF-8, C1 bytes | |
1406 | references | [], {}, code, globs | dies: A datagram must be a |
1407 | | | string ... |
1408 +-----------------+-----------------------------------+----------------------------------+
1409  
1410 Boundaries: length 1 gives undef and 2 gives a record; PRI 191 is valid and
1411 192 is not; PRI 7/8, 15/16, ... are the edges between facilities. The
1412 largest UDP datagram (65535 bytes) is accepted whole.
1413  
1414 =head4 OUTPUT
1415  
1416 {
1417 type => 'hashref',
1418 optional => 1,
1419 schema => {
1420 facility => { type => 'integer', min => 0, max => 23 },
1421 severity => { type => 'integer', min => 0, max => 7 },
1422 message => { type => 'string', matches => qr/\A[^\x00-\x1F\x7F]*\z/ },
1423 valid => { type => 'boolean' },
1424 },
1425 }
1426  
1427 =head3 MESSAGES
1428  
1429 +------------------------------------+------------------------------+-----------------------------+
1430 | Message (dies) | Meaning | What to do |
1431 +------------------------------------+------------------------------+-----------------------------+
1432 | A datagram must be a string (the | A reference was passed; it | Pass the received bytes |
1433 | type given was TYPE) | would have been recorded | |
1434 | | as "ARRAY(0x...)" | |
1435 +------------------------------------+------------------------------+-----------------------------+
1436  
1437 A malformed string is recorded, never rejected. An object that turns
1438 itself into a string (overloads C<"">) is accepted as that string.
1439  
1440 =head3 PSEUDOCODE
1441  
1442 treat undef as an empty string
1443 remove CR, LF and NUL characters from the end
1444 if fewer than 2 characters remain: return undef
1445 if the text is "<" NUMBER ">" REST, where NUMBER is 0 to 191
1446 written without extra leading zeros:
1447 valid = 1
1448 else:
1449 NUMBER = 13, REST = the whole text, valid = 0
1450 return {
1451 facility => NUMBER divided by 8, rounded down,
1452 severity => remainder of NUMBER divided by 8,
1453 message => REST with control characters written as \xNN,
1454 valid => valid,
1455 }
1456  
1457 =cut
1458  
1459 sub parse_message
1460 457 ▶{
Subroutine parse_message: called CC=9 SCAR=22.0
Pod documented
1461 457 my ($self, $datagram) = @_;
1462  
1463 # A reference would be logged as "ARRAY(0x...)"; only a string (or an
1464 # object that turns itself into one) is a datagram
1465 457 ▶ if(ref($datagram) && !overload::Method($datagram, q{""})) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $datagram and not overload::Method($datagram, "\"\"")) 17 440 457
Condition100%3/3
ref $datagram and not overload::Method($datagram, "\"\"")
!ll&&!rl&&r
436417
MC/DC100%2/2
ref $datagram and not overload::Method($datagram, "\"\"")
ref $datagram not overload::Method($datagram, "\"\"")
Truth table100%3/3
A and not(B)
A= ref $datagramB= not overload::Method($datagram, "\"\"")
ABresult
0X0
100
111
1466 17 ▶ croak(($self // __PACKAGE__)->i18n('not_a_datagram', { type => ref($datagram) }));
Condition100%2/2
$self // __PACKAGE__
l!l
161
MC/DC100%1/1
$self // __PACKAGE__
$self
Truth table100%2/2
A
A= $self
Aresult
11
00
1467 }
1468  
1469 # Senders disagree about terminators: "\n", "\r\n" and "\0" are all seen
1470 440 ▶ (my $text = $datagram // '') =~ s/[\r\n\0]+\z//;
Condition100%2/2
$datagram // ""
l!l
4346
MC/DC100%1/1
$datagram // ""
$datagram
Truth table100%2/2
A
A= $datagram
Aresult
11
00
1471  
1472 440 ▶ return undef if(length($text) < $MIN_MESSAGE_LENGTH); ## no critic (ProhibitExplicitReturnUndef): documented, also in list context
Branch: 1 branch
BranchTrueFalseTotal
if length $text < $MIN_MESSAGE_LENGTH 47 393 440
1473  
1474 # The PRI and the body, as RFC 5424 6.2.1 writes them. Linear on
1475 # any input: anchored at the start, the digits capped at three, and
1476 # the body taken in one greedy step to the end.
1477 393 my @match = $text =~ m{
1478 \A
1479 < # a PRI starts with "<"
1480 ( # capture 1: the PRI number
1481 0 # "0" on its own (no other leading zero)
1482 | [1-9] [0-9]{0,2} # or 1 to 3 digits; <= 191 is checked below
1483 )
1484 > # and ends with ">"
1485 (.*) # capture 2: the body, newlines included (/s)
1486 \z
1487 }xs;
1488 393 ▶ my $valid = (@match && ($match[0] <= $MAX_PRI)) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
@match && $match[0] <= $MAX_PRI ? : 314 79 393
Condition100%3/3
@match and $match[0] <= $MAX_PRI
!ll&&!rl&&r
6415314
MC/DC100%2/2
@match and $match[0] <= $MAX_PRI
@match $match[0] <= $MAX_PRI
Truth table100%3/3
A and B
A= @matchB= $match[0] <= $MAX_PRI
ABresult
0X0
100
111
1489  
1490 # RFC 3164 4.3.3: keep the whole datagram rather than discarding it.
1491 # Each value is assigned once, from the right source.
1492 393 ▶ my ($pri, $body) = $valid ? @match : ($DEFAULT_PRI, $text);
Branch: 1 branch
BranchTrueFalseTotal
$valid ? : 314 79 393
1493  
1494 return {
1495 393 facility => int($pri / $SEVERITIES_PER_FACILITY),
1496 severity => $pri % $SEVERITIES_PER_FACILITY,
1497 message => _escape_controls($body),
1498 valid => $valid,
1499 };
1500 }
1501  
1502 =head2 process
1503  
1504 Purpose: write one received datagram to the log.
1505  
1506 Args:
1507  
1508 =over 4
1509  
1510 =item 1. The datagram, as a string of bytes.
1511  
1512 =item 2. The sender's address, in the packed form that C<recv()> returns.
1513 C<undef>, or anything that is not a packed address (such as a reference),
1514 gives an empty Host column.
1515  
1516 =back
1517  
1518 Returns: the object, so you can chain another call.
1519  
1520 Side Effects:
1521  
1522 =over 4
1523  
1524 =item * May look up the sender's host name (the answer is remembered). If
1525 the cache fails (dies) or gives no answer, the IP address is written: a cache
1526 problem never stops the logging.
1527  
1528 =item * Adds one line to the log and adds 1 to C<count()>, unless the
1529 datagram is too short, in which case nothing happens.
1530  
1531 =item * If the line cannot be written (for example, the disk is full), it
1532 warns and continues. That message is lost, but the server keeps working.
1533 If only part of the line fitted, the part is removed again, so the file
1534 never holds a half line and the next message starts on a line of its own.
1535  
1536 =back
1537  
1538 Usage:
1539  
1540 my $peer = $socket->recv(my $datagram, 65535);
1541 $server->process($datagram, $peer);
1542  
1543 =head3 EXAMPLE
1544  
1545 use Socket qw(pack_sockaddr_in inet_aton);
1546  
1547 my $peer = pack_sockaddr_in(514, inet_aton('192.0.2.1'));
1548 $server->reopen_log()->process('<13>hello', $peer);
1549 # The file now ends with: "192.0.2.1","1","5","hello"
1550  
1551 =head3 API SPECIFICATION
1552  
1553 =head4 INPUT
1554  
1555 {
1556 datagram => { type => 'string', optional => 1, position => 0 },
1557 peer => { type => 'string', optional => 1, position => 1 },
1558 }
1559  
1560 Domains of the sender: a packed IPv4 or IPv6 address gives that address
1561 (or its name); undef, "", short or garbage strings and references give an
1562 empty Host. The datagram has the domains listed under L</parse_message>.
1563  
1564 =head4 OUTPUT
1565  
1566 { type => 'object', isa => 'App::Syslogd' }
1567  
1568 =head3 MESSAGES
1569  
1570 +-----------------------------------+------------------------------+-------------------------------+
1571 | Message | Meaning | What to do |
1572 +-----------------------------------+------------------------------+-------------------------------+
1573 | process() was called before | No log file is open (dies) | Call reopen_log() first |
1574 | reopen_log() succeeded | | |
1575 | A datagram must be a string (the | The datagram was a reference | Pass the received bytes |
1576 | type given was TYPE) | (dies) | |
1577 | Could not write to log file F: | The line was not written, | Free disk space; this message |
1578 | ERROR | e.g. disk full, or the CSV | is lost, later ones are not |
1579 | | writer refused (warning) | |
1580 +-----------------------------------+------------------------------+-------------------------------+
1581  
1582 =cut
1583  
1584 sub process
1585 265 ▶{
Subroutine process: called CC=3 SCAR=11.0
Pod documented
1586 265 my ($self, $datagram, $peer) = @_;
1587  
1588 # Keep the caller's $! and $@ (see new())
1589 265 local ($!, $@);
1590  
1591 265 ▶ croak($self->i18n('no_log_open')) unless($self->{fh});
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"fh"} 13 252 265
1592  
1593 # Too-short datagrams are dropped quietly, as the original script did
1594 252 ▶ if(my $record = $self->parse_message($datagram)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $record = $self->parse_message($datagram)) 237 14 251
1595 # Escaped like the message: a reverse-DNS (PTR) name is chosen by
1596 # whoever controls the sender's address and may hold newlines or
1597 # terminal escape sequences. Done here rather than in
1598 # _peer_name(), so that a subclass's override is covered too.
1599 237 my $host = _escape_controls($self->_peer_name($peer));
1600 237 $self->_write_row([$host, @{$record}{qw(facility severity message)}]);
1601 237 $self->{count}++;
1602 }
1603  
1604 251 return $self;
1605 }
1606  
1607 =head2 run
1608  
1609 Purpose: the main loop. Wait for datagrams and write each one to the log,
1610 until told to stop.
1611  
1612 Args: none.
1613  
1614 Returns: the object, after SIGTERM, SIGINT or C<stop()>.
1615  
1616 Side Effects:
1617  
1618 =over 4
1619  
1620 =item * Calls C<open_socket()> and C<reopen_log()> first if they have not been
1621 called. The socket comes first, so if it cannot be opened, C<run()> dies
1622 before the log file is touched. Starting is all or nothing: if the log
1623 cannot be opened, a socket that C<run()> opened itself is closed again
1624 before C<run()> dies (a socket you opened, or gave to C<new()>, is left
1625 open).
1626  
1627 Why the loop never checks for a socket: C<open_socket()> either gives a
1628 socket or dies (premise 1); the loop only starts after it (premise 2); so
1629 inside the loop the socket always exists (conclusion).
1630  
1631 =item * While it runs: SIGHUP reopens the log, and SIGTERM or SIGINT stop the
1632 loop. Your own handlers for these three signals are put back when it
1633 returns.
1634  
1635 =item * When it returns, the socket and the log file are closed.
1636  
1637 =back
1638  
1639 Usage:
1640  
1641 $server->run();
1642  
1643 =head3 EXAMPLE
1644  
1645 my $server = App::Syslogd->new(port => 5514, file => '/var/log/remote.csv');
1646 $server->run(); # Ctrl-C to stop
1647 print $server->i18n('shutdown', { count => $server->count() }), "\n";
1648 # Syslog server shutting down after recording 42 messages
1649  
1650 =head3 API SPECIFICATION
1651  
1652 =head4 INPUT
1653  
1654 {}
1655  
1656 =head4 OUTPUT
1657  
1658 { type => 'object', isa => 'App::Syslogd' }
1659  
1660 =head3 MESSAGES
1661  
1662 +---------------------------------+--------------------------------+------------------------------+
1663 | Message | Meaning | What to do |
1664 +---------------------------------+--------------------------------+------------------------------+
1665 | Error receiving a datagram: | Reading from the network | Usually nothing: the loop |
1666 | ERROR | failed (warning). Not given | continues. If it repeats, |
1667 | | when a signal interrupts the | check the network |
1668 | | wait | |
1669 | Any message of open_socket() or | Starting, or reopening the | See those methods |
1670 | reopen_log() | log after SIGHUP, failed | |
1671 | | (dies) | |
1672 +---------------------------------+--------------------------------+------------------------------+
1673  
1674 =head3 PSEUDOCODE
1675  
1676 open_socket() (does nothing if a socket is already open)
1677 if no log is open: reopen_log()
1678 for the duration of run():
1679 SIGHUP -> set "reopen requested"
1680 SIGTERM, SIGINT -> clear "running"
1681 set "running"
1682 while "running":
1683 if "reopen requested": clear it, then reopen_log()
1684 wait for a datagram
1685 if a datagram arrived: process() it
1686 (a signal ends the wait early, so the flags are seen at once;
1687 any other read error is a warning, and the loop continues)
1688 close the socket and the log
1689 put back the caller's signal handlers
1690 return the object
1691  
1692 =cut
1693  
1694 sub run
1695 77 ▶{
Subroutine run: called CC=10 SCAR=23.0
Pod documented
1696 77 my $self = shift;
1697  
1698 # Keep the caller's $! and $@ (see new())
1699 77 local ($!, $@);
1700  
1701 # One loop per object. A second run() from inside the first (from a
1702 # subclass or a signal handler, say) used to shut the socket and the log
1703 # when it returned, and the first loop then died on the missing socket.
1704 77 ▶ croak($self->i18n('already_running')) if($self->{running});
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"running"} 1 76 77
1705  
1706 # Premise: open_socket() does nothing when a socket is already open.
1707 # Conclusion: it can be called unconditionally. reopen_log() is not
1708 # like that (it always reopens), so its guard stays.
1709 #
1710 # Starting is all or nothing: if the log cannot be opened, a socket
1711 # that run() itself opened is closed again, so a failed start does not
1712 # leave the port taken. A socket the caller opened stays theirs.
1713 76 ▶ my $socket_was_open = $self->{socket} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$self->{'socket'} ? : 60 16 76
1714 76 $self->open_socket();
1715 71 ▶ if(!$self->{fh}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"fh"}) 42 29 71
1716 42 ▶ eval { $self->reopen_log(); 1 } or do {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { $self->reopen_log; 1 } } or do { my $error = $@; if (not $socket_was_open and my $socket = delete $self->{"socket"}) { eval { do { $socket->close } }; } ; die $error } 37 5 42
1717 5 my $error = $@;
1718 5 ▶ if(!$socket_was_open && (my $socket = delete $self->{socket})) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $socket_was_open and my $socket = delete $self->{"socket"}) 2 3 5
Condition100%3/3
not $socket_was_open and my $socket = delete $self->{"socket"}
!ll&&!rl&&r
212
MC/DC100%2/2
not $socket_was_open and my $socket = delete $self->{"socket"}
not $socket_was_open my $socket = delete $self->{"socket"}
Truth table100%3/3
not(A) and B
A= not $socket_was_openB= my $socket = delete $self->{"socket"}
ABresult
0X0
100
111
1719 2 eval { $socket->close() }; # the open error matters more
1720 }
1721 # A rethrow of the error already caught, so die, not croak: croak
1722 # would add this line's location and hide where it really failed
1723 5 die $error;
1724 };
1725 }
1726  
1727 # Handlers only set flags: Perl's deferred signals make that safe, and
1728 # the real work then happens at a known point in the loop below
1729 66 ▶ local $SIG{HUP} = sub { $self->{reopen_requested} = 1 };
Subroutine __ANON__: called CC=1 SCAR=0.0
1730 66 ▶ local $SIG{TERM} = local $SIG{INT} = sub { $self->{running} = 0 };
Subroutine __ANON__: called CC=1 SCAR=0.0
1731  
1732 # local, so the flag is cleared however run() ends: normally, or by
1733 # dying when a reopen after SIGHUP fails
1734 66 local $self->{running} = 1;
1735  
1736 # Also local: a SIGHUP that arrives with the stop signal must not be
1737 # left set, or the next run() would reopen the log for no reason
1738 66 local $self->{reopen_requested} = 0;
1739 66 ▶ while($self->{running}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"running"}) 144 61 205
1740 # Perl does not use SA_RESTART, so a signal interrupts recv()
1741 # and we get here promptly to act on it
1742 144 ▶ if($self->{reopen_requested}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"reopen_requested"}) 12 132 144
1743 12 $self->{reopen_requested} = 0;
1744 12 $self->reopen_log();
1745 }
1746  
1747 142 my $peer = $self->_receive(\my $datagram);
1748 139 ▶ $self->process($datagram, $peer) if($peer);
Branch: 1 branch
BranchTrueFalseTotal
if $peer 50 89 139
1749 }
1750  
1751 61 $self->_shutdown();
1752  
1753 59 return $self;
1754 }
1755  
1756 =head2 stop
1757  
1758 Purpose: ask C<run()> to finish. C<run()> returns after the datagram it is
1759 handling, or at once if it is waiting.
1760  
1761 Args: none.
1762  
1763 Returns: the object.
1764  
1765 Side Effects: clears the "running" flag. Calling it before C<run()> has no
1766 effect, because C<run()> sets the flag when it starts.
1767  
1768 Usage:
1769  
1770 $server->stop();
1771  
1772 =head3 EXAMPLE
1773  
1774 # Run for one minute
1775 local $SIG{ALRM} = sub { $server->stop() };
1776 alarm(60);
1777 $server->run();
1778  
1779 =head3 API SPECIFICATION
1780  
1781 =head4 INPUT
1782  
1783 {}
1784  
1785 =head4 OUTPUT
1786  
1787 { type => 'object', isa => 'App::Syslogd' }
1788  
1789 =head3 MESSAGES
1790  
1791 None.
1792  
1793 =cut
1794  
1795 sub stop
1796 60 ▶{
Subroutine stop: called CC=1 SCAR=0.0
Pod documented
1797 60 my $self = shift;
1798  
1799 60 $self->{running} = 0;
1800  
1801 60 return $self;
1802 }
1803  
1804 =head2 i18n
1805  
1806 Purpose: make a message for people to read, in the server's language. All
1807 of this module's own messages are made with it, so they can be translated.
1808  
1809 Args:
1810  
1811 =over 4
1812  
1813 =item 1. The message key, for example C<listening>. The keys are in the
1814 table below.
1815  
1816 =item 2. Optional: a hash reference of values to put into the message, for
1817 example C<< { port => 514 } >>. A missing value becomes an empty string.
1818  
1819 =back
1820  
1821 It also works on the class (C<< App::Syslogd->i18n(...) >>); the language then
1822 comes from the environment.
1823  
1824 Returns: the message as a string. An unknown key does not die: you get the
1825 key and its values back, such as C<no_such_key (a=1)>.
1826  
1827 Side Effects: none.
1828  
1829 Usage:
1830  
1831 print $server->i18n('listening', { address => '0.0.0.0', port => 514 }), "\n";
1832  
1833 =head3 EXAMPLE
1834  
1835 print App::Syslogd->i18n('shutdown', { count => 1 }), "\n";
1836 # Syslog server shutting down after recording 1 message
1837 print App::Syslogd->i18n('shutdown', { count => 3 }), "\n";
1838 # Syslog server shutting down after recording 3 messages
1839  
1840 =head3 API SPECIFICATION
1841  
1842 =head4 INPUT
1843  
1844 {
1845 key => { type => 'string', min => 1, position => 0 },
1846 args => { type => 'hashref', optional => 1, position => 1 },
1847 }
1848  
1849 Domains: C<key> is one of the keys in the table below (an unknown key gives
1850 the key back; undef, "" or a reference dies). C<args> is a hash reference
1851 or undef; anything else dies, including C<""> and C<0>. Values may be any text, including
1852 non-ASCII characters, which appear unchanged. For C<count>, 1 gives the
1853 singular and every other number (0, 2, -1, 1.5) the plural; text that is
1854 not a number counts as 0.
1855  
1856 =head4 OUTPUT
1857  
1858 { type => 'string' }
1859  
1860 =head3 MESSAGES
1861  
1862 The keys, the values each one uses, and the English text:
1863  
1864 +---------------+------------------------+--------------------------------------------------+
1865 | Key | Values | English text |
1866 +---------------+------------------------+--------------------------------------------------+
1867 | usage | program | Usage: PROGRAM [--port <port_number>] ... |
1868 | listening | address, port | Syslog server listening on ADDRESS UDP port PORT |
1869 | shutdown | count | Syslog server shutting down after recording |
1870 | | | COUNT message(s) |
1871 | socket_failed | address, port, error | Could not create a UDP socket on ADDRESS port |
1872 | | | PORT: ERROR |
1873 | open_failed | file, error | Could not open log file FILE: ERROR |
1874 | unsafe_file | file | Refusing to log to FILE: it must be a regular |
1875 | | | file, owned by this user, with exactly one |
1876 | | | link |
1877 | write_failed | file, error | Could not write to log file FILE: ERROR |
1878 | recv_failed | error | Error receiving a datagram: ERROR |
1879 | no_log_open | (none) | process() was called before reopen_log() |
1880 | | | succeeded |
1881 | not_a_datagram| type | A datagram must be a string (the type given was |
1882 | | | TYPE) |
1883 | missing_key | (none) | A message key is needed |
1884 | bad_values | type | Message values must be a hash reference (the |
1885 | | | type given was TYPE) |
1886 | no_progress | (none) | the system accepted no data (the ERROR part of |
1887 | | | write_failed when a write makes no progress) |
1888 | not_cgi | (none) | This program is a server, not a CGI program: it |
1889 | | | will not run from a web server |
1890 | not_a_log | file | Refusing to log to FILE: it is not empty and |
1891 | | | does not start with the syslog header line |
1892 | already_running | (none) | run() is already running |
1893 +---------------+------------------------+--------------------------------------------------+
1894  
1895 =cut
1896  
1897 sub i18n
1898 262 ▶{
Subroutine i18n: called CC=2 SCAR=6.9
Pod documented
1899 262 my ($self, $key, $args) = @_;
1900  
1901 # Class-method calls have no object and so no stored handle
1902 262 ▶ my $lh = ref($self) ? $self->{lh} : App::Syslogd::I18N->handle();
Branch: 1 branch
BranchTrueFalseTotal
ref $self ? : 228 34 262
1903  
1904 262 return $lh->text($key, $args);
1905 }
1906  
1907 # ---------------------------------------------------------------------------
1908 # Private and protected helpers
1909 # ---------------------------------------------------------------------------
1910  
1911 # _receive
1912 # Purpose: wait for one datagram.
1913 # Entry: $self->{socket} set; $buffer_ref a scalar ref to fill.
1914 # Premise 1: _receive is only called from run()'s loop.
1915 # Premise 2: run() calls open_socket() before the loop, and
1916 # open_socket() dies if it cannot give a socket. Conclusion:
1917 # the socket always exists here, so it is not checked again.
1918 # Exit: the sender's sockaddr, or undef if interrupted or on error.
1919 # Side Effects: carps on errors other than EINTR.
1920 sub _receive
1921 140 ▶{
Subroutine _receive: called CC=3 SCAR=11.0
1922 140 my ($self, $buffer_ref) = @_;
1923  
1924 140 my $peer = $self->{socket}->recv(${$buffer_ref}, $RECV_BUFFER);
1925  
1926 # EINTR is how a signal wakes us; it is expected, not an error
1927 137 ▶ if(!defined($peer) && !$!{EINTR}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $peer or $!{"EINTR"}) 7 130 137
Condition100%3/3
defined $peer or $!{"EINTR"}
l!l&&r!l&&!r
53777
MC/DC100%2/2
defined $peer or $!{"EINTR"}
defined $peer $!{"EINTR"}
Truth table100%3/3
A or B
A= defined $peerB= $!{"EINTR"}
ABresult
1X1
011
000
1928 7 carp($self->i18n('recv_failed', { error => "$!" }));
1929 }
1930  
1931 137 return $peer;
1932 }
1933  
1934 # _open_log
1935 # Purpose: open $self->{file} for appending, safely.
1936 # Entry: $self->{file} set.
1937 # Exit: an open filehandle (written with syswrite, unbuffered);
1938 # croaks on failure.
1939 # Side Effects: may create the file (mode 0600) and write the header row;
1940 # chmods an existing file to 0600.
1941 sub _open_log
1942 313 ▶{
Subroutine _open_log: called CC=10 SCAR=23.0
1943 313 my $self = shift;
1944 313 my $file = $self->{file};
1945  
1946 # The eval below must not touch the caller's $@
1947 313 local $@;
1948  
1949 # O_NOFOLLOW: if the log is in a shared directory (/tmp), anyone could plant a
1950 # symlink to /etc/shadow before root starts us. O_APPEND: rows from
1951 # one write() are never interleaved with another writer's, and always
1952 # go to the end. O_RDWR (not O_WRONLY) so the first line can be read
1953 # to check the file is one of our logs.
1954 313 my $fh;
1955 {
1956 50 ▶ no autodie qw(sysopen);
Subroutine BEGIN: called CC=1 SCAR=0.0
1957 313 ▶ sysopen($fh, $file, O_RDWR | O_APPEND | O_CREAT | $O_NOFOLLOW | $O_NONBLOCK, $LOG_MODE)
Branch: 1 branch
BranchTrueFalseTotal
sysopen $fh, $file, 1090 | $O_NOFOLLOW | $O_NONBLOCK, $LOG_MODE or croak($self->i18n("open_failed", {"file", $file, "error", "$!"})) 267 46 313
1958 or croak($self->i18n('open_failed', { file => $file, error => "$!" }));
1959 }
1960  
1961 # O_NOFOLLOW cannot catch a hard link or a file someone else pre-created
1962 # for us to fill with their reading material, so check after opening
1963 # Safe means all three: a regular file, owned by us, one link. By De
1964 # Morgan, "not all three" is "any one of them fails".
1965 267 my @st = stat($fh);
1966 267 ▶ unless(-f _ && ($st[4] == $>) && ($st[3] == 1)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f _ and $st[4] == $> and $st[3] == 1) 21 246 267
Condition100%6/6
-f _ and $st[4] == $> and $st[3] == 1
!ll&&!rl&&r
156246
-f _ and $st[4] == $>
!ll&&!rl&&r
132252
MC/DC100%3/3
-f _ and $st[4] == $> and $st[3] == 1
-f _ $st[4] == $> $st[3] == 1
Truth table100%4/4
A and B and C
A= -f _B= $st[4] == $>C= $st[3] == 1
ABCresult
0XX0
10X0
1100
1111
1967 21 _discard($fh);
1968 21 croak($self->i18n('unsafe_file', { file => $file }));
1969 }
1970  
1971 # A file that already has content must be one of our logs: it must
1972 # start with the header line. Without this a mistaken setting (as
1973 # root, every root-owned file is "ours") would append to, and chmod,
1974 # any file at all, /etc/passwd included. Checked before the chmod, so
1975 # a file that is not ours to change is never changed.
1976 246 ▶ unless(-z _ || $self->_starts_with_header($fh)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-z _ or $self->_starts_with_header($fh)) 9 237 246
Condition100%3/3
-z _ or $self->_starts_with_header($fh)
l!l&&r!l&&!r
206319
MC/DC100%2/2
-z _ or $self->_starts_with_header($fh)
-z _ $self->_starts_with_header($fh)
Truth table100%3/3
A or B
A= -z _B= $self->_starts_with_header($fh)
ABresult
1X1
011
000
1977 9 _discard($fh);
1978 9 croak($self->i18n('not_a_log', { file => $file }));
1979 }
1980  
1981 # Tighten an existing file too: previous versions created it 0644
1982 237 ▶ chmod($LOG_MODE, $fh) if($HAVE_FCHMOD);
Branch: 1 branch
BranchTrueFalseTotal
if $HAVE_FCHMOD 237 0 237
1983 237 binmode($fh);
1984  
1985 # Header only on an empty file, so a reopened file is not given a
1986 # second header row half way down. If that fails the handle is
1987 # closed here, not left for the garbage collector.
1988 237 ▶ if(-z $fh) {
Branch: 1 branch
BranchTrueFalseTotal
if (-z $fh) 206 31 237
1989 206 ▶ eval { $self->_write_header($fh); 1 } or do {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { $self->_write_header($fh); 1 } } or do { my $error = $@; _discard($fh); die $error } 200 6 206
1990 6 my $error = $@;
1991 6 _discard($fh);
1992 # A rethrow of the error already caught, so die, not croak
1993 6 die $error;
1994 };
1995 }
1996  
1997 231 return $fh;
1998 }
1999  
2000 # _starts_with_header
2001 # Purpose: is this file one of our logs?
2002 # Entry: $fh open for reading on a non-empty file.
2003 # Exit: 1 if the first line is the header row (ending in "\n", or
2004 # "\r\n" for a file once written on Windows), else 0.
2005 # Side Effects: moves the read position; writes are unaffected, because
2006 # O_APPEND always writes at the end.
2007 sub _starts_with_header
2008 50 ▶{
Subroutine _starts_with_header: called CC=5 SCAR=16.1
2009 50 my ($self, $fh) = @_;
2010  
2011 50 ▶ no autodie qw(sysseek sysread);
Subroutine BEGIN: called CC=1 SCAR=0.0
2012  
2013 # The header exactly as _write_header writes it, without its newline
2014 50 my ($line) = $self->_csv_line([@CSV_HEADER]);
2015 50 ▶ (my $header = $line // '') =~ s/\n\z//;
Condition100%2/2
$line // ""
l!l
491
MC/DC100%1/1
$line // ""
$line
Truth table100%2/2
A
A= $line
Aresult
11
00
2016  
2017 # Read the header and up to two line-end bytes; a failed seek or read
2018 # leaves $start empty, which does not match
2019 50 my $start = '';
2020 50 ▶ sysread($fh, $start, length($header) + 2) if(defined(sysseek($fh, 0, SEEK_SET)));
Branch: 1 branch
BranchTrueFalseTotal
if defined sysseek($fh, 0, 0) 49 1 50
2021  
2022 50 ▶ return (length($header) && $start =~ /\A\Q$header\E\r?\n/) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
length $header && $start =~ /\A\Q$header\E\r?\n/ ? : 35 15 50
Condition100%3/3
length $header and $start =~ /\A\Q$header\E\r?\n/
!ll&&!rl&&r
11435
MC/DC100%2/2
length $header and $start =~ /\A\Q$header\E\r?\n/
length $header $start =~ /\A\Q$header\E\r?\n/
Truth table100%3/3
A and B
A= length $headerB= $start =~ /\A\Q$header\E\r?\n/
ABresult
0X0
100
111
2023 }
2024  
2025 # _discard
2026 # Purpose: close a handle that is being abandoned because of an error.
2027 # Entry: $fh an open handle.
2028 # Exit: nothing useful.
2029 # Side Effects: closes $fh, ignoring a failure: the caller is already
2030 # reporting a more useful error, and under autodie a failed
2031 # close() would replace it.
2032 sub _discard
2033 38 ▶{
Subroutine _discard: called CC=1 SCAR=0.0
2034 38 my $fh = shift;
2035  
2036 50 ▶ no autodie qw(close);
Subroutine BEGIN: called CC=1 SCAR=0.0
2037 38 close($fh);
2038  
2039 38 return;
2040 }
2041  
2042 # _write_header
2043 # Purpose: put the column headings at the top of a new log.
2044 # Entry: $fh open on an empty file.
2045 # Exit: $self.
2046 # Side Effects: writes one line; croaks if it cannot, since a log that
2047 # cannot take its first line will not take any others.
2048 sub _write_header
2049 213 ▶{
Subroutine _write_header: called CC=3 SCAR=11.0
2050 213 my ($self, $fh) = @_;
2051  
2052 213 my ($line, $error) = $self->_csv_line([@CSV_HEADER]);
2053 213 ▶ $error //= $self->_append_line($fh, $line);
Condition100%3/3
$error //= $self->_append_line($fh, $line)
l!l&&r!l&&!r
29202
MC/DC100%2/2
$error //= $self->_append_line($fh, $line)
$error $self->_append_line($fh, $line)
Truth table100%3/3
A //= B
A= $errorB= $self->_append_line($fh, $line)
ABresult
1X1
011
000
2054 213 ▶ croak($self->i18n('write_failed', { file => $self->{file}, error => $error })) if(defined($error));
Branch: 1 branch
BranchTrueFalseTotal
if defined $error 11 202 213
2055  
2056 202 return $self;
2057 }
2058  
2059 # _append_line
2060 # Purpose: add one complete line to the end of the log, or nothing.
2061 # Entry: $fh open for appending; $line ends with a newline.
2062 # Exit: undef on success, or the system's error text.
2063 # Side Effects: writes to the file. If only part of the line could be
2064 # written (e.g. the disk filled up mid-line), the part is cut off
2065 # again, so the next line does not join a half-written one.
2066 # syswrite rather than print: print leaves a failed line in Perl's
2067 # buffer, where it makes the next close() fail (fatal under autodie) and
2068 # makes Perl add an "unable to close filehandle properly" warning.
2069 sub _append_line
2070 461 ▶{
Subroutine _append_line: called CC=7 SCAR=19.5
2071 461 my ($self, $fh, $line) = @_;
2072  
2073 50 ▶ no autodie qw(sysseek syswrite truncate);
Subroutine BEGIN: called CC=1 SCAR=0.0
2074  
2075 # syswrite may write less than asked; keep going until done or error
2076 461 my $done = 0;
2077 461 ▶ while($done < length($line)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($done < length $line) 470 426 896
2078 470 my $written = syswrite($fh, $line, length($line) - $done, $done);
2079 470 ▶ last unless($written);
Branch: 1 branch
BranchTrueFalseTotal
unless $written 35 435 470
2080 435 $done += $written;
2081 }
2082 461 ▶ return undef if($done == length($line)); ## no critic (ProhibitExplicitReturnUndef): undef means success
Branch: 1 branch
BranchTrueFalseTotal
if $done == length $line 426 35 461
2083  
2084 # Remember the error before truncate can change $!. A write that
2085 # returned 0 made no progress but set no error, so $! would be stale.
2086 35 ▶ my $error = $! ? "$!" : $self->i18n('no_progress');
Branch: 1 branch
BranchTrueFalseTotal
$! ? : 30 5 35
2087  
2088 # Remove a partial line. The line started $done bytes before the
2089 # current end (O_APPEND wrote it there). Finding that out only now,
2090 # not before every write, saves a seek on every successful line.
2091 35 ▶ if($done) {
Branch: 1 branch
BranchTrueFalseTotal
if ($done) 8 27 35
2092 8 my $end = sysseek($fh, 0, SEEK_END);
2093 8 ▶ truncate($fh, $end - $done) if(defined($end));
Branch: 1 branch
BranchTrueFalseTotal
if defined $end 6 2 8
2094 }
2095  
2096 35 return $error;
2097 }
2098  
2099 # _close_log
2100 # Purpose: close the log if it is open.
2101 # Entry: none.
2102 # Exit: $self; $self->{fh} is undef.
2103 # Side Effects: closes a filehandle.
2104 sub _close_log
2105 371 ▶{
Subroutine _close_log: called CC=2 SCAR=6.9
2106 371 my $self = shift;
2107  
2108 371 ▶ if(my $fh = delete $self->{fh}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $fh = delete $self->{"fh"}) 101 270 371
2109 101 close($fh);
2110 }
2111  
2112 371 return $self;
2113 }
2114  
2115 # _shutdown
2116 # Purpose: release the socket and the log when run() finishes.
2117 # Entry: none.
2118 # Exit: $self.
2119 # Side Effects: closes the socket and log; open_socket() and reopen_log() are
2120 # needed before another run().
2121 sub _shutdown
2122 65 ▶{
Subroutine _shutdown: called CC=3 SCAR=11.0
2123 65 my $self = shift;
2124  
2125 # Close the log even if closing the socket dies, then pass that
2126 # error on: otherwise a broken socket would leave the log open too.
2127 # The eval must not touch the caller's $@.
2128 65 local $@;
2129 65 my $socket = delete $self->{socket};
2130 65 ▶ my $ok = eval { $socket->close() if($socket); 1 };
Branch: 1 branch
BranchTrueFalseTotal
if $socket 62 3 65
2131 65 my $error = $@;
2132 65 $self->_close_log();
2133 # A rethrow of the error already caught, so die, not croak
2134 65 ▶ die $error unless($ok);
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 4 61 65
2135  
2136 61 return $self;
2137 }
2138  
2139 # _write_row
2140 # Purpose: append one CSV row to the log.
2141 # Entry: $self->{fh} open; $row an arrayref of fields.
2142 # Exit: $self.
2143 # Side Effects: writes to the log; carps (does not croak) if that fails, so
2144 # that a transiently full disk does not stop the daemon.
2145 sub _write_row
2146 240 ▶{
Subroutine _write_row: called CC=3 SCAR=11.0
2147 240 my ($self, $row) = @_;
2148  
2149 240 my ($line, $error) = $self->_csv_line($row);
2150 240 ▶ $error //= $self->_append_line($self->{fh}, $line);
Condition100%3/3
$error //= $self->_append_line($self->{"fh"}, $line)
l!l&&r!l&&!r
417219
MC/DC100%2/2
$error //= $self->_append_line($self->{"fh"}, $line)
$error $self->_append_line($self->{"fh"}, $line)
Truth table100%3/3
A //= B
A= $errorB= $self->_append_line($self->{"fh"}, $line)
ABresult
1X1
011
000
2151 240 ▶ carp($self->i18n('write_failed', { file => $self->{file}, error => $error })) if(defined($error));
Branch: 1 branch
BranchTrueFalseTotal
if defined $error 21 219 240
2152  
2153 240 return $self;
2154 }
2155  
2156 # _csv_line
2157 # Purpose: turn fields into one CSV line (shared by the header and rows).
2158 # Entry: $fields an arrayref.
2159 # Exit: ($line) on success, or (undef, $error) if Text::CSV refuses,
2160 # so that a refused row is reported, not silently written as
2161 # nothing (or as the previous row, which string() would repeat).
2162 # Side Effects: none.
2163 # combine() then our own write, rather than Text::CSV's print(): the XS
2164 # print emits a spurious "uninitialized" warning when write() fails.
2165 sub _csv_line
2166 506 ▶{
Subroutine _csv_line: called CC=3 SCAR=11.0
2167 506 my ($self, $fields) = @_;
2168 506 my $csv = $self->{csv};
2169  
2170 # Premise: Text::CSV defines string() whenever combine() succeeds.
2171 # Conclusion: combine()'s result alone decides; string() needs no
2172 # separate check.
2173 return (undef, '' . ($csv->error_diag() || 'Text::CSV could not build the line'))
2174 506 ▶ unless($csv->combine(@{$fields}));
Branch: 1 branch
BranchTrueFalseTotal
unless $csv->combine(@{$fields;}) 9 497 506
Condition100%2/2
$csv->error_diag || 'Text::CSV could not build the line'
l!l
72
MC/DC100%1/1
$csv->error_diag || 'Text::CSV could not build the line'
$csv->error_diag
Truth table100%2/2
A
A= $csv->error_diag
Aresult
11
00
2175  
2176 497 return ($csv->string());
2177 }
2178  
2179 # _peer_name
2180 # Purpose: turn the sender's sockaddr into the string to log.
2181 # Entry: $peer a packed sockaddr (IPv4 or IPv6).
2182 # Exit: the host name if resolution is on and succeeds, else the
2183 # numeric address.
2184 # Side Effects: may do a (cached) reverse DNS lookup.
2185 # Protected rather than private so that a subclass can, say, log
2186 # "name (address)" or use an asynchronous resolver.
2187 sub _peer_name
2188 261 ▶{
Subroutine _peer_name: called CC=8 SCAR=20.8
2189 261 my ($self, $peer) = @_;
2190  
2191 # Only a packed address can be decoded: getnameinfo dies on undef or a
2192 # reference ("addr is not a string"), so those are treated like an
2193 # undecodable address and logged as an empty host
2194 261 ▶ return '' if(!defined($peer) || ref($peer));
Branch: 1 branch
BranchTrueFalseTotal
if not defined $peer or ref $peer 46 215 261
Condition100%3/3
not defined $peer or ref $peer
l!l&&r!l&&!r
3412215
MC/DC100%2/2
not defined $peer or ref $peer
not defined $peer ref $peer
Truth table100%3/3
not(A) or B
A= not defined $peerB= ref $peer
ABresult
1X1
011
000
2195  
2196 # getnameinfo copes with both families, unlike inet_ntoa
2197 215 my (undef, $address) = getnameinfo($peer, NI_NUMERICHOST, NIx_NOSERV);
2198 215 ▶ $address //= '';
Condition100%2/2
$address //= ""
l!l
20015
MC/DC100%1/1
$address //= ""
$address
Truth table100%2/2
A
A= $address
Aresult
11
00
2199  
2200 215 ▶ return $address unless($self->{resolve} && length($address));
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"resolve"} and length $address 163 52 215
Condition100%3/3
$self->{"resolve"} and length $address
!ll&&!rl&&r
1491452
MC/DC100%2/2
$self->{"resolve"} and length $address
$self->{"resolve"} length $address
Truth table100%3/3
A and B
A= $self->{"resolve"}B= length $address
ABresult
0X0
100
111
2201  
2202 # getnameinfo consults /etc/hosts before DNS (via nsswitch.conf), so
2203 # there is no need to read /etc/hosts ourselves. A cache that fails
2204 # (a remote cache timing out, say) or answers nothing must not stop
2205 # the logging: fall back to the address.
2206 52 local $@;
2207 52 my $name = eval {
2208 26 ▶ $self->{cache}->compute($address, $self->{dns_ttl}, sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
2209 26 my ($error, $found) = getnameinfo($peer, NI_NAMEREQD, NIx_NOSERV);
2210 26 ▶ return $error ? $address : $found;
Branch: 1 branch
BranchTrueFalseTotal
$error ? : 9 17 26
2211 52 });
2212 };
2213  
2214 52 ▶ return (defined($name) && length($name)) ? $name : $address;
Branch: 1 branch
BranchTrueFalseTotal
defined $name && length $name ? : 40 12 52
Condition100%3/3
defined $name and length $name
!ll&&!rl&&r
9340
MC/DC100%2/2
defined $name and length $name
defined $name length $name
Truth table100%3/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
2215 }
2216  
2217 # _escape_controls
2218 # Purpose: make a message safe to store as one CSV line.
2219 # Entry: a string.
2220 # Exit: the string with every C0 control and DEL written as \xNN.
2221 # Side Effects: none.
2222 # A plain function, not a method, because it uses no state.
2223 sub _escape_controls
2224 888 ▶{
Subroutine _escape_controls: called CC=1 SCAR=0.0
2225 888 my $text = shift;
2226  
2227 888 $text =~ s/([\x00-\x1F\x7F])/sprintf('\\x%02X', ord($1))/ge;
2228  
2229 888 return $text;
2230 }
2231  
2232 # Protect the helpers now that they are all defined. This uses the
2233 # declarative form, not :Private/:Protected attributes, because attributes
2234 # are only applied in a CHECK block, which never runs when this module is
2235 # loaded with require at run time: the helpers were then left callable by
2236 # anyone.
2237 #
2238 # Loaded normally (use), import() queues the subs for CHECK. Loaded at run
2239 # time, import() should wrap them at once, but Sub::Private 0.05 and
2240 # Sub::Protected 0.02 only learn that CHECK has passed from their own CHECK
2241 # block; if they too were first loaded at run time, the queue is never
2242 # processed. So, at run time, anything import() did not wrap is wrapped
2243 # here with the same routine their CHECK block uses. Comparing code refs
2244 # first means nothing is ever wrapped twice (a double wrapper would lock
2245 # this package out of its own helpers).
2246 {
2247 50 Readonly my %PROTECTION => (
2248 'Sub::Private' => [qw(
2249 _receive _open_log _write_header _append_line _close_log
2250 _shutdown _write_row _csv_line _escape_controls _discard
2251 _starts_with_header
2252 )],
2253 # Protected, not private: a subclass may override it (see SYNOPSIS)
2254 'Sub::Protected' => [qw(_peer_name)],
2255 );
2256 50 ▶ no strict 'refs'; ## no critic (ProhibitNoStrict): reads and replaces subs by name
Subroutine BEGIN: called CC=1 SCAR=0.0
2257 50 foreach my $module (sort keys %PROTECTION) {
2258 100 my @names = @{$PROTECTION{$module}};
2259 100 my %before = map { $_ => \&{__PACKAGE__ . "::$_"} } @names;
2260 100 $module->import(@names);
2261 100 ▶ next if(${^GLOBAL_PHASE} ne 'RUN');
Branch: 1 branch
BranchTrueFalseTotal
if ${^GLOBAL_PHASE} ne "RUN" 86 14 100
2262 14 ▶ my $wrap = $module->can('_process_one') or next;
Branch: 1 branch
BranchTrueFalseTotal
my $wrap = $module->can("_process_one") or next 12 2 14
2263 # Their own helpers are protected too; the documented BYPASS
2264 # switches lift that for this call only
2265 12 local $Sub::Private::BYPASS = 1;
2266 12 local $Sub::Protected::BYPASS = 1;
2267 12 foreach my $name (grep { \&{__PACKAGE__ . "::$_"} == $before{$_} } @names) {
2268 0 $wrap->(__PACKAGE__, $name);
2269 }
2270 }
2271 }
2272  
2273 =head1 SECURITY
2274  
2275 This module is not a CGI program: it reads no HTTP request, no
2276 C<QUERY_STRING>, C<PATH_INFO>, cookies or other C<HTTP_*> variables, and
2277 never reads standard input. It writes CSV, not HTML. Its untrusted
2278 inputs, and what protects against each, are:
2279  
2280 +----------------------+--------------------------+----------------------------------------+
2281 | Input | Controlled by | Protection |
2282 +----------------------+--------------------------+----------------------------------------+
2283 | UDP datagrams | anyone who can reach the | stored as data only; control |
2284 | | port | characters written as \xNN (no forged |
2285 | | | lines, no terminal escapes); never |
2286 | | | reflected into warnings or errors |
2287 | reverse-DNS names | whoever owns the | escaped like messages |
2288 | | sender's address | |
2289 | App__Syslogd__* | whoever starts the | validated like arguments; tainted |
2290 | variables, config | server | values are refused under perl -T |
2291 | files | | (never untainted) |
2292 | LANG, LANGUAGE, LC_* | whoever starts the | a tag can only select a lexicon |
2293 | | server | package; unknown tags give English |
2294 +----------------------+--------------------------+----------------------------------------+
2295  
2296 It never runs another program (no C<system>, C<exec>, backticks or piped
2297 C<open>), so shell metacharacters in any input are only ever text. File
2298 names are passed to the system directly, never to a shell. An existing
2299 file is only reused if it is empty or already one of the server's logs, so
2300 even as root a mistaken or hostile C<file> setting cannot make the server
2301 append to, or change the permissions of, a file such as F</etc/passwd>.
2302 Markup such as
2303 C<< <script> >> in a message is stored unchanged: a program that shows the
2304 log in a web page (for example the viewer in F<www/>) must HTML-encode it.
2305  
2306 =head1 LIMITATIONS
2307  
2308 =over 4
2309  
2310 =item * B<The default directory is a file on Debian and Ubuntu.> The
2311 default log is F</var/log/syslog/syslog.csv>, but on Debian, Ubuntu and
2312 their derivatives F</var/log/syslog> is rsyslog's own log file, so the
2313 server cannot start with the default there ("Not a directory"). Give
2314 C<file> (or C<--file>), for example F</var/log/syslog/syslog.csv> as in
2315 L</SAMPLE CONFIGURATION>.
2316  
2317 =item * B<The default directory must already exist.> The server does not
2318 create directories: create F</var/log/syslog> (see L</INSTALLATION>), or the
2319 server stops with "Could not open log file ...: No such file or directory".
2320 Versions before 0.002.0 logged to F</tmp/syslog.log> by default.
2321  
2322 =item * B<The web viewer cannot read the log.> The file is readable only by
2323 its owner (usually root), but the web pages in F<www/> run as the web
2324 server's user. You must choose between privacy and the viewer, for example
2325 by using a shared group and changing C<$LOG_MODE> in the source.
2326  
2327 =item * B<It does not give up root.> Port 514 needs root (or the
2328 CAP_NET_BIND_SERVICE capability), and the server keeps root while it runs.
2329 Better: use a port above 1023 with a firewall redirect, or let systemd open
2330 the socket and pass it with C<< new(socket => ...) >>.
2331  
2332 =item * B<No time of arrival.> A line holds only what the sender put in the
2333 message. Adding a column would break existing files and the web viewer, so
2334 it needs a migration and has not been done.
2335  
2336 =item * B<Host name lookups block.> Answers are remembered, but the first
2337 message from a host with a slow DNS server makes the loop wait, and the
2338 system may drop datagrams that arrive during the wait. Use C<--no-resolve>
2339 on a busy server.
2340  
2341 =item * B<UDP only.> There is no TCP (RFC 6587) or TLS (RFC 5425). So
2342 delivery is not guaranteed, and anyone who can reach the port can write to
2343 the log.
2344  
2345 =item * B<Only the PRI is decoded.> Time stamps and host names inside RFC 3164
2346 messages, and RFC 5424 structured data, stay in the C<msg> column.
2347  
2348 =item * B<Spreadsheet formulas.> A message that starts with C<=>, C<+>, C<->
2349 or C<@> may run as a formula if you open the file in a spreadsheet. The
2350 data is kept unchanged on purpose; take care when you open it.
2351  
2352 =item * B<Backslashes are not escaped>, so the text C<\x0A> and an escaped
2353 newline look the same (see L</COMMON PITFALLS>).
2354  
2355 =item * B<Windows is less protected.> The module works on Windows, but:
2356  
2357 =over 4
2358  
2359 =item * Windows has no C<O_NOFOLLOW>, so the server cannot refuse a symbolic
2360 link as the log file. (Creating a symbolic link on Windows normally needs
2361 administrator rights, which makes this attack rare.)
2362  
2363 =item * Mode 0600 does not make the file private: Windows uses access control
2364 lists, which this module does not change. An existing file's permissions
2365 are not changed either, because Windows Perl cannot change the permissions
2366 of an open file. Put the log in a folder that only the right users can
2367 read.
2368  
2369 =item * There is no C<kill -HUP> from outside the process, so log rotation by
2370 signal is not available. Stop and restart the server instead.
2371  
2372 =item * A signal such as Ctrl-C may not interrupt the wait for a datagram, so
2373 the server may stop only after the next datagram arrives.
2374  
2375 =back
2376  
2377 =item * B<Do not send the logger's output to this server.> L<Object::Configure>
2378 gives each object a logger, and a shared configuration file may point it
2379 at syslog. This module does not log through it today, but if it ever
2380 does, a logger that sends to the same syslog server would feed its own
2381 input back to itself.
2382  
2383 =back
2384  
2385 =head1 AUTHOR
2386  
2387 Nigel Horne, C<< <njh at nigelhorne.com> >>
2388  
2389 =encoding utf8
2390  
2391 =head1 FORMAL SPECIFICATION
2392  
2393 This section describes each method exactly, in the Z notation. You do not
2394 need it to use the module; the descriptions in L</METHODS> say the same
2395 things in words.
2396  
2397 =head2 State
2398  
2399 [ADDRESS, PATH, LANGTAG, SOCKADDR, BYTE, NAME, VALUE]
2400 PORT == 0 .. 65535
2401 HEADER == ⟨"Host", "facility", "severity", "msg"⟩
2402 RECORD == ⟨facility : 0 .. 23, severity : 0 .. 7,
2403 message : seq BYTE, valid : 𝔹⟩
2404  
2405 Server
2406 port : PORT ; address : ADDRESS ; file : PATH
2407 resolve : 𝔹 ; language : LANGTAG
2408 count : ℕ
2409 bound, logging, running, hup : 𝔹
2410 contents : PATH ⇸ seq (seq BYTE)
2411 ─────────
2412 running ⇒ bound ∧ logging
2413  
2414 ΞServer ≙ [ ΔServer | θServer' = θServer ]
2415  
2416 =head2 new
2417  
2418 New
2419 Server'
2420 args? : NAME ⇸ VALUE
2421 configured? : NAME ⇸ VALUE -- files and environment
2422 ─────────
2423 let a == ((args? ⊕ configured?) ▷ (VALUE \ {⊥})) ∩ (dom NEW_SCHEMA × VALUE) •
2424 dom args? ⊆ dom NEW_SCHEMA ∧
2425 conforms(a, NEW_SCHEMA) ∧
2426 θServer' = (DEFAULTS ⊕ a) ⊕ {count ↦ 0} ∧
2427 bound' = (socket ∈ dom a) ∧ ¬logging' ∧ ¬running' ∧ ¬hup'
2428  
2429 NewFail
2430 ΞServer
2431 args? : NAME ⇸ VALUE
2432 error! : STRING
2433 ─────────
2434 dom args? ⊈ dom NEW_SCHEMA ∨ ¬ conforms(args?, NEW_SCHEMA) ∨
2435 ¬ conforms((args? ⊕ configured?) ∩ (dom NEW_SCHEMA × VALUE), NEW_SCHEMA)
2436  
2437 =head2 open_socket
2438  
2439 OpenSocketOk
2440 ΔServer
2441 ─────────
2442 bound' ∧ logging' = logging ∧ count' = count
2443 (port = 0 ∧ ¬bound ⇒ port' ∈ 1 .. 65535)
2444 (port ≠ 0 ∨ bound ⇒ port' = port)
2445  
2446 OpenSocketFail
2447 ΞServer
2448 error! : STRING
2449 ─────────
2450 ¬bound ∧ ¬ canBind(address, port)
2451  
2452 OpenSocket ≙ OpenSocketOk ∨ OpenSocketFail
2453  
2454 =head2 port
2455  
2456 Port
2457 ΞServer
2458 p! : PORT
2459 ─────────
2460 p! = port
2461  
2462 =head2 address
2463  
2464 Address
2465 ΞServer
2466 a! : ADDRESS
2467 ─────────
2468 a! = address
2469  
2470 =head2 count
2471  
2472 Count
2473 ΞServer
2474 n! : ℕ
2475 ─────────
2476 n! = count
2477  
2478 =head2 reopen_log
2479  
2480 ReopenLogOk
2481 ΔServer
2482 ─────────
2483 logging' ∧ bound' = bound ∧ count' = count
2484 isRegular(file) ∧ ¬ isSymlink(file)
2485 owner(file) = euid ∧ links(file) = 1 ∧ mode'(file) = 0600
2486 contents(file) = ⟨⟩ ∨ csv(HEADER) ⊑ contents(file)
2487 contents(file) = ⟨⟩ ⇒ contents'(file) = ⟨csv(HEADER)⟩
2488 contents(file) ≠ ⟨⟩ ⇒ contents'(file) = contents(file)
2489  
2490 ReopenLogFail
2491 ΔServer
2492 error! : STRING
2493 ─────────
2494 ¬logging' ∧ bound' = bound ∧ count' = count
2495 contents'(file) = contents(file) ∧ mode'(file) = mode(file)
2496  
2497 ReopenLog ≙ ReopenLogOk ∨ ReopenLogFail
2498  
2499 =head2 parse_message
2500  
2501 ParseMessage
2502 d? : seq BYTE
2503 r! : RECORD ∪ {⊥}
2504 ─────────
2505 let t == stripTrailing({CR, LF, NUL}, d?) •
2506 #t < 2 ⇒ r! = ⊥
2507 #t ≥ 2 ∧ (∃ p : 0 .. 191 ; b : seq BYTE •
2508 t = ⟨'<'⟩ ⁀ canonical(p) ⁀ ⟨'>'⟩ ⁀ b) ⇒
2509 r! = ⟨facility ↦ p div 8, severity ↦ p mod 8,
2510 message ↦ escape(b), valid ↦ true⟩
2511 otherwise ⇒
2512 r! = ⟨facility ↦ 1, severity ↦ 5,
2513 message ↦ escape(t), valid ↦ false⟩
2514  
2515 escape : seq BYTE → seq BYTE
2516 ∀ c : BYTE • escape(⟨c⟩) =
2517 if c ∈ 0 .. 31 ∪ {127} then "\x" ⁀ hex2(c) else ⟨c⟩
2518 ∀ s, u : seq BYTE • escape(s ⁀ u) = escape(s) ⁀ escape(u)
2519  
2520 =head2 process
2521  
2522 ProcessOk
2523 ΔServer
2524 d? : seq BYTE ; peer? : SOCKADDR ∪ {⊥}
2525 ─────────
2526 logging ∧ bound' = bound ∧ logging'
2527 ParseMessage(d?) = ⊥ ⇒ count' = count ∧ contents' = contents
2528 ParseMessage(d?) = r ≠ ⊥ ⇒
2529 count' = count + 1 ∧
2530 (writable(file) ⇒
2531 contents'(file) = contents(file) ⁀ ⟨csv(host(peer?), r)⟩) ∧
2532 (¬ writable(file) ⇒ contents' = contents)
2533  
2534 host(⊥) = ""
2535 resolve ⇒ host(p) = reverseName(p) if found, else numeric(p)
2536 ¬resolve ⇒ host(p) = numeric(p)
2537  
2538 ProcessFail
2539 ΞServer
2540 error! : STRING
2541 ─────────
2542 ¬logging
2543  
2544 Process ≙ ProcessOk ∨ ProcessFail
2545  
2546 =head2 run
2547  
2548 Start ≙ (¬bound ∧ OpenSocket ∨ bound ∧ ΞServer) ⨾
2549 (¬logging ∧ ReopenLog ∨ logging ∧ ΞServer)
2550  
2551 Loop ≙ μ L •
2552 (¬running ∧ Shutdown)
2553 □ (running ∧ hup ∧ [ ΔServer | ¬hup' ] ⨾ ReopenLog ⨾ L)
2554 □ (running ∧ ¬hup ∧ Receive ⨾ Process ⨾ L)
2555  
2556 Shutdown
2557 ΔServer
2558 ─────────
2559 ¬bound' ∧ ¬logging' ∧ ¬running' ∧ count' = count
2560  
2561 Run ≙ Start ⨾ [ ΔServer | running' ] ⨾ Loop
2562  
2563 SIGHUP received during Run ⇒ hup' = true
2564 SIGTERM or SIGINT during Run ⇒ running' = false
2565  
2566 =head2 stop
2567  
2568 Stop
2569 ΔServer
2570 ─────────
2571 ¬running' ∧ bound' = bound ∧ logging' = logging ∧ count' = count
2572  
2573 =head2 i18n
2574  
2575 I18n
2576 key? : KEY ; args? : NAME ⇸ VALUE ; out! : STRING
2577 ─────────
2578 key? ∈ dom ARGUMENT_ORDER ⇒
2579 out! = render(lexicon(language, key?),
2580 ⟨args?(n) | n ∈ ARGUMENT_ORDER(key?)⟩)
2581 key? ∉ dom ARGUMENT_ORDER ⇒ key? ⊑ out!
2582  
2583 =head2 Security invariants
2584  
2585 Commands ≙ { system, exec, readpipe, pipe-open }
2586 Datagram, Line : seq BYTE
2587  
2588 NoExecution
2589 ∀ op : operations(App::Syslogd) • calls(op) ∩ Commands = ∅
2590  
2591 LineIntegrity
2592 ∀ d? : Datagram ; peer? : SOCKADDR •
2593 #{ l : lines(record(d?, peer?)) } = 1 ∧
2594 ran record(d?, peer?) ∩ ({0 .. 31} ∪ {127} \ {LF}) = ∅
2595  
2596 NoReflection
2597 ∀ d? : Datagram ; m : warnings ∪ errors •
2598 #d? > 2 ⇒ ¬ (stripPRI(d?) ⊑ m)
2599  
2600 NoNul
2601 ∀ o : {address, file, language} • 0 ∉ ran args?(o)
2602  
2603 =head1 STATE DIAGRAM
2604  
2605 An object is always in one of six states. The boxes are the states; the
2606 arrows are the method calls or events that move it from one state to another.
2607 The text in square brackets is what happens during the move.
2608  
2609 new()
2610 | [check options; nothing opened]
2611 |
2612 | new(socket => S) starts in BOUND instead
2613 v
2614 +---------------------------+
2615 | IDLE |<--------------------------------+
2616 | no socket, no log file | |
2617 +---------------------------+ |
2618 | | |
2619 open_socket()| |reopen_log() |
2620 [bind UDP | |[open or create file (0600), |
2621 socket] | | write header if empty] |
2622 v v |
2623 +---------------+ +---------------+ |
2624 | BOUND | | LOGGING |<-- process() |
2625 | socket open, | | log open, | [write row, count + 1] |
2626 | no log file | | no socket | |
2627 +---------------+ +---------------+ |
2628 | | |
2629 reopen_log()| |open_socket() |
2630 | +---------+ | |
2631 +--->| READY |<---+ |
2632 | socket |<-- process() [write row, count + 1] |
2633 | and log |<-- reopen_log() [close, reopen file] |
2634 +---------+ |
2635 | |
2636 | run() [also allowed from IDLE, BOUND or |
2637 | LOGGING: opens what is missing; |
2638 v installs HUP/TERM/INT handlers] |
2639 +---------+ |
2640 datagram ------>| | [process(): write row, count + 1] |
2641 SIGHUP -------->| RUNNING | [reopen_log() at top of loop] |
2642 read error ---->| | [warning; keep going] |
2643 +---------+ |
2644 | |
2645 | SIGTERM, SIGINT or stop() |
2646 v [clear "running" flag] |
2647 +----------+ |
2648 | STOPPING | the current wait or datagram ends |
2649 +----------+ |
2650 | |
2651 | loop sees the flag |
2652 | [close socket and log; restore caller's |
2653 | signal handlers; run() returns] |
2654 +-----------------------------------------------+
2655  
2656 =head2 Transition table
2657  
2658 +----------+-------------------------------+----------+------------------------------------+
2659 | From | Trigger | To | Action / side effect |
2660 +----------+-------------------------------+----------+------------------------------------+
2661 | (none) | new() | IDLE | options checked and stored |
2662 | (none) | new(socket => S) | BOUND | S used as the socket |
2663 | IDLE | open_socket() | BOUND | UDP socket bound |
2664 | IDLE | reopen_log() | LOGGING | file opened or created, header |
2665 | BOUND | reopen_log() | READY | file opened or created, header |
2666 | LOGGING | open_socket() | READY | UDP socket bound |
2667 | BOUND | open_socket() | BOUND | nothing (already bound) |
2668 | READY | open_socket() | READY | nothing (already bound) |
2669 | LOGGING | reopen_log() | LOGGING | file closed and opened again |
2670 | READY | reopen_log() | READY | file closed and opened again |
2671 | LOGGING | process() | LOGGING | one row written, count + 1 |
2672 | READY | process() | READY | one row written, count + 1 |
2673 | IDLE, | run() | RUNNING | open what is missing, install |
2674 | BOUND, | | | signal handlers, set "running" |
2675 | LOGGING, | | | |
2676 | READY | | | |
2677 | RUNNING | datagram arrives | RUNNING | process(): row written, count + 1 |
2678 | RUNNING | SIGHUP | RUNNING | log closed and opened again |
2679 | RUNNING | read error (not a signal) | RUNNING | warning "Error receiving ..." |
2680 | RUNNING | a write fails (e.g. disk | RUNNING | warning "Could not write ..."; |
2681 | | full) | | that datagram is lost |
2682 | RUNNING | SIGTERM, SIGINT or stop() | STOPPING | "running" flag cleared |
2683 | STOPPING | the wait or datagram ends | IDLE | socket and log closed, handlers |
2684 | | | | restored, run() returns |
2685 +----------+-------------------------------+----------+------------------------------------+
2686  
2687 Failures (the method dies and the object changes as shown):
2688  
2689 +----------+-------------------------------+----------+------------------------------------+
2690 | From | Trigger | To | Action / side effect |
2691 +----------+-------------------------------+----------+------------------------------------+
2692 | IDLE, | open_socket() fails | (same) | dies "Could not create a UDP |
2693 | LOGGING | | | socket ..." |
2694 | IDLE, | reopen_log() fails | (same) | dies "Could not open log file ..." |
2695 | BOUND | | | or "Refusing to log ..." |
2696 | LOGGING, | reopen_log() fails | IDLE or | log closed, then dies "Could not |
2697 | READY | | BOUND | open log file ..." or |
2698 | | | | "Refusing to log ..." |
2699 | IDLE, | process() | (same) | dies "process() was called before |
2700 | BOUND | | | reopen_log() succeeded" |
2701 | RUNNING | SIGHUP, and the reopen fails | BOUND | log closed, handlers restored, |
2702 | | | | run() dies with the error |
2703 | IDLE | run(), and the log cannot be | IDLE | the socket run() opened is closed |
2704 | | opened | | again; run() dies with the error |
2705 | BOUND | run(), and the log cannot be | BOUND | the caller's socket is left open; |
2706 | | opened | | run() dies with the error |
2707 | IDLE, | run(), and the socket cannot | (same) | dies "Could not create a UDP |
2708 | LOGGING | be opened | | socket ..." |
2709 | RUNNING | recv() dies (a broken socket) | READY | handlers restored; run() dies with |
2710 | | | | the error; socket and log stay |
2711 | | | | open |
2712 | RUNNING | run() again (from inside the | RUNNING | dies "run() is already running"; |
2713 | | loop) | | the running loop carries on |
2714 | STOPPING | closing the socket dies | IDLE | the log is closed anyway; run() |
2715 | | | | dies with the error |
2716 | (none) | new() with an invalid option | (none) | dies "validate_strict: ..."; no |
2717 | | | | object is made |
2718 +----------+-------------------------------+----------+------------------------------------+
2719  
2720 C<port()>, C<address()>, C<count()>, C<parse_message()> and C<i18n()> never
2721 change the state. C<stop()> outside C<run()> changes nothing that matters,
2722 because C<run()> sets the "running" flag again when it starts.
2723  
2724 =head1 LICENSE AND COPYRIGHT
2725  
2726 Copyright 2026 Nigel Horne.
2727  
2728 Usage is subject to the GPL2 licence terms.
2729 If you use it,
2730 please let me know.
2731  
2732 =cut
2733  
2734 50 1;
« lib/App/Syslogd/I18N.pm ↑ Summary etc/syslogd »