| 1 | .\" -*-nroff-*- |
| 2 | .TH yaid 8 "21 October 2012" "Straylight/Edgeware" "Yet Another Ident Daemon" |
| 3 | .SH NAME |
| 4 | yaid \- Yet Another Ident Daemon |
| 5 | .SH SYNOPSIS |
| 6 | .B yaid |
| 7 | .RB [ \-Dl ] |
| 8 | .RB [ \-G |
| 9 | .IR group ] |
| 10 | .RB [ \-P |
| 11 | .IR pidfile ] |
| 12 | .RB [ \-U |
| 13 | .IR user ] |
| 14 | .RB [ \-c |
| 15 | .IR file ] |
| 16 | .RB [ \-p |
| 17 | .IR port ] |
| 18 | .SH DESCRIPTION |
| 19 | The |
| 20 | .B yaid |
| 21 | daemon implements the identification service defined in RFC1413. This |
| 22 | simple protocol allows a remote server to ask its client host for the |
| 23 | name of the user who made a given connection to it. It is not useful |
| 24 | for authentication, but may be handy when tracking down the source of a |
| 25 | network problem. |
| 26 | .PP |
| 27 | While |
| 28 | .B yaid |
| 29 | doesn't have any features not found elsewhere, its combination appears |
| 30 | to be unique. |
| 31 | .PP |
| 32 | .B yaid |
| 33 | can handle NAT usefully. On a gateway providing a NAT disservice to |
| 34 | client hosts, it will detect that the connection it has been asked about |
| 35 | is actually owned by a client, and forward the query to the client. On |
| 36 | a client host stuck behind NAT, it will detect that a query is coming |
| 37 | from its NAT gateway and respond appropriately. |
| 38 | .PP |
| 39 | .B yaid |
| 40 | also has powerful policy management, allowing convenient fine-grained |
| 41 | control over the response provided to a given query. |
| 42 | .PP |
| 43 | Sending the daemon a |
| 44 | .B SIGINT |
| 45 | or |
| 46 | .B SIGTERM |
| 47 | signal will cause it to shutdown gracefully. |
| 48 | .SS "Command line" |
| 49 | .BR yaid |
| 50 | accepts the following command-line options. |
| 51 | .TP |
| 52 | .B "\-h, \-\-help" |
| 53 | Write to standard output a summary of the command-line options, and exit |
| 54 | with status zero. |
| 55 | .TP |
| 56 | .B "\-v, \-\-version" |
| 57 | Write to standard output |
| 58 | .BR yaid 'd |
| 59 | version number, and exit with status zero. |
| 60 | .TP |
| 61 | .B "\-u, \-\-usage" |
| 62 | Write to standard output a one-line synopsis of the command-line syntax, |
| 63 | and exit with status zero. |
| 64 | .TP |
| 65 | .B "\-D, \-\-daemon" |
| 66 | After initializing, fork twice, and run in the background. |
| 67 | .TP |
| 68 | .BI "\-G, \-\-group=" group |
| 69 | After obtaining any resources requiring elevated privilege, set the |
| 70 | daemon's group-id to |
| 71 | .IR group , |
| 72 | which may be a name or number; if initially running as the superuser |
| 73 | then supplementary group memberships are also abandoned. The default is |
| 74 | to change to the primary group of the |
| 75 | .I user |
| 76 | named by the |
| 77 | .B \-U |
| 78 | option; if no |
| 79 | .B \-U |
| 80 | option is given either, then don't change group-id. |
| 81 | .TP |
| 82 | .BI "\-P, \-\-pidfile=" file |
| 83 | After forking into the background (if requested using |
| 84 | .BR \-D ), |
| 85 | write the daemon's process id to |
| 86 | .IR file , |
| 87 | as a single line, in decimal; delete the file on a clean shutdown. |
| 88 | .TP |
| 89 | .BI "\-U, \-\-user=" user |
| 90 | After obtaining any resources requiring elevated privilege, set the |
| 91 | daemon's user-id to |
| 92 | .IR user , |
| 93 | which may be a name or number. |
| 94 | .TP |
| 95 | .BI "\-c, \-\-config=" file |
| 96 | Read the global policy rules from |
| 97 | .IR file . |
| 98 | The default is to read them from |
| 99 | .BR @sysconfdir@/yaid.profile . |
| 100 | For a description of the policy file, see below. |
| 101 | .TP |
| 102 | .BI "\-l, \-\-syslog" |
| 103 | Write log messages using |
| 104 | .BR syslog (3), |
| 105 | using the |
| 106 | .B daemon |
| 107 | facility. The default is to write timestamped log messages to standard |
| 108 | error. |
| 109 | .TP |
| 110 | .B "\-p, \-\-port=" port |
| 111 | Listen for incoming connections on |
| 112 | .IR port , |
| 113 | which may be a port number, or a TCP service name. |
| 114 | .SS "Policy file" |
| 115 | By default, |
| 116 | .B yaid |
| 117 | reads policy rules from |
| 118 | .BR @sysconfdir@/yaid.profile , |
| 119 | but this location can be changed using the |
| 120 | .B \-c |
| 121 | option. These rules, together with the actual connection ownership |
| 122 | information, determine the response given to any particular query. |
| 123 | .PP |
| 124 | The policy file consists of a number of rules, one per line. It may |
| 125 | also contain blank lines, and comments beginning with a |
| 126 | .RB \` # '. |
| 127 | The first rule to match the query takes effect; subsequent rules are not |
| 128 | examined. |
| 129 | .PP |
| 130 | A policy rule has the following format. |
| 131 | .IP |
| 132 | .I local-addr-pat |
| 133 | .I local-port-pat |
| 134 | .I remote-addr-pat |
| 135 | .I remote-port-pat |
| 136 | .I user-pat |
| 137 | .I action |
| 138 | .PP |
| 139 | The fields are separated with whitespace. |
| 140 | .PP |
| 141 | An address pattern has the form |
| 142 | .IB address / length \fR. |
| 143 | It matches an address if the first |
| 144 | .I length |
| 145 | bits of the two addresses agree. An |
| 146 | .I address |
| 147 | may be either an IPv4 or IPv6 address, in the numeric form accepted by |
| 148 | .BR inet_pton (3). |
| 149 | .PP |
| 150 | A port pattern has the form |
| 151 | .IR lo [\fB\- hi ]. |
| 152 | It matches any port number which lies between |
| 153 | .I lo |
| 154 | and |
| 155 | .I hi |
| 156 | inclusive. |
| 157 | .PP |
| 158 | A user pattern can be either a user name, or may be of the form |
| 159 | .IR lo [\fB\- hi ]. |
| 160 | The latter matches any uid lying between |
| 161 | .I lo |
| 162 | and |
| 163 | .I hi |
| 164 | inclusive. |
| 165 | .PP |
| 166 | Also, any of the above patterns may be |
| 167 | .RB ` * ', |
| 168 | which matches anything. |
| 169 | .PP |
| 170 | An action may have one of the following forms. |
| 171 | .TP |
| 172 | .B name |
| 173 | The user's name will be reported honestly, quoting |
| 174 | .B UNIX |
| 175 | as the operating system. |
| 176 | .TP |
| 177 | .B token |
| 178 | Instead of a user name, a random token unrelated to the user name will |
| 179 | be reported, along with the operating system name |
| 180 | .BR OTHER . |
| 181 | .TP |
| 182 | .B deny |
| 183 | Report a |
| 184 | .B NOUSER |
| 185 | error to the client. |
| 186 | .TP |
| 187 | .B hide |
| 188 | Report a |
| 189 | .B HIDDEN |
| 190 | error to the client. |
| 191 | .TP |
| 192 | .BI "lie " name |
| 193 | Report |
| 194 | .I name |
| 195 | as the owner of the connection, with |
| 196 | .B UNIX |
| 197 | as the operating system. |
| 198 | .TP |
| 199 | .BI "user " action " " \fR... |
| 200 | Allow the user who owns the connection to determine the policy. Further |
| 201 | policy rules are read from |
| 202 | .BI ~ user /.yaid.policy \fR. |
| 203 | If a rule matches the query, and the rule's action matches one of the |
| 204 | listed |
| 205 | .I action |
| 206 | tokens, then that action takes effect. If no rules match, then the |
| 207 | .B user |
| 208 | rule is considered not to match, and further rules from the global |
| 209 | policy file will be tried. Only the first 100 lines of a user policy |
| 210 | file are examined. |
| 211 | .PP |
| 212 | In any event, the details of the connection and the real owner (uid and |
| 213 | name) are always written to the log. |
| 214 | .PP |
| 215 | If none of the rules match the query then the |
| 216 | .B name |
| 217 | action is used as a default. |
| 218 | .PP |
| 219 | Changes to the global policy file take place immediately. There is no |
| 220 | need to send the daemon a signal to notify it of the change. |
| 221 | .SH SEE ALSO |
| 222 | RFC1413, |
| 223 | .IR "Identification Protocol" , |
| 224 | by M. St. Johns. |
| 225 | .SH AUTHOR |
| 226 | Mark Wooding, <mdw@distorted.org.uk> |