.so ../ADM/mac .XX setup 497 "Setting Up a Research UNIX System" .nr dP 2 .nr dV 3p .TL Setting Up a Research .UX System .AU Norman Wilson .AI .MH .SP 2 .2C .NH Introduction .PP `Research .UX ' is the .UX system used and fiddled with in the Bell Laboratories Computing Science Research Center. It is often named after the most recent version of the manual. This is the Tenth Edition. .PP The system runs only on VAXes, and only on some CPUs and some peripheral devices. At the moment these include the VAX-11/750, 11/780, and 8550, the MicroVAX II and III, MSCP disks connected to UDA50, KDA50, KDB50, and RQDX3 controllers, and TU78, TE16, and TU81 tapes. Various Ethernet and Datakit controllers are supported. The list is likely to change as time passes. There will probably never be support for DEC HSC50 and HSC70 disk servers. .PP There is no official distribution tape for the system, nor are there any plans to produce one. This reflects our desire to stay out of the software support business; we have enough of that keeping our own machines running. We are, however, willing to send snapshots of our current system to deserving people with the right expectations. We are interested in sharing the system with colleagues; we aren't set up to support customers. .PP Our system is not packaged for novices. It is assumed that anyone who gets a copy is self-sufficient and can read our manuals, the hardware manuals, and the source code to resolve confusions and problems. Each copy of the distribution is hand-crafted at a different time; different kinds of digging around may be necessary to get any given copy running. .PP If you haven't been scared off yet, here are some suggestions about how to get started. .NH Documentation .PP The system changes daily, so the printed manual is always out of date. Check the online manual, and any supplementary printed pages that came with the tape, before taking the printed book as gospel. .PP Neither the online manual nor the printed one is pure; various local programs and local conventions have crept in, especially in the crucial system administration parts. Examples should be taken as examples, not as recipes. .NH Cracking the tape and booting .PP The tape consists of at least a root file system image and a .I tar image to be put in .CW /usr . There may be other files as well. Tapes are hand-crafted, so details do vary; see the notes that came with the tape. .PP The root image is a block-by-block copy of a root file system, containing a kernel binary in .CW /unix specific to your hardware. It is probably exactly five megabytes long. It should be copied (you figure out how) to the beginning of the disk you want to boot from. One way is to plug the disk into some already-running machine with a tape drive, and .P1 0 dd bs=blocksize </dev/rawtape >/dev/rawdisk .P2 .PP The root image includes a boot block that behaves as described in .I reboot (8). On the VAX-11/750 and machines with similar boot ROMs, such as the 8200 (if we ever support it), nothing more is needed. On other VAXes, in particular the 11/780 and the 8500-8700 machines, some boot programs must be installed on the console disk. A floppy and instructions should have come with the tape. .PP Once the root is installed, boot the system to single-user state, .I reboot (8). The kernel image is in file .CW /unix . It is prudent to run .I fsck or .I chuck (8) on the root file system to be sure it's OK. It is mandatory to examine the special files in .CW /dev to make sure they're correct for your disk and tape drives; ...... see .I mknod (8) and the driver writeups referred to there. The special files on the tape bear no necessary correspondence to the ones you need, though we try to supply correct ones for the root file system. .PP To read in .CW /usr , do something like this: .P1 0 # /etc/mkbitfs /dev/ra02 31231 4 40 \fR(make a new 4KB-block file system; see below for details)\fP # /etc/mount /dev/ra02 /usr # cd /usr # mt fsf 1 \fR(skip first file on the tape, the root image)\fP # umask 2 # tar xbf 20 /dev/rmt0 \fR(extract \f(CW/usr\fR files)\fP .P2 .PP The .CW /usr files occupy about 50 megabytes. The .CW umask is needed because .I tar carefully records permissions in the archive, but at the moment neglects to restore them. Most of the directories have group (but not general) write permissions on our system. .I Tar does at least set ownership correctly. .PP There may be a snapshot of our sources as well, in one or more additional tape files or on additional tapes. They won't exactly correspond to the binaries. The tape won't have absolute pathnames on it, and for the most part you can rearrange things as you please (though dependencies do creep in), but the arrangement on the tape reflects our conventions. The source to the operating system belongs in .CW /usr/src/sys ; that to the 5620 software in .CW /usr/jerq/src ; that to everything else in .CW /usr/src . Sources to the network programs live in .CW /usr/src/ipc (even some programs that are installed in .CW /usr/bin ), except the network file system, which is in .CW /usr/src/netb . Most programs are built with .I mk (1), but a few still use .I make instead. Programs with their own directories have their own .I mkfile s; there is one .I mkfile in .CW /usr/src/cmd for all the small programs there. .PP The sources occupy some indeterminate but large amount of space; expect to need at least 135 megabytes. .NH Disks and file systems .PP There are two kinds of disk file system, referred to herein as `classical' and `bitmapped.' A classical file system uses 1024-byte blocks and a V7-style free block list. A bitmapped file system uses 4096-byte blocks and keeps the free block list in a bitmap. Bitmapped file systems come in two flavors: small ones, which keep the free block bitmap in the super-block (which means they can't be much bigger than 120 megabytes), and big ones, which keep the bitmap in the highest-numbered blocks in the file system. We use bitmapped file systems almost exclusively. The root image on the tape will be a bitmapped file system. .PP The system distinguishes classical file systems from bitmapped ones by the minor device number: bitmapped file systems are on devices with numbers greater than 64. A block device with minor number 10 could contain a classical file system; if it contains a bitmapped file system, it should have minor number 74 instead. All the disk drivers ignore the 64 bit. .PP Various tools work with the different kinds of file systems: .IP .I Fsck understands classical and small bitmapped file systems. It doesn't know about big ones yet. .IP .I Chuck understands both kinds of bitmapped file system, but doesn't know how to rebuild the free list in a classical file system. .IP .I Icheck , .I dcheck , and .I ncheck work with all kinds of file system. .PP If you check the block special file, you don't have to reboot the system after fixing the root. We borrowed this simple convenience from 4.1BSD; it seems to have vanished from subsequent Berkeley systems. .PP .I Mkfs makes a classical file system; .I mkbitfs a bitmapped file system, which will be the small kind if possible. To get reasonable speed, it is important to set file system spacing parameters correctly; see .I mkfs (8). In our experience, the `space' number is very important, but the `cylinder size' makes little difference. .PP Read .I mount and .I umount (8) carefully; notice in particular that the arguments to .I umount are mount points like .CW /usr , not special files like .CW /dev/ra02 . .PP An example to get you started: many of our machines have system files on a single RA81. The driver allows the disk to be split into certain sections (\c .I ra (4)). We use these sections: .IP Section 0 (5 megabytes) is the root. .IP Section 1 (10 megabytes) is the swap area. .IP Section 2 (120 megabytes) is .CW /usr . .IP Section 5 (50 megabytes at the high end of the disk) is a rather generous .CW /tmp . .PP Users' files might go in .CW /usr , or in other file systems in the other two 120 megabyte sections; if the latter, we use symbolic links to arrange that .CW /usr/andrew always means .I andrew 's home directory. .PP Backups are somewhat ad hoc. The old V7 .I dump and .I restor programs have long since rotted, and their newer Berkeley-derived kin seem too complicated to be worth adapting. We back up whole file systems simply by copying the special file to tape with .I dd ; 120 megabytes in 16Kbyte blocks fits nicely on a 6250 bpi magtape. Such backups are mostly meant for use when disk drives break; they aren't very convenient when files are accidentally deleted. .PP A more sophisticated and more complicated system for incremental backups is described in .I backup (1) and .I backup (8). .I Cpio and .I tar are simpler possibilities. .NH Files to watch for .PP Most of our machines are run in a fairly open manner; special files for disks and memory often have general read permissions. Most system files and directories may be written by group .I bin ; if the special files aren't generally readable, they may certainly be read by group .I sys . You may want to change some of this, and to browse around generally for holes. .PP Here are some files that have system-dependent contents; the versions on the tape are probably wrong, and must be edited for your system. .de Fp .IP .ne 2 .ti -5n .CW "\\$1" .br .if !'\\$2''\{. .ti -5n .CW "\\$2" .br\} .. .Fp /etc/whoami A single line of text containing this machine's name, printed by .I getty (8), used by .I uucp and miscellaneous network programs. .Fp /n Mount points for network file systems, .I netfs (8). .I .CW /n/ remsys .R is the (empty) directory on which the remote file system for system .I remsys is mounted. .I .CW /n/ myname\c .R , where .I myname is the name in .CW /etc/whoami , is conventionally a symbolic link to .CW / . .Fp /etc/fstab Filesystems to be mounted in normal operation, .I fstab (5). .Fp /etc/ttys Terminal lines to be maintained by .I init and .I getty (8), .I ttys (5). .Fp /etc/crontab List of actions for .I cron (8). .Fp /etc/passwd /etc/group List of users and groups, .I passwd (5). .Fp /etc/rc Script to be executed when the system starts, .I rc (8). .Fp /lib/dst Daylight saving time definitions, .I ctime (3). The timezone is compiled into the kernel, as is a flag that declares whether daylight time ever happens; these are probably both mistakes. .Fp /lib/ttynames List of directories searched by .I ttyname (3). .Fp /etc/aculist List of telephone dialling devices, .I dialout (3). .I Cu and .I uucp depend on this list. .PP If you use networking, .I uucp , or electronic mail, there are other files to fix; details below. .PP Here are some accounting files that should be truncated from time to time: .Fp /usr/adm/wtmp Session accounting, .I login (8). .Fp /usr/adm/messages Record of console messages, .I dmesg (8). .Fp /usr/adm/smdr Autodialler use; written if possible by .I dialout (3). .Fp /usr/spool/mail/mail.log Record of mail sent or delivered, .I upas (8). .Fp /usr/netb/setupl /usr/netb/zarf.log Network file system logs, .I netfs (8). .Fp /usr/ipc/log Directory where various daemons in .CW /usr/ipc/mgrs write log files; .I svcmgr , .I dkmgr , .I tcpmgr (8) among others. .Fp /usr/spool/uucp/.Log Log files from various .I uucp daemons. .PP We run .CW /usr/ipc/servers/daily just before midnight every day; it maintains a week's worth of daily issues of the .CW /usr/ipc/log files and of .CW mail.log . If present, .CW /usr/adm/weekclean and .CW /usr/adm/monthclean show what we do about some of the other files. .NH ..... Setting up mail .PP Everyone has a complicated mail system these days; ours is perhaps simpler than many, but still requires some setting up. There are various files to fix in directory .CW /usr/lib/upas , especially the list of addressing rules in .CW rewrite and the list of local name alias files in .CW namefiles . See .I mail (1) and .I upas (8), and the .I upas paper in Volume 2. .PP The .CW rewrite on the tape knows about local mail and .I uucp , which is probably enough to get you started; the supplied .CW namefiles points at two empty files .CW names.local and .CW names.global . Our usual .CW rewrite file is in .CW rewrite.fancy ; you don't want to use it unchanged, but it is there as an advanced example. Shell scripts like .CW route go with it. Before trying to use them, please read them carefully, and remove things like use of our gateway machine .I research . .NH Setting up uucp .PP Our .I uucp programs belong to the honey danber family, and behave in a mostly standard way. The principle difference is that the programs don't read a single .CW Systems file to look up a system. Instead, they run .CW /usr/lib/uucp/uugrep with an argument naming the system of interest. .I Uugrep is expected to print one or more .CW Systems lines, which may or may not be relevant to that system; the system name in each line must still be checked. .PP Normally .I uugrep just prints the contents of all the files named in .CW /usr/lib/uucp/Sysfiles . However, if the files .CW /usr/lib/uucp/Bsystems.[FT] exist, they are assumed to contain a .I cbt (3) database of .CW Systems entries; .I uugrep searches the database and prints only the lines for the interesting system. If that system isn't found, or one of the original .CW Systems files is newer than the database, the database is ignored and all the files are printed. .PP .I Uugrep without arguments spits out all the entries, and rebuilds the database if necessary. .PP To use the database, create empty .CW Bsystems.T and .CW Bsystems.F files (with the same permissions used for Systems files), and run .P1 0 /usr/lib/uucp/uugrep >/dev/null 2>&1 .P2 Make arrangements to run this whenever one of the .CW Systems files changes; we just do it every hour. .PP .CW /usr/lib/uucp/uudemon.hr is run hourly, .CW uudemon.day daily. Take them as examples. .PP None of the .I uucp files are used by .I cu in our system. .NH Setting up networking .PP The programs in .I con (1) are used to remotely log into another machine and to execute remote commands. .I Push and .I rcp (1) copy files. Our .I push speaks a different (and markedly simpler) language from the DKHOST program of the same name; .I npush and .I npull attempt compatibility. .PP For each kind of network, there is at least one network-specific daemon responsible for listening and dialling. This daemon announces a local name through which outbound calls may be requested. It also listens for inbound calls from the network, maps the network's idea of a service name through some local convention, and calls the appropriate local name for the service. Most local services, login and command execution in particular, are handled by .I svcmgr (8). .PP Local service names, including network dialling, are announced with .I ipccreat and called with .I ipcopen ; see .I ipc (3). The services are usually announced in directory .CW /cs . For example, the Datakit dialler announces itself as .CW /cs/dk ; .I con opens that name with .I ipcopen to place a call. .PP To turn on any network, you must run .I svcmgr . Edit .CW /usr/ipc/lib/serv and .CW auth to contain the desired services and authorization mappings. The ones on the tape are certainly wrong; use them as examples. .PP To turn on Datakit, you must have the right special files in .CW /dev/dk , and must run .I dkhup and .I dkmgr ; see .I dk (4) and .I dkmgr (8). The device files on the tape are probably wrong. Watch out for .CW /dev/dk/dkctl , which should be linked to the common signalling channel; this is channel 1 on production Datakits, but not on most of our machines. .PP If you're using a KMC, run .CW /etc/kdiload to load microcode into it, after editing .CW /etc/kmctab to point at the appropriate KMC microcode: .CW /etc/dkk.kdi for the KMS11-K, .CW /etc/dkk.dubhi for the DUBHI. .I Kmc (8) explains some of this. .PP To turn on TCP/IP, you must run an instance of .I ipconfig (8) for each IP network interface, and one instance of .I tcpmgr (8). If you want to use UDP, run .I udpconfig too. .PP Besides the hardware devices (e.g. an Ethernet controller), these special files are needed for TCP/IP. Channel numbers like that in .CW /dev/tcp01 must always be two digits. .KS .TS c c c lFCW l l. _ file maj,min = /dev/ip0 42,0 for general IP control /dev/iptcp 42,6 for TCP /dev/ip16 42,16 for \fIrouted\fP /dev/ipudp 42,17 for UDP /dev/tcp\fInn\fP 43,\fInn\fP TCP channels /dev/udp\fInn\fP 50,\fInn\fP UDP channels _ .TE .KE .PP Most TCP/IP programs depend on the name service mechanisms described in .I qns (7) and .I ns (8). You must run .I ns , after adjusting .CW /usr/ipc/lib/ns.db . .PP To turn on our kind of network file system, you need to edit files in .CW /usr/netb , and to run certain programs kept there; see .I netfs (8). Our network file system protocol is different from everyone else's. Since our server is just a user program, it is possible with some effort to make it run under other operating systems, making their files accessible to the machine running our system (but not vice versa). For example, some of our machines can see all the files on the local Cray. Look in the sources if you want to do this. .NH Bitmapped terminals .PP There is a fairly extensive set of programs for the Teletype 5620 terminal; see section 9 of the manual, in particular .I intro (9). The programs live in .CW /usr/jerq . Some of the programs have been moved to the AT&T 630 terminal; the 630 versions live in .CW /usr/630 . There is no documentation for the 630 versions, but most are the same as their 5620 cousins. .I 630mux is the window multiplexer. The name is deceptive; .I 630mux terminal windows act like the ones in the 630 ROM, not like those in .I mux . .NH Miscellaneous hardware support .PP If you have a VAX-11/750 with a patchable control store (most do), .I ldpcs (8) will load DEC's microcode patches. .PP The system doesn't replace bad blocks automatically on MSCP disks, but .I rarepl (8) will replace a particular block on request, and .I smash (8) will often make it unnecessary. In our experience, bad block replacement is almost never appropriate on RA81s. .PP On a VAX-11/780, .CW /dev/floppy is the console disk; it should be a character device with major number 8, minor number 0. .I Arff (8) attempts to understand the RT-11 file system format used by the console.