Makefile.am: Tweak `silent-rules' machinery.

[yaid] / yaid.8.in

.\" -*-nroff-*-
.TH yaid 8 "21 October 2012" "Straylight/Edgeware" "Yet Another Ident Daemon"
.SH NAME
yaid \- Yet Another Ident Daemon
.SH SYNOPSIS
.B yaid
.RB [ \-Dl ]
.RB [ \-G
.IR group ]
.RB [ \-P
.IR pidfile ]
.RB [ \-U
.IR user ]
.RB [ \-c
.IR file ]
.RB [ \-p
.IR port ]
.SH DESCRIPTION
The
.B yaid
daemon implements the identification service defined in RFC1413.  This
simple protocol allows a remote server to ask its client host for the
name of the user who made a given connection to it.  It is not useful
for authentication, but may be handy when tracking down the source of a
network problem.
.PP
While
.B yaid
doesn't have any features not found elsewhere, its combination appears
to be unique.
.PP
.B yaid
can handle NAT usefully.  On a gateway providing a NAT disservice to
client hosts, it will detect that the connection it has been asked about
is actually owned by a client, and forward the query to the client.  On
a client host stuck behind NAT, it will detect that a query is coming
from its NAT gateway and respond appropriately.
.PP
.B yaid
also has powerful policy management, allowing convenient fine-grained
control over the response provided to a given query.
.PP
Sending the daemon a
.B SIGINT
or
.B SIGTERM
signal will cause it to shutdown gracefully.
.SS "Command line"
.BR yaid
accepts the following command-line options.
.TP
.B "\-h, \-\-help"
Write to standard output a summary of the command-line options, and exit
with status zero.
.TP
.B "\-v, \-\-version"
Write to standard output
.BR yaid 's
version number, and exit with status zero.
.TP
.B "\-u, \-\-usage"
Write to standard output a one-line synopsis of the command-line syntax,
and exit with status zero.
.TP
.B "\-D, \-\-daemon"
After initializing, fork twice, and run in the background.
.TP
.BI "\-G, \-\-group=" group
After obtaining any resources requiring elevated privilege, set the
daemon's group-id to
.IR group ,
which may be a name or number; if initially running as the superuser
then supplementary group memberships are also abandoned.  The default is
to change to the primary group of the
.I user
named by the
.B \-U
option; if no
.B \-U
option is given either, then don't change group-id.
.TP
.BI "\-P, \-\-pidfile=" file
After forking into the background (if requested using
.BR \-D ),
write the daemon's process id to
.IR file ,
as a single line, in decimal; delete the file on a clean shutdown.
.TP
.BI "\-U, \-\-user=" user
After obtaining any resources requiring elevated privilege, set the
daemon's user-id to
.IR user ,
which may be a name or number.
.TP
.BI "\-c, \-\-config=" file
Read the global policy rules from
.IR file .
The default is to read them from
.BR @sysconfdir@/yaid.policy .
For a description of the policy file, see below.
.TP
.BI "\-l, \-\-syslog"
Write log messages using
.BR syslog (3),
using the
.B daemon
facility.  The default is to write timestamped log messages to standard
error.
.TP
.BI "\-p, \-\-port=" port
Listen for incoming connections on
.IR port ,
which may be a port number, or a TCP service name.
.SS "Policy file"
By default,
.B yaid
reads policy rules from
.BR @sysconfdir@/yaid.policy ,
but this location can be changed using the
.B \-c
option.  These rules, together with the actual connection ownership
information, determine the response given to any particular query.
.PP
The policy file consists of a number of rules, one per line.  It may
also contain blank lines, and comments beginning with a
.RB \` # '.
The first rule to match the query takes effect; subsequent rules are not
examined.
.PP
A policy rule has the following format.
.IP
.I local-addr-pat
.I local-port-pat
.I remote-addr-pat
.I remote-port-pat
.I user-pat
.I action
.PP
The fields are separated with whitespace.
.PP
An address pattern has the form
.IB address / length \fR.
It matches an address if the first
.I length
bits of the two addresses agree.  An
.I address
may be either an IPv4 or IPv6 address, in the numeric form accepted by
.BR inet_pton (3).
.PP
A port pattern has the form
.IR lo [\fB\- hi ].
It matches any port number which lies between
.I lo
and
.I hi
inclusive.
.PP
A user pattern can be either a user name, or may be of the form
.IR lo [\fB\- hi ].
The latter matches any uid lying between
.I lo
and
.I hi
inclusive.
.PP
Also, any of the above patterns may be
.RB ` * ',
which matches anything.
.PP
An action may have one of the following forms.
.TP
.B name
The user's name will be reported honestly, quoting
.B UNIX
as the operating system.
.TP
.B token
Instead of a user name, a random token unrelated to the user name will
be reported, along with the operating system name
.BR OTHER .
.TP
.B deny
Report a
.B NOUSER
error to the client.
.TP
.B hide
Report a
.B HIDDEN
error to the client.
.TP
.BI "lie " name
Report
.I name
as the owner of the connection, with
.B UNIX
as the operating system.
.TP
.BI "user " action " " \fR...
Allow the user who owns the connection to determine the policy.  Further
policy rules are read from
.BI ~ user /.yaid.policy \fR.
If a rule matches the query, and the rule's action matches one of the
listed
.I action
tokens, then that action takes effect.  If no rules match, then the
.B user
rule is considered not to match, and further rules from the global
policy file will be tried.  Only the first 100 lines of a user policy
file are examined.
.PP
In any event, the details of the connection and the real owner (uid and
name) are always written to the log.
.PP
If none of the rules match the query then the
.B name
action is used as a default.
.PP
Changes to the global policy file take place immediately.  There is no
need to send the daemon a signal to notify it of the change.
.SH SEE ALSO
RFC1413,
.IR "Identification Protocol" ,
by M. St. Johns.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>