Commit | Line | Data |
---|---|---|
c1c61666 KB |
1 | .\" Copyright (c) 1985, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
55270cae | 3 | .\" |
dcebbf27 | 4 | .\" %sccs.include.redist.man% |
fd869580 | 5 | .\" |
c1c61666 | 6 | .\" @(#)inetd.8 8.1 (Berkeley) %G% |
55270cae | 7 | .\" |
b42074ab CL |
8 | .Dd |
9 | .Dt INETD 8 | |
173b3427 | 10 | .Os BSD 4.4 |
b42074ab CL |
11 | .Sh NAME |
12 | .Nm inetd | |
13 | .Nd internet | |
14 | .Dq super-server | |
15 | .Sh SYNOPSIS | |
16 | .Nm inetd | |
17 | .Op Fl d | |
173b3427 | 18 | .Op Fl R Ar rate |
b42074ab CL |
19 | .Op Ar configuration file |
20 | .Sh DESCRIPTION | |
21 | .Nm Inetd | |
55270cae | 22 | should be run at boot time by |
b42074ab CL |
23 | .Pa /etc/rc.local |
24 | (see | |
25 | .Xr rc 8 ) . | |
55270cae KM |
26 | It then listens for connections on certain |
27 | internet sockets. When a connection is found on one | |
28 | of its sockets, it decides what service the socket | |
29 | corresponds to, and invokes a program to service the request. | |
30 | After the program is | |
31 | finished, it continues to listen on the socket (except in some cases which | |
32 | will be described below). Essentially, | |
b42074ab | 33 | .Nm inetd |
55270cae KM |
34 | allows running one daemon to invoke several others, |
35 | reducing load on the system. | |
b42074ab | 36 | .Pp |
173b3427 | 37 | The options available for |
b42074ab CL |
38 | .Nm inetd: |
39 | .Bl -tag -width Ds | |
40 | .It Fl d | |
41 | Turns on debugging. | |
173b3427 AC |
42 | .It Fl R Ar rate |
43 | Specifies the maximum number of times a service can be invoked | |
44 | in one minute; the default is 1000. | |
b42074ab CL |
45 | .El |
46 | .Pp | |
55270cae | 47 | Upon execution, |
b42074ab | 48 | .Nm inetd |
55270cae KM |
49 | reads its configuration information from a configuration |
50 | file which, by default, is | |
b42074ab | 51 | .Pa /etc/inetd.conf . |
55270cae KM |
52 | There must be an entry for each field of the configuration |
53 | file, with entries for each field separated by a tab or | |
54 | a space. Comments are denoted by a ``#'' at the beginning | |
55 | of a line. There must be an entry for each field. The | |
56 | fields of the configuration file are as follows: | |
b42074ab CL |
57 | .Pp |
58 | .Bd -unfilled -offset indent -compact | |
59 | service name | |
60 | socket type | |
61 | protocol | |
62 | wait/nowait | |
63 | user | |
64 | server program | |
65 | server program arguments | |
66 | .Ed | |
67 | .Pp | |
173b3427 AC |
68 | There are two types of services that |
69 | .Nm inetd | |
70 | can start: standard and TCPMUX. | |
71 | A standard service has a well-known port assigned to it; | |
72 | it may be a service that implements an official Internet standard or is a | |
73 | BSD-specific service. | |
74 | As described in | |
75 | .Tn RFC 1078 , | |
76 | TCPMUX services are nonstandard services that do not have a | |
77 | well-known port assigned to them. | |
78 | They are invoked from | |
79 | .Nm inetd | |
80 | when a program connects to the | |
81 | .Dq tcpmux | |
82 | well-known port and specifies | |
83 | the service name. | |
84 | This feature is useful for adding locally-developed servers. | |
85 | .Pp | |
55270cae | 86 | The |
b42074ab | 87 | .Em service-name |
55270cae KM |
88 | entry is the name of a valid service in |
89 | the file | |
b42074ab CL |
90 | .Pa /etc/services . |
91 | For | |
92 | .Dq internal | |
93 | services (discussed below), the service | |
55270cae | 94 | name |
b42074ab | 95 | .Em must |
63c183b7 | 96 | be the official name of the service (that is, the first entry in |
b42074ab | 97 | .Pa /etc/services ) . |
173b3427 AC |
98 | For TCPMUX services, the value of the |
99 | .Em service-name | |
100 | field consists of the string | |
101 | .Dq tcpmux | |
102 | followed by a slash and the | |
103 | locally-chosen service name. | |
104 | The service names listed in | |
105 | .Pa /etc/services | |
106 | and the name | |
107 | .Dq help | |
108 | are reserved. | |
109 | Try to choose unique names for your TCPMUX services by prefixing them with | |
110 | your organization's name and suffixing them with a version number. | |
b42074ab | 111 | .Pp |
55270cae | 112 | The |
b42074ab CL |
113 | .Em socket-type |
114 | should be one of | |
115 | .Dq stream , | |
116 | .Dq dgram , | |
117 | .Dq raw , | |
118 | .Dq rdm , | |
119 | or | |
120 | .Dq seqpacket , | |
55270cae KM |
121 | depending on whether the socket is a stream, datagram, raw, |
122 | reliably delivered message, or sequenced packet socket. | |
173b3427 AC |
123 | TCPMUX services must use |
124 | .Dq stream . | |
b42074ab | 125 | .Pp |
55270cae | 126 | The |
b42074ab | 127 | .Em protocol |
55270cae | 128 | must be a valid protocol as given in |
b42074ab CL |
129 | .Pa /etc/protocols . |
130 | Examples might be | |
131 | .Dq tcp | |
132 | or | |
133 | .Dq udp . | |
173b3427 AC |
134 | TCPMUX services must use |
135 | .Dq tcp . | |
b42074ab | 136 | .Pp |
55270cae | 137 | The |
b42074ab | 138 | .Em wait/nowait |
55270cae | 139 | entry is applicable to datagram sockets only (other sockets should |
b42074ab CL |
140 | have a |
141 | .Dq nowait | |
142 | entry in this space). If a datagram server connects | |
55270cae | 143 | to its peer, freeing the socket so |
b42074ab | 144 | .Nm inetd |
55270cae | 145 | can received further messages on the socket, it is said to be |
b42074ab CL |
146 | a |
147 | .Dq multi-threaded | |
148 | server, and should use the | |
149 | .Dq nowait | |
55270cae KM |
150 | entry. For datagram servers which process all incoming datagrams |
151 | on a socket and eventually time out, the server is said to be | |
b42074ab CL |
152 | .Dq single-threaded |
153 | and should use a | |
154 | .Dq wait | |
155 | entry. | |
156 | .Xr Comsat 8 | |
157 | .Pq Xr biff 1 | |
158 | and | |
159 | .Xr talkd 8 | |
160 | are both examples of the latter type of | |
55270cae | 161 | datagram server. |
b42074ab | 162 | .Xr Tftpd 8 |
63c183b7 | 163 | is an exception; it is a datagram server that establishes pseudo-connections. |
b42074ab CL |
164 | It must be listed as |
165 | .Dq wait | |
166 | in order to avoid a race; | |
63c183b7 MK |
167 | the server reads the first packet, creates a new socket, |
168 | and then forks and exits to allow | |
b42074ab | 169 | .Nm inetd |
63c183b7 | 170 | to check for new service requests to spawn new servers. |
173b3427 AC |
171 | TCPMUX services must use |
172 | .Dq nowait . | |
b42074ab | 173 | .Pp |
55270cae | 174 | The |
b42074ab | 175 | .Em user |
55270cae KM |
176 | entry should contain the user name of the user as whom the server |
177 | should run. This allows for servers to be given less permission | |
178 | than root. | |
b42074ab | 179 | .Pp |
55270cae | 180 | The |
b42074ab | 181 | .Em server-program |
55270cae KM |
182 | entry should contain the pathname of the program which is to be |
183 | executed by | |
b42074ab | 184 | .Nm inetd |
55270cae | 185 | when a request is found on its socket. If |
b42074ab | 186 | .Nm inetd |
55270cae | 187 | provides this service internally, this entry should |
b42074ab CL |
188 | be |
189 | .Dq internal . | |
190 | .Pp | |
191 | The | |
192 | .Em server program arguments | |
193 | should be just as arguments | |
55270cae KM |
194 | normally are, starting with argv[0], which is the name of |
195 | the program. If the service is provided internally, the | |
b42074ab CL |
196 | word |
197 | .Dq internal | |
198 | should take the place of this entry. | |
199 | .Pp | |
200 | .Nm Inetd | |
201 | provides several | |
202 | .Dq trivial | |
203 | services internally by use of | |
204 | routines within itself. These services are | |
205 | .Dq echo , | |
206 | .Dq discard , | |
207 | .Dq chargen | |
208 | (character generator), | |
209 | .Dq daytime | |
210 | (human readable time), and | |
211 | .Dq time | |
212 | (machine readable time, | |
55270cae KM |
213 | in the form of the number of seconds since midnight, January |
214 | 1, 1900). All of these services are tcp based. For | |
b42074ab CL |
215 | details of these services, consult the appropriate |
216 | .Tn RFC | |
55270cae | 217 | from the Network Information Center. |
b42074ab CL |
218 | .Pp |
219 | .Nm Inetd | |
220 | rereads its configuration file when it receives a hangup signal, | |
221 | .Dv SIGHUP . | |
f8cbfd03 MK |
222 | Services may be added, deleted or modified when the configuration file |
223 | is reread. | |
173b3427 AC |
224 | .Sh TCPMUX |
225 | .Pp | |
226 | .Tn RFC 1078 | |
227 | describes the TCPMUX protocol: | |
228 | ``A TCP client connects to a foreign host on TCP port 1. It sends the | |
229 | service name followed by a carriage-return line-feed <CRLF>. The | |
230 | service name is never case sensitive. The server replies with a | |
231 | single character indicating positive (+) or negative (\-) | |
232 | acknowledgment, immediately followed by an optional message of | |
233 | explanation, terminated with a <CRLF>. If the reply was positive, | |
234 | the selected protocol begins; otherwise the connection is closed.'' | |
235 | The program is passed the TCP connection as file descriptors 0 and 1. | |
236 | .Pp | |
237 | If the TCPMUX service name begins with a ``+'', | |
238 | .Nm inetd | |
239 | returns the positive reply for the program. | |
240 | This allows you to invoke programs that use stdin/stdout | |
241 | without putting any special server code in them. | |
242 | .Pp | |
243 | The special service name | |
244 | .Dq help | |
245 | causes | |
246 | .Nm inetd | |
247 | to list TCPMUX services in | |
248 | .Pa inetd.conf . | |
249 | .Sh "EXAMPLES" | |
250 | .Pp | |
251 | Here are several example service entries for the various types of services: | |
252 | .Bd -literal | |
253 | ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l | |
254 | ntalk dgram udp wait root /usr/libexec/ntalkd ntalkd | |
255 | tcpmux/+date stream tcp nowait guest /bin/date date | |
256 | tcpmux/phonebook stream tcp nowait guest /usr/local/bin/phonebook phonebook | |
257 | .Ed | |
258 | .Sh "ERROR MESSAGES" | |
259 | .Nm Inetd | |
260 | logs error messages using | |
261 | .Xr syslog 3 . | |
262 | Important error messages and their explanations are: | |
263 | .Bd -literal | |
264 | \fIservice\fP/\fIprotocol\fP server failing (looping), service terminated. | |
265 | .Ed | |
266 | The number of requests for the specified service in the past minute | |
267 | exceeded the limit. The limit exists to prevent a broken program | |
268 | or a malicious user from swamping the system. | |
269 | This message may occur for several reasons: | |
270 | 1) there are lots of hosts requesting the service within a short time period, | |
271 | 2) a 'broken' client program is requesting the service too frequently, | |
272 | 3) a malicious user is running a program to invoke the service in | |
273 | a 'denial of service' attack, or | |
274 | 4) the invoked service program has an error that causes clients | |
275 | to retry quickly. | |
276 | Use the | |
277 | .Op Fl R | |
278 | option, | |
279 | as described above, to change the rate limit. | |
280 | Once the limit is reached, the service will be | |
281 | reenabled automatically in 10 minutes. | |
282 | .sp | |
283 | .Bd -literal | |
284 | \fIservice\fP/\fIprotocol\fP: No such user '\fIuser\fP', service ignored | |
285 | \fIservice\fP/\fIprotocol\fP: getpwnam: \fIuser\fP: No such user | |
286 | .Ed | |
287 | No entry for | |
288 | .Em user | |
289 | exists in the | |
290 | .Pa passwd | |
291 | file. The first message | |
292 | occurs when | |
293 | .Nm inetd | |
294 | (re)reads the configuration file. The second message occurs when the | |
295 | service is invoked. | |
296 | .sp | |
297 | .Bd -literal | |
298 | \fIservice\fP: can't set uid \fInumber\fP | |
299 | \fIservice\fP: can't set gid \fInumber\fP | |
300 | .Ed | |
301 | The user or group ID for the entry's | |
302 | .Em user | |
303 | is invalid. | |
b42074ab CL |
304 | .Sh SEE ALSO |
305 | .Xr comsat 8 , | |
306 | .Xr fingerd 8 , | |
307 | .Xr ftpd 8 , | |
308 | .Xr rexecd 8 , | |
309 | .Xr rlogind 8 , | |
310 | .Xr rshd 8 , | |
311 | .Xr telnetd 8 , | |
312 | .Xr tftpd 8 | |
313 | .Sh HISTORY | |
314 | The | |
315 | .Nm | |
316 | command appeared in | |
317 | .Bx 4.3 . | |
173b3427 | 318 | TCPMUX is based on code and documentation by Mark Lottor. |