--- /dev/null
+.\" -*-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 'd
+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.profile .
+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
+.B "\-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.profile ,
+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>
~mdw / yaid / commitdiff