Commit | Line | Data |
---|---|---|
ace9eb22 MW |
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 | |
bf5c2318 | 58 | .BR yaid 's |
ace9eb22 MW |
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 | |
c8e76bde | 99 | .BR @sysconfdir@/yaid.policy . |
ace9eb22 MW |
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 | |
15cc376d | 110 | .BI "\-p, \-\-port=" port |
ace9eb22 MW |
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 | |
c8e76bde | 118 | .BR @sysconfdir@/yaid.policy , |
ace9eb22 MW |
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> |