Aquire serializer before calling ioctl
[dragonfly.git] / share / doc / smm / 01.setup / 5.t
1 .\" Copyright (c) 1980, 1986, 1988, 1993 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
31 .\"
32 .\"     @(#)5.t 8.1 (Berkeley) 7/27/93
33 .\"
34 .ds lq ``
35 .ds rq ''
36 .ds LH "Installing/Operating \*(4B
37 .ds RH Network setup
38 .ds CF \*(Dy
39 .Sh 1 "Network setup"
40 .PP
41 \*(4B provides support for the standard Internet
42 protocols IP, ICMP, TCP, and UDP.  These protocols may be used
43 on top of a variety of hardware devices ranging from
44 serial lines to local area network controllers
45 for the Ethernet.  Network services are split between the
46 kernel (communication protocols) and user programs (user
47 services such as TELNET and FTP).  This section describes
48 how to configure your system to use the Internet networking support.
49 \*(4B also supports the Xerox Network Systems (NS) protocols.
50 IDP and SPP are implemented in the kernel,
51 and other protocols such as Courier run at the user level.
52 \*(4B provides some support for the ISO OSI protocols CLNP
53 TP4, and ESIS.  User level process
54 complete the application protocols such as X.400 and X.500.
55 .Sh 2 "System configuration"
56 .PP
57 To configure the kernel to include the Internet communication
58 protocols, define the INET option.
59 Xerox NS support is enabled with the NS option.
60 ISO OSI support is enabled with the ISO option.
61 In either case, include the pseudo-devices
62 ``pty'', and ``loop'' in your machine's configuration
63 file. 
64 The ``pty'' pseudo-device forces the pseudo terminal device driver
65 to be configured into the system, see
66 .Xr pty (4),
67 while the ``loop'' pseudo-device forces inclusion of the software loopback
68 interface driver.
69 The loop driver is used in network testing
70 and also by the error logging system.
71 .PP
72 If you are planning to use the Internet network facilities on a 10Mb/s
73 Ethernet, the pseudo-device ``ether'' should also be included
74 in the configuration; this forces inclusion of the Address Resolution
75 Protocol module used in mapping between 48-bit Ethernet
76 and 32-bit Internet addresses.
77 .PP
78 Before configuring the appropriate networking hardware, you should
79 consult the manual pages in section 4 of the Programmer's Manual
80 selecting the appropriate interfaces for your architecture.
81 .PP
82 All network interface drivers including the loopback interface,
83 require that their host address(es) be defined at boot time.
84 This is done with
85 .Xr ifconfig (8)
86 commands included in the
87 .Pn /etc/netstart
88 file.
89 Interfaces that are able to dynamically deduce the host
90 part of an address may check that the host part of the address is correct.
91 The manual page for each network interface
92 describes the method used to establish a host's address.
93 .Xr Ifconfig (8)
94 can also be used to set options for the interface at boot time.
95 Options are set independently for each interface, and
96 apply to all packets sent using that interface.
97 Alternatively, translations for such hosts may be set in advance
98 or ``published'' by a \*(4B host by use of the
99 .Xr arp (8)
100 command.
101 Note that the use of trailer link-level is now negotiated between \*(4B hosts
102 using ARP,
103 and it is thus no longer necessary to disable the use of trailers
104 with
105 .Xr ifconfig .
106 .PP
107 The OSI equivalent to ARP is ESIS (End System to Intermediate System Routing
108 Protocol); running this protocol is mandatory, however one can manually add
109 translations for machines that do not participate by use of the
110 .Xr route (8)
111 command.
112 Additional information is provided in the manual page describing
113 .Xr ESIS (4).
114 .PP
115 To use the pseudo terminals just configured, device
116 entries must be created in the
117 .Pn /dev
118 directory.  To create 32
119 pseudo terminals (plenty, unless you have a heavy network load)
120 execute the following commands.
121 .DS
122 \fB#\fP \fIcd /dev\fP
123 \fB#\fP \fIMAKEDEV pty0 pty1\fP
124 .DE
125 More pseudo terminals may be made by specifying
126 .Pn pty2 ,
127 .Pn pty3 ,
128 etc.  The kernel normally includes support for 32 pseudo terminals
129 unless the configuration file specifies a different number.
130 Each pseudo terminal really consists of two files in
131 .Pn /dev :
132 a master and a slave.  The master pseudo terminal file is named
133 .Pn /dev/ptyp? ,
134 while the slave side is
135 .Pn /dev/ttyp? .
136 Pseudo terminals are also used by several programs not related to the network.
137 In addition to creating the pseudo terminals,
138 be sure to install them in the
139 .Pn /etc/ttys
140 file (with a `none' in the second column so no
141 .Xr getty
142 is started).
143 .Sh 2 "Local subnets"
144 .PP
145 In \*(4B the Internet support
146 includes the notion of ``subnets''.  This is a mechanism
147 by which multiple local networks may appears as a single Internet
148 network to off-site hosts.  Subnetworks are useful because
149 they allow a site to hide their local topology, requiring only a single
150 route in external gateways;
151 it also means that local network numbers may be locally administered.
152 The standard describing this change in Internet addressing is RFC-950.
153 .PP
154 To set up local subnets one must first decide how the available
155 address space (the Internet ``host part'' of the 32-bit address)
156 is to be partitioned.
157 Sites with a class A network
158 number have a 24-bit host address space with which to work, sites with a
159 class B network number have a 16-bit host address space, while sites with
160 a class C network number have an 8-bit host address space\**.
161 .FS
162 If you are unfamiliar with the Internet addressing structure, consult
163 ``Address Mappings'', Internet RFC-796, J. Postel; available from
164 the Internet Network Information Center at SRI.
165 .FE
166 To define local subnets you must steal some bits
167 from the local host address space for use in extending the network
168 portion of the Internet address.  This reinterpretation of Internet
169 addresses is done only for local networks; i.e. it is not visible
170 to hosts off-site.  For example, if your site has a class B network
171 number, hosts on this network have an Internet address that contains
172 the network number, 16 bits, and the host number, another
173 16 bits.  To define 254 local subnets, each
174 possessing at most 255 hosts, 8 bits may be taken from the local part.
175 (The use of subnets 0 and all-1's, 255 in this example, is discouraged
176 to avoid confusion about broadcast addresses.)
177 These new network
178 numbers are then constructed by concatenating the original 16-bit network
179 number with the extra 8 bits containing the local subnet number.
180 .PP
181 The existence of local subnets is communicated to the system at the time a
182 network interface is configured with the
183 .I netmask
184 option to the
185 .Xr ifconfig
186 program.  A ``network mask'' is specified to define the
187 portion of the Internet address that is to be considered the network part
188 for that network.
189 This mask normally contains the bits corresponding to the standard
190 network part as well as the portion of the local part
191 that has been assigned to subnets.
192 If no mask is specified when the address is set,
193 it will be set according to the class of the network.
194 For example, at Berkeley (class B network 128.32) 8 bits
195 of the local part have been reserved for defining subnets;
196 consequently the
197 .Pn /etc/netstart
198 file contains lines of the form
199 .DS
200 .ft CW
201 /sbin/ifconfig le0 netmask 0xffffff00
202 .DE
203 This specifies that for interface ``le0'', the upper 24 bits of
204 the Internet address should be used in calculating network numbers
205 (netmask 0xffffff00), and the interface's Internet address is
206 ``'' (host 7 on network 128.32.1).  Hosts \fIm\fP on
207 sub-network \fIn\fP of this network would then have addresses of
208 the form ``128.32.\fIn\fP.\fIm\fP'';  for example, host
209 99 on network 129 would have an address ``''.
210 For hosts with multiple interfaces, the network mask should
211 be set for each interface,
212 although in practice only the mask of the first interface on each network
213 is really used.
214 .Sh 2 "Internet broadcast addresses"
215 .PP
216 The address defined as the broadcast address for Internet networks
217 according to RFC-919 is the address with a host part of all 1's.
218 The address used by 4.2BSD was the address with a host part of 0.
219 \*(4B uses the standard broadcast address (all 1's) by default,
220 but allows the broadcast address to be set (with
221 .Xr ifconfig )
222 for each interface.
223 This allows networks consisting of both 4.2BSD, \*(Ps and \*(4B hosts
224 to coexist while the upgrade process proceeds.
225 In the presence of subnets, the broadcast address uses the subnet field
226 as for normal host addresses, with the remaining host part set to 1's
227 (or 0's, on a network that has not yet been converted).
228 \*(4B hosts recognize and accept packets
229 sent to the logical-network broadcast address as well as those sent
230 to the subnet broadcast address, and when using an all-1's broadcast,
231 also recognize and receive packets sent to host 0 as a broadcast.
232 .Sh 2 "Routing"
233 .PP
234 If your environment allows access to networks not directly
235 attached to your host you will need to set up routing information
236 to allow packets to be properly routed.  Two schemes are
237 supported by the system.  The first scheme
238 employs a routing table management daemon.
239 Optimally, you should use the routing daemon
240 .Xr gated
241 available from Cornell university.
242 We use it on our systems and it works well,
243 especially for multi-homed hosts using Serial Line IP (SLIP).
244 Unfortunately, we were not able to obtain permission to
245 include it on \*(4B.
246 .PP
247 If you do not wish to or cannot obtain
248 .Xr gated ,
249 the distribution does include
250 .Xr routed (8)
251 to maintain the system routing tables.  The routing daemon
252 uses a variant of the Xerox Routing Information Protocol
253 to maintain up to date routing tables in a cluster of local
254 area networks.  By using the
255 .Pn /etc/gateways
256 file, the routing daemon can also be used to initialize static routes
257 to distant networks (see the next section for further discussion).
258 When the routing daemon is started up
259 (usually from
260 .Pn /etc/rc )
261 it reads
262 .Pn /etc/gateways
263 if it exists and installs those routes defined there,
264 then broadcasts on each local network
265 to which the host is attached to find other instances of the routing
266 daemon.  If any responses are received, the routing daemons
267 cooperate in maintaining a globally consistent view of routing
268 in the local environment.  This view can be extended to include
269 remote sites also running the routing daemon by setting up suitable
270 entries in
271 .Pn /etc/gateways ;
272 consult
273 .Xr routed (8)
274 for a more thorough discussion.
275 .PP
276 The second approach is to define a default or wildcard
277 route to a smart
278 gateway and depend on the gateway to provide ICMP routing
279 redirect information to dynamically create a routing data
280 base.  This is done by adding an entry of the form
281 .DS
282 .ft CW
283 /sbin/route add default \fIsmart-gateway\fP 1
284 .DE
285 to
286 .Pn /etc/netstart ;
287 see
288 .Xr route (8)
289 for more information.  The default route
290 will be used by the system as a ``last resort''
291 in routing packets to their destination.  Assuming the gateway
292 to which packets are directed is able to generate the proper
293 routing redirect messages, the system will then add routing
294 table entries based on the information supplied.  This approach
295 has certain advantages over the routing daemon, but is
296 unsuitable in an environment where there are only bridges (i.e.
297 pseudo gateways that, for instance, do not generate routing
298 redirect messages).  Further, if the
299 smart gateway goes down there is no alternative, save manual
300 alteration of the routing table entry, to maintaining service.
301 .PP
302 The system always listens, and processes, routing redirect
303 information, so it is possible to combine both of the above
304 facilities.  For example, the routing table management process
305 might be used to maintain up to date information about routes
306 to geographically local networks, while employing the wildcard
307 routing techniques for ``distant'' networks.  The
308 .Xr netstat (1)
309 program may be used to display routing table contents as well
310 as various routing oriented statistics.  For example,
311 .DS
312 \fB#\fP \fInetstat \-r\fP
313 .DE
314 will display the contents of the routing tables, while
315 .DS
316 \fB#\fP \fInetstat \-r \-s\fP
317 .DE
318 will show the number of routing table entries dynamically
319 created as a result of routing redirect messages, etc.
320 .Sh 2 "Use of \*(4B machines as gateways"
321 .PP
322 Several changes have been made in \*(4B in the area of gateway support
323 (or packet forwarding, if one prefers).
324 A new configuration option, GATEWAY, is used when configuring
325 a machine to be used as a gateway.
326 This option increases the size of the routing hash tables in the kernel.
327 Unless configured with that option,
328 hosts with only a single non-loopback interface never attempt
329 to forward packets or to respond with ICMP error messages to misdirected
330 packets.
331 This change reduces the problems that may occur when different hosts
332 on a network disagree on the network number or broadcast address.
333 Another change is that \*(4B machines that forward packets back through
334 the same interface on which they arrived
335 will send ICMP redirects to the source host if it is on the same network.
336 This improves the interaction of \*(4B gateways with hosts that configure
337 their routes via default gateways and redirects.
338 The generation of redirects may be disabled with the configuration option
339 IPSENDREDIRECTS=0 or while the system is running by using the command:
340 .DS
341 .ft CW
342 sysctl -w net.inet.ip.redirect=0
343 .DE
344 in environments where it may cause difficulties.
345 .Sh 2 "Network databases"
346 .PP
347 Several data files are used by the network library routines
348 and server programs.  Most of these files are host independent
349 and updated only rarely.
350 .br
351 .ne 1i
352 .TS
353 lfC l l.
354 File    Manual reference        Use
355 _
356 /etc/hosts      \fIhosts\fP\|(5)        local host names
357 /etc/networks   \fInetworks\fP\|(5)     network names
358 /etc/services   \fIservices\fP\|(5)     list of known services
359 /etc/protocols  \fIprotocols\fP\|(5)    protocol names
360 /etc/hosts.equiv        \fIrshd\fP\|(8) list of ``trusted'' hosts
361 /etc/netstart   \fIrc\fP\|(8)   command script for initializing network
362 /etc/rc \fIrc\fP\|(8)   command script for starting standard servers
363 /etc/rc.local   \fIrc\fP\|(8)   command script for starting local servers
364 /etc/ftpusers   \fIftpd\fP\|(8) list of ``unwelcome'' ftp users
365 /etc/hosts.lpd  \fIlpd\fP\|(8)  list of hosts allowed to access printers
366 /etc/inetd.conf \fIinetd\fP\|(8)        list of servers started by \fIinetd\fP
367 .TE
368 The files distributed are set up for Internet hosts.
369 Local networks and hosts should be added to describe the local
370 configuration; the Berkeley entries may serve as examples
371 (see also the section on
372 .Pn /etc/hosts ).
373 Network numbers will have to be chosen for each Ethernet.
374 For sites connected to the Internet,
375 the normal channels should be used for allocation of network
376 numbers (contact hostmaster@SRI-NIC.ARPA).
377 For other sites,
378 these could be chosen more or less arbitrarily,
379 but it is generally better to request official numbers
380 to avoid conversion if a connection to the Internet (or others on the Internet)
381 is ever established.
382 .Sh 3 "Network servers"
383 .PP
384 Most network servers are automatically started up at boot time
385 by the command file
386 .Pn /etc/rc
387 or by the Internet daemon (see below).
388 These include the following:
389 .TS
390 lfC l l.
391 Program Server  Started by
392 _
393 /usr/sbin/syslogd       error logging server    \f(CW/etc/rc\fP
394 /usr/sbin/named Internet name server    \f(CW/etc/rc\fP
395 /sbin/routed    routing table management daemon \f(CW/etc/rc\fP
396 /usr/sbin/rwhod system status daemon    \f(CW/etc/rc\fP
397 /usr/sbin/timed time synchronization daemon     \f(CW/etc/rc\fP
398 /usr/sbin/sendmail      SMTP server     \f(CW/etc/rc\fP
399 /usr/libexec/rshd       shell server    inetd
400 /usr/libexec/rexecd     exec server     inetd
401 /usr/libexec/rlogind    login server    inetd
402 /usr/libexec/telnetd    TELNET server   inetd
403 /usr/libexec/ftpd       FTP server      inetd
404 /usr/libexec/fingerd    Finger server   inetd
405 /usr/libexec/tftpd      TFTP server     inetd
406 .TE
407 Consult the manual pages and accompanying documentation (particularly
408 for named and sendmail) for details about their operation.
409 .PP
410 The use of
411 .Xr routed
412 and
413 .Xr rwhod
414 is controlled by shell
415 variables set in
416 .Pn /etc/netstart .
417 By default,
418 .Xr routed
419 is used, but
420 .Xr rwhod
421 is not; they are enabled by setting the variables \fIroutedflags\fP and
422 .Xr rwhod
423 to strings other than ``NO.''
424 The value of \fIroutedflags\fP provides host-specific options to
425 .Xr routed .
426 For example,
427 .DS
428 .ft CW
429 routedflags=-q
430 rwhod=NO
431 .DE
432 would run
433 .Xr "routed -q"
434 and would not run
435 .Xr rwhod .
436 .PP
437 To have other network servers started as well,
438 commands of the following sort should be placed in the site-dependent file
439 .Pn /etc/rc.local .
440 .DS
441 .ft CW
442 if [ -f /usr/sbin/timed ]; then
443         /usr/sbin/timed & echo -n ' timed'                      >/dev/console
444 f\&i
445 .DE
446 .Sh 3 "Internet daemon"
447 .PP
448 In \*(4B most of the servers for user-visible services are started up by a
449 ``super server'', the Internet daemon.  The Internet
450 daemon,
451 .Pn /usr/sbin/inetd ,
452 acts as a master server for
453 programs specified in its configuration file,
454 .Pn /etc/inetd.conf ,
455 listening for service requests for these servers, and starting
456 up the appropriate program whenever a request is received.
457 The configuration file contains lines containing a service
458 name (as found in
459 .Pn /etc/services ),
460 the type of socket the
461 server expects (e.g. stream or dgram), the protocol to be
462 used with the socket (as found in
463 .Pn /etc/protocols ),
464 whether to wait for each server to complete before starting up another,
465 the user name by which the server should run, the server
466 program's name, and at most five arguments to pass to the
467 server program.
468 Some trivial services are implemented internally in
469 .Xr inetd ,
470 and their servers are listed as ``internal.''
471 For example, an entry for the file
472 transfer protocol server would appear as
473 .DS
474 .ft CW
475 ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd
476 .DE
477 Consult
478 .Xr inetd (8)
479 for more detail on the format of the configuration file
480 and the operation of the Internet daemon.
481 .Sh 3 "The \f(CW/etc/hosts.equiv\fP file"
482 .PP
483 The remote login and shell servers use an
484 authentication scheme based on trusted hosts.  The
485 .Pn hosts.equiv
486 file contains a list of hosts that are considered trusted
487 and, under a single administrative control.  When a user
488 contacts a remote login or shell server requesting service,
489 the client process passes the user's name and the official
490 name of the host on which the client is located.  In the simple
491 case, if the host's name is located in
492 .Pn hosts.equiv
493 and the user has an account on the server's machine, then service
494 is rendered (i.e. the user is allowed to log in, or the command
495 is executed).  Users may expand this ``equivalence'' of
496 machines by installing a
497 .Pn \&.rhosts
498 file in their login directory.
499 The root login is handled specially, bypassing the
500 .Pn hosts.equiv
501 file, and using only the
502 .Pn /.rhosts
503 file.
504 .PP
505 Thus, to create a class of equivalent machines, the
506 .Pn hosts.equiv
507 file should contain the \fIofficial\fP names for those machines.
508 If you are running the name server, you may omit the domain part
509 of the host name for machines in your local domain.
510 For example, four machines on our local
511 network are considered trusted, so the
512 .Pn hosts.equiv
513 file is of the form:
514 .DS
515 .ft CW
516 vangogh.CS.Berkeley.EDU
517 picasso.CS.Berkeley.EDU
518 okeeffe.CS.Berkeley.EDU
519 .DE
520 .Sh 3 "The \f(CW/etc/ftpusers\fP file"
521 .PP
522 The FTP server included in the system provides support for an
523 anonymous FTP account.  Because of the inherent security problems
524 with such a facility you should read this section carefully if
525 you consider providing such a service.
526 .PP
527 An anonymous account is enabled by creating a user
528 .Xr ftp .
529 When a client uses the anonymous account a
530 .Xr chroot (2)
531 system call is performed by the server to restrict the client
532 from moving outside that part of the filesystem where the
533 user ftp home directory is located.  Because a
534 .Xr chroot
535 call is used, certain programs and files used by the server
536 process must be placed in the ftp home directory.
537 Further, one must be
538 sure that all directories and executable images are unwritable.
539 The following directory setup is recommended.  The
540 use of the
541 .Xr awk
542 commands to copy the
543 .Pn /etc/passwd
544 and
545 .Pn /etc/group
546 files are \fBSTRONGLY\fP recommended.
547 .DS
548 \fB#\fP \fIcd ~ftp\fP
549 \fB#\fP \fIchmod 555 .; chown ftp .; chgrp ftp .\fP
550 \fB#\fP \fImkdir bin etc pub\fP
551 \fB#\fP \fIchown root bin etc\fP
552 \fB#\fP \fIchmod 555 bin etc\fP
553 \fB#\fP \fIchown ftp pub\fP
554 \fB#\fP \fIchmod 777 pub\fP
555 \fB#\fP \fIcd bin\fP
556 \fB#\fP \fIcp /bin/sh /bin/ls .\fP
557 \fB#\fP \fIchmod 111 sh ls\fP
558 \fB#\fP \fIcd ../etc\fP
559 \fB#\fP \fIawk -F: '{$2="*";print$1":"$2":"$3":"$4":"$5":"$6":"}' < /etc/passwd > passwd\fP
560 \fB#\fP \fIawk -F: '{$2="*";print$1":"$2":"}' < /etc/group > group\fP
561 \fB#\fP \fIchmod 444 passwd group\fP
562 .DE
563 When local users wish to place files in the anonymous
564 area, they must be placed in a subdirectory.  In the
565 setup here, the directory
566 .Pn ~ftp/pub
567 is used.
568 .PP
569 Aside from the problems of directory modes and such,
570 the ftp server may provide a loophole for interlopers
571 if certain user accounts are allowed.
572 The file
573 .Pn /etc/ftpusers
574 is checked on each connection.
575 If the requested user name is located in the file, the
576 request for service is denied.  This file normally has
577 the following names on our systems.
578 .DS
579 uucp
580 root
581 .DE
582 Accounts without passwords need not be listed in this file as the ftp
583 server will refuse service to these users.
584 Accounts with nonstandard shells (any not listed in
585 .Pn /etc/shells )
586 will also be denied access via ftp.