From ace9eb228c33bdb5ab3848154819e74ad2f2e4b0 Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Sun, 21 Oct 2012 15:49:58 +0100 Subject: [PATCH] yaid.8.in: Add manual page. --- Makefile.am | 6 ++ yaid.8.in | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 yaid.8.in diff --git a/Makefile.am b/Makefile.am index 2b89d59..df95ec2 100644 --- a/Makefile.am +++ b/Makefile.am @@ -55,6 +55,12 @@ yaid_SOURCES = EXTRA_yaid_SOURCES = yaid_LDADD = $(mLib_LIBS) +man_MANS += yaid.8 +EXTRA_DIST += yaid.8.in +CLEANFILES += yaid.8 +yaid.8: yaid.8.in Makefile + $(SUBST) $(srcdir)/yaid.8.in >yaid.8 $(SUBSTITUTIONS) + yaid_SOURCES += yaid.h yaid_SOURCES += yaid.c yaid_SOURCES += addr.c diff --git a/yaid.8.in b/yaid.8.in new file mode 100644 index 0000000..bd0c38f --- /dev/null +++ b/yaid.8.in @@ -0,0 +1,226 @@ +.\" -*-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, -- 2.11.0