| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
MC/DC0%0/1
eval {
do {
131072
}
} // 0
eval {
do {
131072
}
}
Truth table50%1/2
A
A= eval {
do {
131072
}
}
| |||||||||||||||||||||||||||||||||||||||||||
| 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
MC/DC0%0/1
eval {
do {
2048
}
} // 0
eval {
do {
2048
}
}
Truth table50%1/2
A
A= eval {
do {
2048
}
}
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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, \@_) || {}
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, \@_)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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"})
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"})
| |||||||||||||||||||||||||||||||||||||||||||
| 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 || "$!"}))
'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 || "$!"}))
$IO::Socket::errstr || "$!"
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')
Truth table100%3/3
A || B
A= $IO::Socket::errstrB= "$!"
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
$socket and $socket->can("sockport")
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")
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
$socket and $socket->can("sockhost")
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")
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
ref $datagram and not overload::Method($datagram, "\"\"")
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, "\"\"")
| |||||||||||||||||||||||||||||||||||||||||||
| 1466 | 17 | ▶ | croak(($self // __PACKAGE__)->i18n('not_a_datagram', { type => ref($datagram) })); | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self // __PACKAGE__
MC/DC100%1/1
$self // __PACKAGE__
$self
Truth table100%2/2
A
A= $self
| |||||||||||||||||||||||||||||||||||||||||||
| 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 // ""
MC/DC100%1/1
$datagram // ""
$datagram
Truth table100%2/2
A
A= $datagram
| |||||||||||||||||||||||||||||||||||||||||||
| 1471 | |||||||||||||||||||||||||||||||||||||||||||
| 1472 | 440 | ▶ | return undef if(length($text) < $MIN_MESSAGE_LENGTH); ## no critic (ProhibitExplicitReturnUndef): documented, also in list context | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
@match and $match[0] <= $MAX_PRI
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1714 | 76 | $self->open_socket(); | |||||||||||||||||||||||||||||||||||||||||
| 1715 | 71 | ▶ | if(!$self->{fh}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1716 | 42 | ▶ | eval { $self->reopen_log(); 1 } or do { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 1717 | 5 | my $error = $@; | |||||||||||||||||||||||||||||||||||||||||
| 1718 | 5 | ▶ | if(!$socket_was_open && (my $socket = delete $self->{socket})) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
not $socket_was_open and my $socket = delete $self->{"socket"}
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"}
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
defined $peer or $!{"EINTR"}
MC/DC100%2/2
defined $peer or $!{"EINTR"}
defined $peer
$!{"EINTR"}
Truth table100%3/3
A or B
A= defined $peerB= $!{"EINTR"}
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%6/6
-f _ and $st[4] == $> and $st[3] == 1
-f _ and $st[4] == $>
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
-z _ or $self->_starts_with_header($fh)
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)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1989 | 206 | ▶ | eval { $self->_write_header($fh); 1 } or do { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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 // ""
MC/DC100%1/1
$line // ""
$line
Truth table100%2/2
A
A= $line
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 2021 | |||||||||||||||||||||||||||||||||||||||||||
| 2022 | 50 | ▶ | return (length($header) && $start =~ /\A\Q$header\E\r?\n/) ? 1 : 0; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
length $header and $start =~ /\A\Q$header\E\r?\n/
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/
| |||||||||||||||||||||||||||||||||||||||||||
| 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)
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)
| |||||||||||||||||||||||||||||||||||||||||||
| 2054 | 213 | ▶ | croak($self->i18n('write_failed', { file => $self->{file}, error => $error })) if(defined($error)); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 2078 | 470 | my $written = syswrite($fh, $line, length($line) - $done, $done); | |||||||||||||||||||||||||||||||||||||||||
| 2079 | 470 | ▶ | last unless($written); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 2080 | 435 | $done += $written; | |||||||||||||||||||||||||||||||||||||||||
| 2081 | } | ||||||||||||||||||||||||||||||||||||||||||
| 2082 | 461 | ▶ | return undef if($done == length($line)); ## no critic (ProhibitExplicitReturnUndef): undef means success | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 2092 | 8 | my $end = sysseek($fh, 0, SEEK_END); | |||||||||||||||||||||||||||||||||||||||||
| 2093 | 8 | ▶ | truncate($fh, $end - $done) if(defined($end)); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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)
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)
| |||||||||||||||||||||||||||||||||||||||||||
| 2151 | 240 | ▶ | carp($self->i18n('write_failed', { file => $self->{file}, error => $error })) if(defined($error)); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%2/2
$csv->error_diag || 'Text::CSV could not build the line'
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
not defined $peer or ref $peer
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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 //= ""
MC/DC100%1/1
$address //= ""
$address
Truth table100%2/2
A
A= $address
| |||||||||||||||||||||||||||||||||||||||||||
| 2199 | |||||||||||||||||||||||||||||||||||||||||||
| 2200 | 215 | ▶ | return $address unless($self->{resolve} && length($address)); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$self->{"resolve"} and length $address
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 2211 | 52 | }); | |||||||||||||||||||||||||||||||||||||||||
| 2212 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 2213 | |||||||||||||||||||||||||||||||||||||||||||
| 2214 | 52 | ▶ | return (defined($name) && length($name)) ? $name : $address; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $name and length $name
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 2262 | 14 | ▶ | my $wrap = $module->can('_process_one') or next; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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; | |||||||||||||||||||||||||||||||||||||||||