diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml index 8ead931d08..153f212121 100644 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ b/en_US.ISO8859-1/articles/multi-os/article.sgml @@ -1,743 +1,755 @@ %authors; + + +%trademarks; ]>
Installing and Using FreeBSD With Other Operating Systems Jay Richmond
jayrich@sysc.com
6 August 1996 + + &tm-attrib.freebsd; + &tm-attrib.ibm; + &tm-attrib.linux; + &tm-attrib.microsoft; + &tm-attrib.powerquest; + &tm-attrib.general; + + This document discusses how to make FreeBSD coexist nicely - with other popular operating systems such as Linux, MS-DOS, - OS/2, and Windows 95. Special thanks to: Annelise Anderson + with other popular operating systems such as Linux, &ms-dos;, + &os2;, and &windows; 95. Special thanks to: Annelise Anderson andrsn@stanford.edu, Randall Hopper rhh@ct.picker.com, and &a.jkh;. Overview Most people can not fit these operating systems together comfortably without having a larger hard disk, so special information on large EIDE drives is included. Because there are so many combinations of possible operating systems and hard disk configurations, the section may be of the most use to you. It contains descriptions of specific working computer setups that use multiple operating systems. This document assumes that you have already made room on your hard disk for an additional operating system. Any time you repartition your hard drive, you run the risk of destroying the data on the original partitions. However, if your hard drive is completely occupied by DOS, you might find the FIPS utility (included on the FreeBSD CDROM in the \TOOLS directory or via ftp) useful. It lets you repartition your hard disk without destroying the data already on it. There is also a commercial - program available called Partition Magic, which lets you size + program available called &partitionmagic;, which lets you size and delete partitions without consequence. Overview of Boot Managers These are just brief descriptions of some of the different boot managers you may encounter. Depending on your computer setup, you may find it useful to use more than one of them on the same system. Boot Easy This is the default boot manager used with FreeBSD. It has the ability to boot most anything, including BSD, - OS/2 (HPFS), Windows 95 (FAT and FAT32), and Linux. + &os2; (HPFS), &windows; 95 (FAT and FAT32), and Linux. Partitions are selected with the function keys. - OS/2 Boot Manager + &os2; Boot Manager This will boot FAT, FAT32, HPFS, FFS (FreeBSD), and EXT2 (Linux). Partitions - are selected using arrow keys. The OS/2 Boot Manager is + are selected using arrow keys. The &os2; Boot Manager is the only one to use its own separate partition, unlike the others which use the master boot record (MBR). Therefore, it must be installed below the 1024th cylinder to avoid booting problems. It can boot Linux using LILO when it is part of the boot sector, not the MBR. Go to Linux HOWTOs on the World Wide Web for more - information on booting Linux with OS/2's boot + information on booting Linux with the &os2; boot manager. OS-BS This is an alternative to Boot Easy. It gives you more control over the booting process, with the ability to set the default partition to boot and the booting timeout. The beta version of this programs allows you to boot by selecting the OS with your arrow keys. It is included on the FreeBSD CD in the \TOOLS directory, and via ftp. LILO, or LInux LOader This is a limited boot manager. It will boot FreeBSD, though some customization work is required in the LILO configuration file. About FAT32 FAT32 is the replacement to the FAT filesystem included in Microsoft's OEM SR2 Beta release, which started replacing FAT - on computers pre-loaded with Windows 95 towards the + on computers pre-loaded with &windows; 95 towards the end of 1996. It converts the normal FAT filesystem and allows you to use smaller cluster sizes for larger hard drives. FAT32 also modifies the traditional FAT boot sector and allocation table, making it incompatible with some boot managers. A Typical Installation Let's say I have two large EIDE hard drives, and I want to - install FreeBSD, Linux, and Windows 95 on them. + install FreeBSD, Linux, and &windows; 95 on them. Here is how I might do it using these hard disks: /dev/wd0 (first physical hard disk) /dev/wd1 (second hard disk) Both disks have 1416 cylinders. - I boot from a MS-DOS or Windows 95 boot disk that + I boot from a &ms-dos; or &windows; 95 boot disk that contains the FDISK.EXE utility and make a small - 50 MB primary partition (35-40 for Windows 95, plus a + 50 MB primary partition (35-40 for &windows; 95, plus a little breathing room) on the first disk. Also create a - larger partition on the second hard disk for my Windows + larger partition on the second hard disk for my &windows; applications and data. - I reboot and install Windows 95 (easier said than done) + I reboot and install &windows; 95 (easier said than done) on the C: partition. The next thing I do is install Linux. I am not sure about all the distributions of Linux, but Slackware includes LILO (see ). When I am partitioning out my hard disk with Linux fdisk, I would put all of Linux on the first drive (maybe 300 MB for a nice root partition and some swap space). After I install Linux, and are prompted about installing LILO, make sure that I install it on the boot sector of my root Linux partition, not in the MBR (master boot record). The remaining hard disk space can go to FreeBSD. I also make sure that my FreeBSD root slice does not go beyond the 1024th cylinder. (The 1024th cylinder is 528 MB into the disk with our hypothetical 720 MB disks). I will use the rest of the hard drive (about 270 MB) for the /usr and / slices if I wish. The rest of the second hard disk (size depends on the amount of - my Windows application/data partition that I created in step + my &windows; application/data partition that I created in step 1) can go to the /usr/src slice and swap space. - When viewed with the Windows 95 fdisk + When viewed with the &windows; 95 fdisk utility, my hard drives should now look something like this: --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 1 Partition Status Type Volume_Label Mbytes System Usage C: 1 A PRI DOS 50 FAT** 7% 2 A Non-DOS (Linux) 300 43% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 2 Partition Status Type Volume_Label Mbytes System Usage D: 1 A PRI DOS 420 FAT** 60% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- ** May say FAT16 or FAT32 if you are using the OEM SR2 update. See . Install FreeBSD. I make sure to boot with my first hard disk set at NORMAL in the BIOS. If it is not, I will have the enter my true disk geometry at boot time (to - get this, boot Windows 95 and consult Microsoft Diagnostics + get this, boot &windows; 95 and consult Microsoft Diagnostics (MSD.EXE), or check your BIOS) with the parameter hd0=1416,16,63 where 1416 is the number of cylinders on my hard disk, 16 is the number of heads per track, and 63 is the number of sectors per track on the drive. When partitioning out the hard disk, I make sure to install Boot Easy on the first disk. I do not worry about the second disk, nothing is booting off of it. When I reboot, Boot Easy should recognize my three - bootable partitions as DOS (Windows 95), Linux, and BSD + bootable partitions as DOS (&windows; 95), Linux, and BSD (FreeBSD). Special Considerations Most operating systems are very picky about where and how - they are placed on the hard disk. Windows 95 and DOS need to be - on the first primary partition on the first hard disk. OS/2 is + they are placed on the hard disk. &windows; 95 and DOS need to be + on the first primary partition on the first hard disk. &os2; is the exception. It can be installed on the first or second disk in a primary or extended partition. If you are not sure, keep the beginning of the bootable partitions below the 1024th cylinder. - If you install Windows 95 on an existing BSD system, it will + If you install &windows; 95 on an existing BSD system, it will destroy the MBR, and you will have to reinstall your previous boot manager. Boot Easy can be reinstalled by using the BOOTINST.EXE utility included in the \TOOLS directory on the CDROM, and via ftp. You can also re-start the installation process and go to the partition editor. From there, mark the FreeBSD partition as bootable, select Boot Manager, and then type W to (W)rite out the information to the MBR. You can now reboot, and Boot Easy - should then recognize Windows 95 as DOS. + should then recognize &windows; 95 as DOS. - Please keep in mind that OS/2 can read FAT and HPFS + Please keep in mind that &os2; can read FAT and HPFS partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. - Likewise, Windows 95 can only read and write to FAT and FAT32 + Likewise, &windows; 95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most filesystems, but currently cannot read HPFS partitions. Linux can read HPFS partitions, but can not write to them. Recent - versions of the Linux kernel (2.x) can read and write to Windows - 95 VFAT partitions (VFAT is what gives Windows 95 long file + versions of the Linux kernel (2.x) can read and write to &windows; + 95 VFAT partitions (VFAT is what gives &windows; 95 long file names - it is pretty much the same as FAT). Linux can read and write to most filesystems. Got that? I hope so. Examples (section needs work, please send your example to jayrich@sysc.com). - FreeBSD+Win95: If you installed FreeBSD after Windows 95, + FreeBSD + &windows; 95: If you installed FreeBSD after &windows; 95, you should see DOS on the Boot Easy menu. This is - Windows 95. If you installed Windows 95 after FreeBSD, read + &windows; 95. If you installed &windows; 95 after FreeBSD, read above. As long as your hard disk does not have 1024 cylinders you should not have a problem booting. If one of your partitions goes beyond the 1024th cylinder however, and you get messages like invalid system disk - under DOS (Windows 95) and FreeBSD will not boot, try looking + under DOS (&windows; 95) and FreeBSD will not boot, try looking for a setting in your BIOS called > 1024 cylinder support or NORMAL/LBA mode. DOS may need LBA (Logical Block Addressing) in order to boot correctly. If the idea of switching BIOS settings every time you boot up does not appeal to you, you can boot FreeBSD through DOS via the FBSDBOOT.EXE utility on the CD (It should find your FreeBSD partition and boot it.) - FreeBSD+OS/2+Win95: Nothing new here. OS/2's boot manager + FreeBSD + &os2; + &windows; 95: Nothing new here. The &os2; boot manager can boot all of these operating systems, so that should not be a problem. - FreeBSD+Linux: You can also use Boot Easy to boot both + FreeBSD + Linux: You can also use Boot Easy to boot both operating systems. - FreeBSD+Linux+Win95: (see ) + FreeBSD + Linux + &windows; 95: (see ) Other Sources of Help There are many Linux HOW-TOs that deal with multiple operating systems on the same hard disk. The Linux+DOS+Win95+OS2 - mini-HOWTO offers help on configuring the OS/2 boot + mini-HOWTO offers help on configuring the &os2; boot manager, and the Linux+FreeBSD mini-HOWTO might be interesting as well. The Linux-HOWTO is also helpful. The NT + URL="http://www.tburke.net/info/ntldr/ntldr_hacking_guide.htm">&windowsnt; Loader Hacking Guide provides good information on - multibooting Windows NT, '95, and DOS with other operating + multibooting &windowsnt;, &windows; 95, and DOS with other operating systems. And Hale Landis's How It Works document pack contains some good info on all sorts of disk geometry and booting related topics. You can find it at . Finally, do not overlook FreeBSD's kernel documentation on the booting procedure, available in the kernel source distribution (it unpacks to /usr/src/sys/i386/boot/biosboot/README.386BSD. Technical Details (Contributed by Randall Hopper, rhh@ct.picker.com) This section attempts to give you enough basic information about your hard disks and the disk booting process so that you can troubleshoot most problems you might encounter when getting set up to boot several operating systems. It starts in pretty basic terms, so you may want to skim down in this section until it begins to look unfamiliar and then start reading. Disk Primer Three fundamental terms are used to describe the location of data on your hard disk: Cylinders, Heads, and Sectors. It is not particularly important to know what these terms relate to except to know that, together, they identify where data is physically on your disk. Your disk has a particular number of cylinders, number of heads, and number of sectors per cylinder-head (a cylinder-head also known now as a track). Collectively this information defines the physical disk geometry for your hard disk. There are typically 512 bytes per sector, and 63 sectors per track, with the number of cylinders and heads varying widely from disk to disk. Thus you can figure the number of bytes of data that will fit on your own disk by calculating: (# of cylinders) × (# heads) × (63 sectors/track) × (512 bytes/sect) For example, on my 1.6 Gig Western Digital AC31600 EIDE hard disk, that is: (3148 cyl) × (16 heads) × (63 sectors/track) × (512 bytes/sect) which is 1,624,670,208 bytes, or around 1.6 Gig. You can find out the physical disk geometry (number of cylinders, heads, and sectors/track counts) for your hard disks using ATAID or other programs off the net. Your hard disk probably came with this information as well. Be careful though: if you are using BIOS LBA (see ), you can not use just any program to get the physical geometry. This is because many programs (e.g. MSD.EXE or FreeBSD fdisk) do not identify the physical disk geometry; they instead report the translated geometry (virtual numbers from using LBA). Stay tuned for what that means. One other useful thing about these terms. Given 3 numbers—a cylinder number, a head number, and a sector-within-track number—you identify a specific absolute sector (a 512 byte block of data) on your disk. Cylinders and Heads are numbered up from 0, and Sectors are numbered up from 1. For those that are interested in more technical details, information on disk geometry, boot sectors, BIOSes, etc. can be found all over the net. Query Lycos, Yahoo, etc. for boot sector or master boot record. Among the useful info you will find are Hale Landis's How It Works document pack. See the section for a few pointers to this pack. Ok, enough terminology. We are talking about booting here. The Booting Process On the first sector of your disk (Cyl 0, Head 0, Sector 1) lives the Master Boot Record (MBR). It contains a map of your disk. It identifies up to 4 partitions, each of which is a contiguous chunk of that disk. FreeBSD calls partitions slices to avoid confusion with its own partitions, but we will not do that here. Each partition can contain its own operating system. Each partition entry in the MBR has a Partition ID, a Start Cylinder/Head/Sector, and an End Cylinder/Head/Sector. The Partition ID tells what type of partition it is (what OS) and the Start/End tells where it is. lists a smattering of some common Partition IDs. Partition IDs ID (hex) Description 01 Primary DOS12 (12-bit FAT) 04 Primary DOS16 (16-bit FAT) 05 Extended DOS 06 Primary big DOS (> 32MB) 0A - OS/2 + &os2; 83 Linux (EXT2FS) A5 FreeBSD, NetBSD, 386BSD (UFS)
Note that not all partitions are bootable (e.g. Extended DOS). Some are—some are not. What makes a partition bootable is the configuration of the Partition Boot Sector that exists at the beginning of each partition. When you configure your favorite boot manager, it looks up the entries in the MBR partition tables of all your hard disks and lets you name the entries in that list. Then when you boot, the boot manager is invoked by special code in the Master Boot Sector of the first probed hard disk on your system. It looks at the MBR partition table entry corresponding to the partition choice you made, uses the Start Cylinder/Head/Sector information for that partition, loads up the Partition Boot Sector for that partition, and gives it control. That Boot Sector for the partition itself contains enough information to start loading the operating system on that partition. One thing we just brushed past that is important to know. All of your hard disks have MBRs. However, the one that is important is the one on the disk that is first probed by the BIOS. If you have only IDE hard disks, its the first IDE disk (e.g. primary disk on first controller). Similarly for SCSI only systems. If you have both IDE and SCSI hard disks though, the IDE disk is typically probed first by the BIOS, so the first IDE disk is the first probed disk. The boot manager you will install will be hooked into the MBR on this first probed hard disk that we have just described. Booting Limitations and Warnings Now the interesting stuff that you need to watch out for. The dreaded 1024 cylinder limit and how BIOS LBA helps The first part of the booting process is all done through the BIOS, (if that is a new term to you, the BIOS is a software chip on your system motherboard which provides startup code for your computer). As such, this first part of the process is subject to the limitations of the BIOS interface. The BIOS interface used to read the hard disk during this period (INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 bits to the Head Number, and 6 bits to the Sector Number. This restricts users of this interface (i.e. boot managers hooked into your disk's MBR as well as OS loaders hooked into the Boot Sectors) to the following limits: 1024 cylinders, max 256 heads, max 64 sectors/track, max (actually 63, 0 is not available) Now big hard disks have lots of cylinders but not a lot of heads, so invariably with big hard disks the number of cylinders is greater than 1024. Given this and the BIOS interface as is, you can not boot off just anywhere on your hard disk. The boot code (the boot manager and the OS loader hooked into all bootable partitions' Boot Sectors) has to reside below cylinder 1024. In fact, if your hard disk is typical and has 16 heads, this equates to: 1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) × 512 bytes/sector which is around the often-mentioned 528MB limit. This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA gives the user of the BIOS API calls access to physical cylinders above 1024 though the BIOS interfaces by redefining a cylinder. That is, it remaps your cylinders and heads, making it appear through the BIOS as though the disk has fewer cylinders and more heads than it actually does. In other words, it takes advantage of the fact that hard disks have relatively few heads and lots of cylinders by shifting the balance between number of cylinders and number of heads so that both numbers lie below the above-mentioned limits (1024 cylinders, 256 heads). With BIOS LBA, the hard disk size limitation is virtually removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA BIOS, you can put FreeBSD or any OS anywhere you want and not hit the 1024 cylinder limit. To use my 1.6 Gig Western Digital as an example again, its physical geometry is: (3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) However, my BIOS LBA remaps this to: (787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) giving the same effective size disk, but with cylinder and head counts within the BIOS API's range (Incidentally, I have both Linux and FreeBSD existing on one of my hard disks above the 1024th physical cylinder, and both operating systems boot fine, thanks to BIOS LBA). Boot Managers and Disk Allocation Another gotcha to watch out when installing boot managers is allocating space for your boot manager. It is best to be aware of this issue up front to save yourself from having to reinstall one or more of your OSs. If you followed the discussion in about the Master Boot Sector (where the MBR is), Partition Boot Sectors, and the booting process, you may have been wondering just exactly where on your hard disk that nifty boot manager is going to live. Well, some boot managers are small enough to fit entirely within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with the partition table. Others need a bit more room and actually extend a few sectors past the Master Boot Sector in the Cylinder 0 Head 0 track, since that is typically free…typically. That is the catch. Some operating systems (FreeBSD included) let you start their partitions right after the Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give FreeBSD's sysinstall a disk with an empty chunk up front or the whole disk empty, that is where it will start the FreeBSD partition by default (at least it did when I fell into this trap). Then when you go to install your boot manager, if it is one that occupies a few extra sectors after the MBR, it will overwrite the front of the first partition's data. In the case of FreeBSD, this overwrites the disk label, and renders your FreeBSD partition unbootable. The easy way to avoid this problem (and leave yourself the flexibility to try different boot managers later) is just to always leave the first full track on your disk unallocated when you partition your disk. That is, leave the space from Cylinder 0, Head 0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and start your first partition at Cylinder 0, Head 1, Sector 1. For what it is worth, when you create a DOS partition at the front of your disk, DOS leaves this space open by default (this is why some boot managers assume it is free). So creating a DOS partition up at the front of your disk avoids this problem altogether. I like to do this myself, creating 1 Meg DOS partition up front, because it also avoids my primary DOS drive letters shifting later when I repartition. For reference, the following boot managers use the Master Boot Sector to store their code and data: OS-BS 1.35 Boot Easy LILO These boot managers use a few additional sectors after the Master Boot Sector: OS-BS 2.0 Beta 8 (sectors 2-5) - OS/2's boot manager + The &os2; boot manager What if your machine will not boot? At some point when installing boot managers, you might leave the MBR in a state such that your machine will not boot. This is unlikely, but possible when re-FDISKing underneath an already-installed boot manager. If you have a bootable DOS partition on your disk, you can boot off a DOS floppy, and run: A:\> FDISK /MBR to put the original, simple DOS boot code back into the system. You can then boot DOS (and DOS only) off the hard drive. Alternatively, just re-run your boot manager installation program off a bootable floppy.
diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml index 5438d8d551..35529d9d68 100644 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ b/en_US.ISO8859-1/articles/new-users/article.sgml @@ -1,1058 +1,1069 @@ %man; %mailing-lists; %freebsd; + +%trademarks; ]>
For People New to Both FreeBSD and &unix; Annelise Anderson
andrsn@andrsn.stanford.edu
 August 15, 1997 + + &tm-attrib.freebsd; + &tm-attrib.ibm; + &tm-attrib.microsoft; + &tm-attrib.netscape; + &tm-attrib.opengroup; + &tm-attrib.general; + + Congratulations on installing FreeBSD! This introduction is for people new to both FreeBSD and - Un*x—so it starts with basics. It assumes you are using + &unix;—so it starts with basics. It assumes you are using version 2.0.5 or later of FreeBSD as distributed by BSDi or FreeBSD.org, your system (for now) has a single user - (you)—and you are probably pretty good with DOS/Windows - or OS/2. + (you)—and you are probably pretty good with DOS/&windows; + or &os2;. Logging in and Getting Out Log in (when you see login:) as a user you created during installation or as root. (Your FreeBSD installation will already have an account for root; root can go anywhere and do anything, including deleting essential files, so be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the prompt (yours may be different), with &prompt.user; indicating an ordinary user and &prompt.root; indicating root. To log out (and get a new login: prompt) type &prompt.root; exit as often as necessary. Yes, press enter after commands, and remember that &unix; is case-sensitive—exit, not EXIT. To shut down the machine type &prompt.root; /sbin/shutdown -h now Or to reboot type &prompt.root; /sbin/shutdown -r now or &prompt.root; /sbin/reboot You can also reboot with CtrlAltDelete. Give it a little time to do its work. This is equivalent to /sbin/reboot in recent releases of FreeBSD and is much, much better than hitting the reset button. You do not want to have to reinstall this thing, do you? Adding A User with Root Privileges If you did not create any users when you installed the system and are thus logged in as root, you should probably create a user now with &prompt.root; adduser The first time you use adduser, it might ask for some defaults to save. You might want to make the default shell &man.csh.1; instead of &man.sh.1;, if it suggests sh as the default. Otherwise just press enter to accept each default. These defaults are saved in /etc/adduser.conf, an editable file. Suppose you create a user jack with full name Jack Benimble. Give jack a password if security (even kids around who might pound on the keyboard) is an issue. When it asks you if you want to invite jack into other groups, type wheel Login group is ``jack''. Invite jack into other groups: wheel This will make it possible to log in as jack and use the &man.su.1; command to become root. Then you will not get scolded any more for logging in as root. You can quit adduser any time by typing CtrlC, and at the end you will have a chance to approve your new user or simply type n for no. You might want to create a second new user (jill?) so that when you edit jack's login files, you will have a hot spare in case something goes wrong. Once you have done this, use exit to get back to a login prompt and log in as jack. In general, it is a good idea to do as much work as possible as an ordinary user who does not have the power—and risk—of root. If you already created a user and you want the user to be able to su to root, you can log in as root and edit the file /etc/group, adding jack to the first line (the group wheel). But first you need to practice &man.vi.1;, the text editor—or use the simpler text editor, &man.ee.1;, installed on recent version of FreeBSD. To delete a user, use the rmuser command. Looking Around Logged in as an ordinary user, look around and try out some commands that will access the sources of help and information within FreeBSD. Here are some commands and what they do: id Tells you who you are! pwd Shows you where you are—the current working directory. ls Lists the files in the current directory. ls Lists the files in the current directory with a * after executables, a / after directories, and an @ after symbolic links. ls Lists the files in long format—size, date, permissions. ls Lists hidden dot files with the others. If you are root, the dot files show up without the switch. cd Changes directories. cd .. backs up one level; note the space after cd. cd /usr/local goes there. cd ~ goes to the home directory of the person logged in—e.g., /usr/home/jack. Try cd /cdrom, and then ls, to find out if your CDROM is mounted and working. view filename Lets you look at a file (named filename) without changing it. Try view /etc/fstab. :q to quit. cat filename Displays filename on screen. If it is too long and you can see only the end of it, press ScrollLock and use the up-arrow to move backward; you can use ScrollLock with manual pages too. Press ScrollLock again to quit scrolling. You might want to try cat on some of the dot files in your home directory—cat .cshrc, cat .login, cat .profile. You will notice aliases in .cshrc for some of the ls commands (they are very convenient). You can create other aliases by editing .cshrc. You can make these aliases available to all users on the system by putting them in the system-wide csh configuration file, /etc/csh.cshrc. Getting Help and Information Here are some useful sources of help. Text stands for something of your choice that you type in—usually a command or filename. apropos text Everything containing string text in the whatis database. man text The manual page for text. The - major source of documentation for Un*x systems. + major source of documentation for &unix; systems. man ls will tell you all the ways to use the ls command. Press Enter to move through text, CtrlB to go back a page, CtrlF to go forward, q or CtrlC to quit. which text Tells you where in the user's path the command text is found. locate text All the paths where the string text is found. whatis text Tells you what the command text does and its manual page. Typing whatis * will tell you about all the binaries in the current directory. whereis text Finds the file text, giving its full path. You might want to try using whatis on some common useful commands like cat, more, grep, mv, find, tar, chmod, chown, date, and script. more lets you read a page at a time as it does in DOS, e.g., ls -l | more or more filename. The * works as a wildcard—e.g., ls w* will show you files beginning with w. Are some of these not working very well? Both &man.locate.1; and &man.whatis.1; depend on a database that is rebuilt weekly. If your machine is not going to be left on over the weekend (and running FreeBSD), you might want to run the commands for daily, weekly, and monthly maintenance now and then. Run them as root and give each one time to finish before you start the next one, for now. &prompt.root; periodic daily output omitted &prompt.root; periodic weekly output omitted &prompt.root; periodic monthly output omitted If you get tired of waiting, press AltF2 to get another virtual console, and log in again. After all, it is a multi-user, multi-tasking system. Nevertheless these commands will probably flash messages on your screen while they are running; you can type clear at the prompt to clear the screen. Once they have run, you might want to look at /var/mail/root and /var/log/messages. Running such commands is part of system - administration—and as a single user of a Unix system, + administration—and as a single user of a &unix; system, you are your own system administrator. Virtually everything you need to be root to do is system administration. Such responsibilities are not covered very well even in those big fat - books on Unix, which seem to devote a lot of space to pulling + books on &unix;, which seem to devote a lot of space to pulling down menus in windows managers. You might want to get one of the two leading books on systems administration, either Evi Nemeth et.al.'s UNIX System Administration Handbook (Prentice-Hall, 1995, ISBN 0-13-15051-7)—the second edition with the red cover; or Æleen Frisch's Essential System Administration (O'Reilly & Associates, 1993, ISBN 0-937175-80-3). I used Nemeth. Editing Text To configure your system, you need to edit text files. Most of them will be in the /etc directory; and you will need to su to root to be able to change them. You can use the easy ee, but in the long run the text editor vi is worth learning. There is an excellent tutorial on vi in /usr/src/contrib/nvi/docs/tutorial if you have that installed; otherwise you can get it by FTP to ftp.cdrom.com in the directory FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. Before you edit a file, you should probably back it up. Suppose you want to edit /etc/rc.conf. You could just use cd /etc to get to the /etc directory and do: &prompt.root; cp rc.conf rc.conf.orig This would copy rc.conf to rc.conf.orig, and you could later copy rc.conf.orig to rc.conf to recover the original. But even better would be moving (renaming) and then copying back: &prompt.root; mv rc.conf rc.conf.orig &prompt.root; cp rc.conf.orig rc.conf because the mv command preserves the original date and owner of the file. You can now edit rc.conf. If you want the original back, you would then mv rc.conf rc.conf.myedit (assuming you want to preserve your edited version) and then &prompt.root; mv rc.conf.orig rc.conf to put things back the way they were. To edit a file, type &prompt.root; vi filename Move through the text with the arrow keys. Esc (the escape key) puts vi in command mode. Here are some commands: x delete letter the cursor is on dd delete the entire line (even if it wraps on the screen) i insert text at the cursor a insert text after the cursor Once you type i or a, you can enter text. Esc puts you back in command mode where you can type :w to write your changes to disk and continue editing :wq to write and quit :q! to quit without saving changes /text to move the cursor to text; /Enter (the enter key) to find the next instance of text. G to go to the end of the file nG to go to line n in the file, where n is a number CtrlL to redraw the screen Ctrlb and Ctrlf go back and forward a screen, as they do with more and view. Practice with vi in your home directory by creating a new file with vi filename and adding and deleting text, saving the file, and calling it up again. vi delivers some surprises because it is really quite complex, and sometimes you will inadvertently issue a command that will do something you do not expect. (Some people actually like vi—it is more powerful than DOS EDIT—find out about the :r command.) Use Esc one or more times to be sure you are in command mode and proceed from there when it gives you trouble, save often with :w, and use :q! to get out and start over (from your last :w) when you need to. Now you can cd to /etc, su to root, use vi to edit the file /etc/group, and add a user to wheel so the user has root privileges. Just add a comma and the user's login name to the end of the first line in the file, press Esc, and use :wq to write the file to disk and quit. Instantly effective. (You did not put a space after the comma, did you?) Printing Files from DOS At this point you probably do not have the printer working, so here is a way to create a file from a manual page, move it to a floppy, and then print it from DOS. Suppose you want to read carefully about changing permissions on files (pretty important). You can use man chmod to read about it. The command &prompt.user; man chmod | col -b > chmod.txt will remove formatting codes and send the manual page to the chmod.txt file instead of showing it on your screen. Now put a dos-formatted diskette in your floppy drive a, su to root, and type &prompt.root; /sbin/mount -t msdos /dev/fd0 /mnt to mount the floppy drive on /mnt. Now (you no longer need to be root, and you can type exit to get back to being user jack) you can go to the directory where you created chmod.txt and copy the file to the floppy with: &prompt.user; cp chmod.txt /mnt and use ls /mnt to get a directory listing of /mnt, which should show the file chmod.txt. You might especially want to make a file from /sbin/dmesg by typing &prompt.user; /sbin/dmesg > dmesg.txt and copying dmesg.txt to the floppy. /sbin/dmesg is the boot log record, and it is useful to understand it because it shows what FreeBSD found when it booted up. If you ask questions on the &a.questions; or on a USENET group—like FreeBSD is not finding my tape drive, what do I do?—people will want to know what dmesg has to say. You can now dismount the floppy drive (as root) to get the disk out with &prompt.root; /sbin/umount /mnt and reboot to go to DOS. Copy these files to a DOS - directory, call them up with DOS EDIT, Windows Notepad or + directory, call them up with DOS EDIT, &windows; Notepad or Wordpad, or a word processor, make a minor change so the file has to be saved, and print as you normally would from DOS or Windows. Hope it works! manual pages come out best if printed with the DOS print command. (Copying files from FreeBSD to a mounted DOS partition is in some cases still a little risky.) Getting the printer printing from FreeBSD involves creating an appropriate entry in /etc/printcap and creating a matching spool directory in /var/spool/output. If your printer is on lpt0 (what DOS calls LPT1), you may only need to go to /var/spool/output and (as root) create the directory lpd by typing: mkdir lpd, if it does not already exist. Then the printer should respond if it is turned on when the system is booted, and lp or lpr should send a file to the printer. Whether or not the file actually prints depends on configuring it, which is covered in the FreeBSD handbook. Other Useful Commands df shows file space and mounted systems. ps aux shows processes running. ps ax is a narrower form. rm filename remove filename. rm -R dir removes a directory dir and all subdirectories—careful! ls -R lists files in the current directory and all subdirectories; I used a variant, ls -AFR > where.txt, to get a list of all the files in / and (separately) /usr before I found better ways to find files. passwd to change user's password (or root's password) man hier - manual page on the Unix filesystem + manual page on the &unix; filesystem Use find to locate filename in /usr or any of its subdirectories with &prompt.user; find /usr -name "filename" You can use * as a wildcard in "filename" (which should be in quotes). If you tell find to search in / instead of /usr it will look for the file(s) on all mounted filesystems, including the CDROM and the DOS partition. - An excellent book that explains Unix commands and utilities + An excellent book that explains &unix; commands and utilities is Abrahams & Larson, Unix for the Impatient (2nd ed., Addison-Wesley, 1996). - There is also a lot of Unix information on the Internet. Try the + There is also a lot of &unix; information on the Internet. Try the Unix Reference Desk. Next Steps You should now have the tools you need to get around and edit files, so you can get everything up and running. There is a great deal of information in the FreeBSD handbook (which is probably on your hard drive) and FreeBSD's web site. A wide variety of packages and ports are on the CDROM as well as the web site. The handbook tells you more about how to use them (get the package if it exists, with pkg_add /cdrom/packages/All/packagename, where packagename is the filename of the package). The CDROM has lists of the packages and ports with brief descriptions in cdrom/packages/index, cdrom/packages/index.txt, and cdrom/ports/index, with fuller descriptions in /cdrom/ports/*/*/pkg/DESCR, where the *s represent subdirectories of kinds of programs and program names respectively. If you find the handbook too sophisticated (what with lndir and all) on installing ports from the CDROM, here is what usually works: Find the port you want, say kermit. There will be a directory for it on the CDROM. Copy the subdirectory to /usr/local (a good place for software you add that should be available to all users) with: &prompt.root; cp -R /cdrom/ports/comm/kermit /usr/local This should result in a /usr/local/kermit subdirectory that has all the files that the kermit subdirectory on the CDROM has. Next, create the directory /usr/ports/distfiles if it does not already exist using mkdir. Now check /cdrom/ports/distfiles for a file with a name that indicates it is the port you want. Copy that file to /usr/ports/distfiles; in recent versions you can skip this step, as FreeBSD will do it for you. In the case of kermit, there is no distfile. Then cd to the subdirectory of /usr/local/kermit that has the file Makefile. Type &prompt.root; make all install During this process the port will FTP to get any compressed files it needs that it did not find on the CDROM or in /usr/ports/distfiles. If you do not have your network running yet and there was no file for the port in /cdrom/ports/distfiles, you will have to get the distfile using another machine and copy it to /usr/ports/distfiles from a floppy or your DOS partition. Read Makefile (with cat or more or view) to find out where to go (the master distribution site) to get the file and what its name is. Its name will be truncated when downloaded to DOS, and after you get it into /usr/ports/distfiles you will have to rename it (with the mv command) to its original name so it can be found. (Use binary file transfers!) Then go back to /usr/local/kermit, find the directory with Makefile, and type make all install. The other thing that happens when installing ports or packages is that some other program is needed. If the installation stops with a message can't find unzip or whatever, you might need to install the package or port for unzip before you continue. Once it is installed type rehash to make FreeBSD reread the files in the path so it knows what is there. (If you get a lot of path not found messages when you use whereis or which, you might want to make additions to the list of directories in the path statement in .cshrc in your home - directory. The path statement in Unix does the same kind of + directory. The path statement in &unix; does the same kind of work it does in DOS, except the current directory is not (by default) in the path for security reasons; if the command you want is in the directory you are in, you need to type ./ before the command to make it work; no space after the slash.) - You might want to get the most recent version of Netscape + You might want to get the most recent version of &netscape; from their FTP site. - (Netscape requires the X Window System.) There is now a FreeBSD + (&netscape; requires the X Window System.) There is now a FreeBSD version, so look around carefully. Just use gunzip filename and tar xvf filename on it, move the binary to /usr/local/bin or some other place binaries are kept, rehash, and then put the following lines in .cshrc in each user's home directory or (easier) in /etc/csh.cshrc, the system-wide csh start-up file: setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB setenv XNLSPATH /usr/X11R6/lib/X11/nls This assumes that the file XKeysymDB and the directory nls are in /usr/X11R6/lib/X11; if they are not, find them and put them there. - If you originally got Netscape as a port using the CDROM (or + If you originally got &netscape; as a port using the CDROM (or FTP), do not replace /usr/local/bin/netscape with the new netscape binary; this is just a shell script that sets up the environment variables for you. Instead rename the new binary to netscape.bin and replace the old binary, which is /usr/local/netscape/netscape. Your Working Environment Your shell is the most important part of your working environment. In DOS, the usual shell is command.com. The shell is what interprets the commands you type on the command line, and thus communicates with the rest of the operating system. You can also write shell scripts, which are like DOS batch files: a series of commands to be run without your intervention. Two shells come installed with FreeBSD: csh and sh. csh is good for command-line work, but scripts should be written with sh (or bash). You can find out what shell you have by typing echo $SHELL. The csh shell is okay, but tcsh does everything csh does and more. It allows you to recall commands with the arrow keys and edit them. It has tab-key completion of filenames (csh uses the Esc key), and it lets you switch to the directory you were last in with cd -. It is also much easier to alter your prompt with tcsh. It makes life a lot easier. Here are the three steps for installing a new shell: Install the shell as a port or a package, just as you would any other port or package. Use rehash and which tcsh (assuming you are installing tcsh) to make sure it got installed. As root, edit /etc/shells, adding a line in the file for the new shell, in this case /usr/local/bin/tcsh, and save the file. (Some ports may do this for you.) Use the chsh command to change your shell to tcsh permanently, or type tcsh at the prompt to change your shell without logging in again. It can be dangerous to change root's shell to something other than sh or csh on - early versions of FreeBSD and many other versions of Unix; you + early versions of FreeBSD and many other versions of &unix;; you may not have a working shell when the system puts you into single user mode. The solution is to use su -m to become root, which will give you the tcsh as root, because the shell is part of the environment. You can make this permanent by adding it to your .tcshrc file as an alias with: alias su su -m When tcsh starts up, it will read the /etc/csh.cshrc and /etc/csh.login files, as does csh. It will also read the .login file in your home directory and the .cshrc file as well, unless you provide a .tcshrc file. This you can do by simply copying .cshrc to .tcshrc. Now that you have installed tcsh, you can adjust your prompt. You can find the details in the manual page for tcsh, but here is a line to put in your .tcshrc that will tell you how many commands you have typed, what time it is, and what directory you are in. It also produces a > if you are an ordinary user and a # if you are root, but tsch will do that in any case: set prompt = "%h %t %~ %# " This should go in the same place as the existing set prompt line if there is one, or under "if($?prompt) then" if not. Comment out the old line; you can always switch back to it if you prefer it. Do not forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. You can get a listing of other environmental variables that have been set by typing env at the prompt. The result will show you your default editor, pager, and terminal type, among possibly many others. A useful command if you log in from a remote location and can not run a program because the terminal is not capable is setenv TERM vt100. Other As root, you can dismount the CDROM with /sbin/umount /cdrom, take it out of the drive, insert another one, and mount it with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming cd0a is the device name for your CDROM drive. The most recent versions of FreeBSD let you mount the CDROM with just /sbin/mount /cdrom. Using the live filesystem—the second of FreeBSD's CDROM disks—is useful if you have got limited space. What is on the live filesystem varies from release to release. You might try playing games from the CDROM. This involves using lndir, which gets installed with the X Window System, to tell the program(s) where to find the necessary files, because they are in the /cdrom file system instead of in /usr and its subdirectories, which is where they are expected to be. Read man lndir. Comments Welcome If you use this guide I would be interested in knowing where it was unclear and what was left out that you think should be included, and if it was helpful. My thanks to Eugene W. Stark, professor of computer science at SUNY-Stony Brook, and John Fieber for helpful comments. Annelise Anderson, andrsn@andrsn.stanford.edu
diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml index 6a63a7286d..9f81155977 100644 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ b/en_US.ISO8859-1/articles/pam/article.sgml @@ -1,1334 +1,1333 @@ %man; + + +%freebsd; + + +%trademarks; ]>
Pluggable Authentication Modules $FreeBSD$ This article describes the underlying principles and mechanisms of the Pluggable Authentication Modules (PAM) library, and explains how to configure PAM, how to integrate PAM into applications, and how to write PAM modules. 2001 2002 2003 Networks Associates Technology, Inc. Dag-Erling Smørgrav Contributed by This article was written for the FreeBSD Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (CBOSS), as part of the DARPA CHATS research program. + + + &tm-attrib.freebsd; + &tm-attrib.opengroup; + &tm-attrib.sun; + &tm-attrib.general; +
Introduction The Pluggable Authentication Modules (PAM) library is a generalized API for authentication-related services which allows a system administrator to add new authentication methods simply by installing new PAM modules, and to modify authentication policies by editing configuration files. PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun Microsystems, and has not changed much since. In 1997, the Open Group published the X/Open Single Sign-on (XSSO) preliminary specification, which standardized the PAM API and added extensions for single (or rather integrated) sign-on. At the time of this writing, this specification has not yet been adopted as a standard. Although this article focuses primarily on FreeBSD 5.x, which uses OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses Linux-PAM, and other operating systems such as - Linux and Solaris. - -
- Trademarks - - Sun, Sun Microsystems, SunOS and Solaris are trademarks or - registered trademarks of Sun Microsystems, Inc. - - UNIX and The Open Group are trademarks or registered - trademarks of The Open Group. - - All other brand or product names mentioned in this - document may be trademarks or registered trademarks of their - respective owners. -
+ Linux and &solaris;.
Terms and conventions
Definitions The terminology surrounding PAM is rather confused. Neither Samar and Lai's original paper nor the XSSO specification made any attempt at formally defining terms for the various actors and entities involved in PAM, and the terms that they do use (but do not define) are sometimes misleading and ambiguous. The first attempt at establishing a consistent and unambiguous terminology was a whitepaper written by Andrew G. Morgan (author of Linux-PAM) in 1999. While Morgan's choice of terminology was a huge leap forward, it is in this author's opinion by no means perfect. What follows is an attempt, heavily inspired by Morgan, to define precise and unambiguous terms for all actors and entities involved in PAM. account The set of credentials the applicant is requesting from the arbitrator. applicant The user or entity requesting authentication. arbitrator The user or entity who has the privileges necessary to verify the applicant's credentials and the authority to grant or deny the request. chain A sequence of modules that will be invoked in response to a PAM request. The chain includes information about the order in which to invoke the modules, what arguments to pass to them, and how to interpret the results. client The application responsible for initiating an authentication request on behalf of the applicant and for obtaining the necessary authentication information from him. facility One of the four basic groups of functionality provided by PAM: authentication, account management, session management and authentication token update. module A collection of one or more related functions implementing a particular authentication facility, gathered into a single (normally dynamically loadable) binary file and identified by a single name. policy The complete set of configuration statements describing how to handle PAM requests for a particular service. A policy normally consists of four chains, one for each facility, though some services do not use all four facilities. server The application acting on behalf of the arbitrator to converse with the client, retrieve authentication information, verify the applicant's credentials and grant or deny requests. service A class of servers providing similar or related functionality and requiring similar authentication. PAM policies are defined on a per-service basis, so all servers that claim the same service name will be subject to the same policy. session The context within which service is rendered to the applicant by the server. One of PAM's four facilities, session management, is concerned exclusively with setting up and tearing down this context. token A chunk of information associated with the account, such as a password or passphrase, which the applicant must provide to prove his identity. transaction A sequence of requests from the same applicant to the same instance of the same server, beginning with authentication and session set-up and ending with session tear-down.
Usage examples This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple examples.
Client and server are one This simple example shows alice &man.su.1;'ing to root. &prompt.user; whoami alice &prompt.user; ls -l `which su` -r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su &prompt.user; su - Password: xi3kiune &prompt.root; whoami root The applicant is alice. The account is root. The &man.su.1; process is both client and server. The authentication token is xi3kiune. The arbitrator is root, which is why &man.su.1; is setuid root.
Client and server are separate The example below shows eve try to initiate an &man.ssh.1; connection to login.example.com, ask to log in as bob, and succeed. Bob should have chosen a better password! &prompt.user; whoami eve &prompt.user; ssh bob@login.example.com bob@login.example.com's password: god Last login: Thu Oct 11 09:52:57 2001 from 192.168.0.1 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD 4.4-STABLE (LOGIN) #4: Tue Nov 27 18:10:34 PST 2001 Welcome to FreeBSD! &prompt.user; The applicant is eve. The client is Eve's &man.ssh.1; process. The server is the &man.sshd.8; process on login.example.com The account is bob. The authentication token is god. Although this is not shown in this example, the arbitrator is root.
Sample policy The following is FreeBSD's default policy for sshd: sshd auth required pam_nologin.so no_warn sshd auth required pam_unix.so no_warn try_first_pass sshd account required pam_login_access.so sshd account required pam_unix.so sshd session required pam_lastlog.so no_fail sshd password required pam_permit.so This policy applies to the sshd service (which is not necessarily restricted to the &man.sshd.8; server.) auth, account, session and password are facilities. pam_nologin.so, pam_unix.so, pam_login_access.so, pam_lastlog.so and pam_permit.so are modules. It is clear from this example that pam_unix.so provides at least two facilities (authentication and account management.)
Conventions This section has not yet been written.
PAM Essentials
Facilities and primitives The PAM API offers six different authentication primitives grouped in four facilities, which are described below. auth Authentication. This facility concerns itself with authenticating the applicant and establishing the account credentials. It provides two primitives: &man.pam.authenticate.3; authenticates the applicant, usually by requesting an authentication token and comparing it with a value stored in a database or obtained from an authentication server. &man.pam.setcred.3; establishes account credentials such as user ID, group membership and resource limits. account Account management. This facility handles non-authentication-related issues of account availability, such as access restrictions based on the time of day or the server's work load. It provides a single primitive: &man.pam.acct.mgmt.3; verifies that the requested account is available. session Session management. This facility handles tasks associated with session set-up and tear-down, such as login accounting. It provides two primitives: &man.pam.open.session.3; performs tasks associated with session set-up: add an entry in the utmp and wtmp databases, start an SSH agent, etc. &man.pam.close.session.3; performs tasks associated with session tear-down: add an entry in the utmp and wtmp databases, stop the SSH agent, etc. password Password management. This facility is used to change the authentication token associated with an account, either because it has expired or because the user wishes to change it. It provides a single primitive: &man.pam.chauthtok.3; changes the authentication token, optionally verifying that it is sufficiently hard to guess, has not been used previously, etc.
Modules Modules are a very central concept in PAM; after all, they are the M in PAM. A PAM module is a self-contained piece of program code that implements the primitives in one or more facilities for one particular mechanism; possible mechanisms for the - authentication facility, for instance, include the UNIX + authentication facility, for instance, include the &unix; password database, NIS, LDAP and Radius.
Module Naming FreeBSD implements each mechanism in a single module, named pam_mechanism.so - (for instance, pam_unix.so for the Unix + (for instance, pam_unix.so for the &unix; mechanism.) Other implementations sometimes have separate modules for separate facilities, and include the facility name as well as the mechanism name in the module name. To - name one example, Solaris has a + name one example, &solaris; has a pam_dial_auth.so.1 module which is commonly used to authenticate dialup users.
Module Versioning FreeBSD's original PAM implementation, based on Linux-PAM, did not use version numbers for PAM modules. This would commonly cause problems with legacy applications, which might be linked against older versions of the system libraries, as there was no way to load a matching version of the required modules. OpenPAM, on the other hand, looks for modules that have the same version number as the PAM library (currently 2), and only falls back to an unversioned module if no versioned module could be loaded. Thus legacy modules can be provided for legacy applications, while allowing new (or newly built) applications to take advantage of the most recent modules. - Although Solaris PAM modules commonly have a version + Although &solaris; PAM modules commonly have a version number, they're not truly versioned, because the number is a part of the module name and must be included in the configuration.
Chains and policies When a server initiates a PAM transaction, the PAM library tries to load a policy for the service specified in the &man.pam.start.3; call. The policy specifies how authentication requests should be processed, and is defined in a configuration file. This is the other central concept in PAM: the possibility for the admin to tune the system security policy (in the wider sense of the word) simply by editing a text file. A policy consists of four chains, one for each of the four PAM facilities. Each chain is a sequence of configuration statements, each specifying a module to invoke, some (optional) parameters to pass to the module, and a control flag that describes how to interpret the return code from the module. Understanding the control flags is essential to understanding PAM configuration files. There are four different control flags: binding If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the rest of the chain is executed, but the request is ultimately denied. - This control flag was introduced by Sun in Solaris 9 - (SunOS 5.9), and is also supported by OpenPAM. + This control flag was introduced by Sun in &solaris; 9 + (&sunos; 5.9), and is also supported by OpenPAM. required If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the rest of the chain is also executed, but the request is ultimately denied. requisite If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the chain is immediately terminated and the request is denied. sufficient If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the module is ignored and the rest of the chain is executed. As the semantics of this flag may be somewhat confusing, especially when it is used for the last module in a chain, it is recommended that the binding control flag be used instead if the implementation supports it. optional The module is executed, but its result is ignored. If all modules in a chain are marked optional, all requests will always be granted. When a server invokes one of the six PAM primitives, PAM retrieves the chain for the facility the primitive belongs to, and invokes each of the modules listed in the chain, in the order they are listed, until it reaches the end, or determines that no further processing is necessary (either because a binding or sufficient module succeeded, or because a requisite module failed.) The request is granted if and only if at least one module was invoked, and all non-optional modules succeeded. Note that it is possible, though not very common, to have the same module listed several times in the same chain. For instance, a module that looks up user names and passwords in a directory server could be invoked multiple times with different parameters specifying different directory servers to contact. PAM treat different occurrences of the same module in the same chain as different, unrelated modules.
Transactions The lifecycle of a typical PAM transaction is described below. Note that if any of these steps fails, the server should report a suitable error message to the client and abort the transaction. If necessary, the server obtains arbitrator credentials through a mechanism independent of PAM—most commonly by virtue of having been started by root, or of being setuid root. The server calls &man.pam.start.3; to initialize the PAM library and specify its service name and the target account, and register a suitable conversation function. The server obtains various information relating to the transaction (such as the applicant's user name and the name of the host the client runs on) and submits it to PAM using &man.pam.set.item.3;. The server calls &man.pam.authenticate.3; to authenticate the applicant. The server calls &man.pam.acct.mgmt.3; to verify that the requested account is available and valid. If the password is correct but has expired, &man.pam.acct.mgmt.3; will return PAM_NEW_AUTHTOK_REQD instead of PAM_SUCCESS. If the previous step returned PAM_NEW_AUTHTOK_REQD, the server now calls &man.pam.chauthtok.3; to force the client to change the authentication token for the requested account. Now that the applicant has been properly authenticated, the server calls &man.pam.setcred.3; to establish the credentials of the requested account. It is able to do this because it acts on behalf of the arbitrator, and holds the arbitrator's credentials. Once the correct credentials have been established, the server calls &man.pam.open.session.3; to set up the session. The server now performs whatever service the client requested—for instance, provide the applicant with a shell. Once the server is done serving the client, it calls &man.pam.close.session.3; to tear down the session. Finally, the server calls &man.pam.end.3; to notify the PAM library that it is done and that it can release whatever resources it has allocated in the course of the transaction.
PAM Configuration
Location of configuration files The traditional PAM configuration file is /etc/pam.conf. This file contains all the PAM policies for your system. Each line of the file describes one step in a chain, as shown below: login auth required pam_nologin.so no_warn The fields are, in order: service name, facility name, control flag, module name, and module arguments. Any additional fields are interpreted as additional module arguments. A separate chain is constructed for each service / facility pair, so while the order in which lines for the same service and facility appear is significant, the order in which the individual services and facilities are listed is not—except that entries for the other service, which serves as a fall-back, should come last. The examples in the original PAM paper grouped configuration lines - by facility, and Solaris' stock pam.conf + by facility, and the &solaris; stock pam.conf still does that, but FreeBSD's stock configuration groups configuration lines by service. Either way is fine; either way makes equal sense. OpenPAM and Linux-PAM offer an alternate configuration mechanism, where policies are contained in separate files, named for the service they apply to, in /etc/pam.d/, with only four fields instead of five—the service name field is omitted. This is the preferred mechanism in FreeBSD 5.x. Note, however, that if /etc/pam.conf exists, and contains configuration statements for services which do not have a specific policy in /etc/pam.d/, it will be used as a fall-back for these services. The great advantage of /etc/pam.d/ over /etc/pam.conf is that it is possible to use the same policy for multiple services by linking each service name to a same policy file. For instance, to use the same policy for the su and sudo services, one could do as follows: &prompt.root; cd /etc/pam.d &prompt.root; ln -s su sudo This works because the service name is determined from the file name rather than specified in the policy file, so the same file can be used for multiple differently-named services. One other advantage is that third-party software can easily install policies for their services without the need to edit /etc/pam.conf. True to the FreeBSD tradition, OpenPAM will even look for policy files in /usr/local/etc/pam.d/ if no configuration for the requested service is present in /etc/pam.d/ or /etc/pam.conf. Finally, whichever configuration mechanism you choose, the magic policy other is used as a fall-back for any service that does not have its own policy.
Breakdown of a configuration line As explained in the section, each line in /etc/pam.conf consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments. The service name is generally (though not always) the name of the application the statement applies to. If you are unsure, refer to the individual application's documentation to determine what service name it uses. Note that if you use /etc/pam.d/ instead of /etc/pam.conf, the service name is specified by the name of the policy file, and omitted from the actual configuration lines, which then start with the facility name. The facility is one of the four facility keywords described in the section. Likewise, the control flag is one of the four keywords described in the section, describing how to interpret the return code from the module. Linux-PAM supports an alternate syntax that lets you specify the action to associate with each possible return code, but this should be avoided as it is non-standard and closely tied in with the way Linux-PAM dispatches service calls (which - differs greatly from the way Solaris and OpenPAM do it.) + differs greatly from the way &solaris; and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax.
Policies To configure PAM correctly, it is essential to understand how policies are interpreted. When an application calls &man.pam.start.3;, the PAM library loads the policy for the specified service and constructs four module chains (one for each facility.) If one or more of these chains are empty, the corresponding chains from the policy for the other service are substituted. When the application later calls one of the six PAM primitives, the PAM library retrieves the chain for the corresponding facility and calls the appropriate service function in each module listed in the chain, in the order in which they were listed in the configuration. After each call to a service function, the module type and the error code returned by the service function are used to determine what happens next. With a few exceptions, which we discuss below, the following table applies: PAM chain execution summary PAM_SUCCESS PAM_IGNORE other binding if (!fail) break; - fail = true; required - - fail = true; requisite - - fail = true; break; sufficient if (!fail) break; - - optional - - -
If fail is true at the end of a chain, or when a break is reached, the dispatcher returns the error code returned by the first module that failed. Otherwise, it returns PAM_SUCCESS. The first exception of note is that the error code PAM_NEW_AUTHTOK_REQD is treated like a success, except that if no module failed, and at least one module returned PAM_NEW_AUTHTOK_REQD, the dispatcher will return PAM_NEW_AUTHTOK_REQD. The second exception is that &man.pam.setcred.3; treats binding and sufficient modules as if they were required. The third and final exception is that &man.pam.chauthtok.3; runs the entire chain twice (once for preliminary checks and once to actually set the password), and in the preliminary phase it treats binding and sufficient modules as if they were required.
FreeBSD PAM Modules
&man.pam.deny.8; The &man.pam.deny.8; module is one of the simplest modules available; it responds to any request with PAM_AUTH_ERR. It is useful for quickly disabling a service (add it to the top of every chain), or for terminating chains of sufficient modules.
&man.pam.echo.8; The &man.pam.echo.8; module simply passes its arguments to the conversation function as a PAM_TEXT_INFO message. It is mostly useful for debugging, but can also serve to display messages such as Unauthorized access will be prosecuted before starting the authentication procedure.
&man.pam.exec.8; The &man.pam.exec.8; module takes its first argument to be the name of a program to execute, and the remaining arguments are passed to that program as command-line arguments. One possible application is to use it to run a program at login time which mounts the user's home directory.
&man.pam.ftp.8; The &man.pam.ftp.8; module
&man.pam.ftpusers.8; The &man.pam.ftpusers.8; module
&man.pam.group.8; The &man.pam.group.8; module accepts or rejects applicants on the basis of their membership in a particular file group (normally wheel for &man.su.1;). It is primarily intended for maintaining the traditional behaviour of BSD &man.su.1;, but has many other uses, such as excluding certain groups of users from a particular service.
&man.pam.krb5.8; The &man.pam.krb5.8; module
&man.pam.ksu.8; The &man.pam.ksu.8; module
&man.pam.lastlog.8; The &man.pam.lastlog.8; module
&man.pam.login.access.8; The &man.pam.login.access.8; module
&man.pam.nologin.8; The &man.pam.nologin.8; module
&man.pam.opie.8; The &man.pam.opie.8; module implements the &man.opie.4; authentication method. The &man.opie.4; system is a challenge-response mechanism where the response to each challenge is a direct function of the challenge and a passphrase, so the response can be easily computed just in time by anyone possessing the passphrase, eliminating the need for password lists. Moreover, since &man.opie.4; never reuses a challenge that has been correctly answered, it is not vulnerable to replay attacks.
&man.pam.opieaccess.8; The &man.pam.opieaccess.8; module is a companion module to &man.pam.opie.8;. Its purpose is to enforce the restrictions codified in &man.opieaccess.5;, which regulate the conditions under which a user who would normally authenticate herself using &man.opie.4; is allowed to use alternate methods. This is most often used to prohibit the use of password authentication from untrusted hosts. In order to be effective, the &man.pam.opieaccess.8; module must be listed as requisite immediately after a sufficient entry for &man.pam.opie.8;, and before any other modules, in the auth chain.
&man.pam.passwdqc.8; The &man.pam.passwdqc.8; module
&man.pam.permit.8; The &man.pam.permit.8; module is one of the simplest modules available; it responds to any request with PAM_SUCCESS. It is useful as a placeholder for services where one or more chains would otherwise be empty.
&man.pam.radius.8; The &man.pam.radius.8; module
&man.pam.rhosts.8; The &man.pam.rhosts.8; module
&man.pam.rootok.8; The &man.pam.rootok.8; module reports success if and only if the real user id of the process calling it (which is assumed to be run by the applicant) is 0. This is useful for non-networked services such as &man.su.1; or &man.passwd.1;, to which the root should have automatic access.
&man.pam.securetty.8; The &man.pam.securetty.8; module
&man.pam.self.8; The &man.pam.self.8; module reports success if and only if the names of the applicant matches that of the target account. It is most useful for non-networked services such as &man.su.1;, where the identity of the applicant can be easily verified.
&man.pam.ssh.8; The &man.pam.ssh.8; module
&man.pam.tacplus.8; The &man.pam.tacplus.8; module
&man.pam.unix.8; - The &man.pam.unix.8; module implements traditional Unix + The &man.pam.unix.8; module implements traditional &unix; password authentication, using &man.getpwnam.3; to obtain the target account's password and compare it with the one provided by the applicant. It also provides account management services (enforcing account and password expiration times) and password-changing services. This is probably the single most useful module, as the great majority of admins will want to maintain historical behaviour for at least some services.
PAM Application Programming This section has not yet been written.
PAM Module Programming This section has not yet been written.
Sample PAM Application The following is a minimal implementation of &man.su.1; using PAM. Note that it uses the OpenPAM-specific &man.openpam.ttyconv.3; conversation function, which is prototyped in security/openpam.h. If you wish build this application on a system with a different PAM library, you will have to provide your own conversation function. A robust conversation function is surprisingly difficult to implement; the one presented in the appendix is a good starting point, but should not be used in real-world applications. Sample PAM Module The following is a minimal implementation of &man.pam.unix.8;, offering only authentication services. It should build and run with most PAM implementations, but takes advantage of OpenPAM extensions if available: note the use of &man.pam.get.authtok.3;, which enormously simplifies prompting the user for a password. Sample PAM Conversation Function The conversation function presented below is a greatly simplified version of OpenPAM's &man.openpam.ttyconv.3;. It is fully functional, and should give the reader a good idea of how a conversation function should behave, but it is far too simple for real-world use. Even if you're not using OpenPAM, feel free to download the source code and adapt &man.openpam.ttyconv.3; to your uses; we believe it to be as robust as a tty-oriented conversation function can reasonably get. Further Reading This is a list of documents relevant to PAM and related issues. It is by no means complete. Papers <ulink url="http://www.sun.com/software/solaris/pam/pam.external.pdf"> Making Login Services Independent of Authentication Technologies</ulink> Samar Vipin Lai Charlie Sun Microsystems <ulink url="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open Single Sign-on Preliminary Specification</ulink> The Open Group 1-85912-144-6 June 1997 <ulink url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt"> Pluggable Authentication Modules</ulink> Morgan Andrew G. October 6, 1999 User Manuals <ulink url="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM Administration</ulink> Sun Microsystems Related Web pages <ulink url="http://openpam.sourceforge.net/">OpenPAM homepage</ulink> Smørgrav Dag-Erling ThinkSec AS <ulink url="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</ulink> Morgan Andrew G. <ulink url="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</ulink> Sun Microsystems
diff --git a/en_US.ISO8859-1/articles/pxe/article.sgml b/en_US.ISO8859-1/articles/pxe/article.sgml index 4f4505e438..0daddba58e 100644 --- a/en_US.ISO8859-1/articles/pxe/article.sgml +++ b/en_US.ISO8859-1/articles/pxe/article.sgml @@ -1,285 +1,294 @@ %man %authors; %misc; + + +%trademarks; ]>
FreeBSD Jumpstart Guide Alfred Perlstein
alfred@FreeBSD.org
 $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.intel; + &tm-attrib.general; + + This article details the method used to allow machines to install - FreeBSD using the Intel PXE method of booting a machine over a network. + FreeBSD using the &intel; PXE method of booting a machine over a network. Introduction This procedure will make the Server both insecure and dangerous, it is best to just keep the Server on its own hub and not in any way accessible by any machines other than the Clients. Terminology: Server The machine offering netboot and install options. Client The machine that will have FreeBSD installed on it. Requires: - Clients supporting the Intel PXE netboot option, an Ethernet connection. + Clients supporting the &intel; PXE netboot option, an Ethernet connection. Please let me know if you come across anything you have problems with or suggestions for additional documentation. If you would like someone to train/implement a specific netinstall system for you, please send email so that we can discuss terms. I would also like to thank &a.ps; and &a.jhb; for doing most of the - programming work on pxeboot, the interface to Intel's PXE (netboot) + programming work on pxeboot, the interface to the &intel; PXE (netboot) system. Server Configuration Install DHCP: Install net/isc-dhcp3 you can use this config file dhcpd.conf, stick it in /usr/local/etc/ Enable tftp: Make a directory /usr/tftpboot Add this line to your /etc/inetd.conf: tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /usr/tftpboot Enable NFS: Add this to /etc/rc.conf: nfs_server_enable="YES" Add this to /etc/exports: /usr -alldirs -ro Reboot to enable the new services or start them manually. Bootstrap Setup Download bootfiles: Download the kern.flp and mfsroot.flp floppy images. Setup tftp/pxe-boot directory: Put pxeboot in the boot directory: &prompt.root; rm -rf /usr/obj/* &prompt.root; cd /usr/src/sys/boot &prompt.root; make &prompt.root; cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot Using the vndevice mount the kern.flp file and copy its contents to /usr/tftpboot: &prompt.root; vnconfig vn0 kern.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp -R /mnt /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file Compile a custom kernel for the clients (particularly to avoid the device config screen at boot) and stick it in /usr/tftpboot. Make a special loader.rc to and install it in /usr/tftpboot/boot/loader.rc so that it does not prompt for the second disk, here is mine. Extract the installer and helper utilities from the mfsroot disk and uncompress them, put them in /usr/tftpboot as well: &prompt.root; vnconfig vn0 mfsroot.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp /mnt/mfsroot.gz /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file &prompt.root; cd /usr/tftpboot # get into the pxeboot directory &prompt.root; gunzip mfsroot.gz # uncompress the mfsroot Make your sysinstall script install.cfg, you can use mine as a template, but you must edit it. Copy the sysinstall script into the extracted and uncompressed mfsroot image: &prompt.root; cd /usr/tftpboot &prompt.root; vnconfig vn0 mfsroot &prompt.root; mount /dev/vn0 /mnt &prompt.root; cp install.cfg /mnt &prompt.root; umount /mnt &prompt.root; vnconfig -u vn0 Install Setup Put the install files in an NFS accessible location on the Server. Make a directory corresponding the 'nfs' directive in the install.cfg file and mirror the FreeBSD install files there, you will want it to look somewhat like this: ABOUT.TXT TROUBLE.TXT compat20 floppies ports ERRATA.TXT UPGRADE.TXT compat21 games proflibs HARDWARE.TXT XF86336 compat22 info src INSTALL.TXT bin compat3x kern.flp LAYOUT.TXT catpages crypto manpages README.TXT cdrom.inf dict mfsroot.flp RELNOTES.TXT compat1x doc packages Copy the compressed packages into the packages/All directory under nfs. Make sure you have an INDEX file prepared in the packages directory. You can make your own INDEX entries like so: alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org|||| Then you can install custom packages, particularly your own custom post-install package. Custom Post-Install Package You can use the script pkgmaker.sh to create a custom package for post install, the idea is to have it install and configure any special things you may need done. pkgmaker is run in the directory above the package you wish to create with the single argument of the package (ie mypkg) which will then create a mypkg.tgz for you to include in your sysinstall package. Inside your custom package dir you will want a file called PLIST which contains all the files that you wish to install and be incorporated into your package. You will also want files called pre and post in the directory, these are shell scripts that you want to execute before and after your package is installed. Since this package is in your install.cfg file it should be run and do the final configuration for you.
diff --git a/en_US.ISO8859-1/articles/releng-packages/article.sgml b/en_US.ISO8859-1/articles/releng-packages/article.sgml index 8ec0804d77..e57e8fe953 100644 --- a/en_US.ISO8859-1/articles/releng-packages/article.sgml +++ b/en_US.ISO8859-1/articles/releng-packages/article.sgml @@ -1,366 +1,375 @@ %man; %teams; %freebsd; %authors; + +%trademarks; ]>
FreeBSD Release Engineering for Third Party Software Packages Steve Price
steve@FreeBSD.org
 $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.intel; + &tm-attrib.xfree86; + &tm-attrib.general; + + This paper describes the approach used by the FreeBSD release engineering team to produce a high quality package set suitable for official FreeBSD release media. This document is a work in progress, but eventually it will cover the process used to build a clean package set on the FreeBSD.org Ports Cluster, how to configure any other set of machines as a ports cluster, how to split up the packages for the release media, and how to verify that a package set is consistent. Building packages from the Ports Collection The FreeBSD Ports collection is a collection of over &os.numports; third-party software packages available for FreeBSD. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany a given FreeBSD release. The Ports Cluster In order to provide a consistent set of third-party packages for FreeBSD releases, every port is built in a separate chroot environment, starting with an empty /usr/local and /usr/X11R6. The requisite dependencies are installed as packages before the build proceeds. This enforces consistency in the package build process. By starting the package build in a pristine environment, we can assure that the package metadata (such as required dependencies) is accurate. This way, we will never generate packages that might work on some systems and not on others depending on what software was previously installed. The Ports Cluster for the x86 architecture - currently consists of a master node (Dual Pentium III 733MHz) - and 8 slave nodes (Pentium III 800MHz) to do the actual + currently consists of a master node (Dual &pentium; III 733MHz) + and 8 slave nodes (&pentium; III 800MHz) to do the actual package builds. With this configuration, a complete package build takes over 24 hours. These machines are co-located with the other FreeBSD Project equipment at Yahoo's corner of Exodus in Santa Clara, CA. The Ports Cluster for the Alpha architecture consists of 7 PWS 500A machines donated by Compaq and also co-located with Yahoo's facilities. The Package Split For FreeBSD 4.4 over 4.1 gigabytes of packages were created. This causes a problem for CDROM distributions because we would like to ship as many packages as possible without making the user insert another disc to satisfy dependencies. The solution is to create clusters of like packages with similar dependencies and group these onto specific discs. This section describes the software and methodology used to create those package sets for the official FreeBSD release discs. The scripts and other files needed to produce a package split can be found in the CVS tree in ports/Tools/scripts/release. Copy this directory to a machine that has enough free disk space to hold 2 to 3 times the size of the package set that you wish to split. The following scripts are present in this directory: config This file contains the free space on each disc and whether packages, distfiles, or both are allowed on any given disc. The first column is the disc name. It must be of the form disc[0-9a-z]. Currently it is setup to allow for 10 discs (4 for the release set and 6 for the toolkit). There is an implied extra disc called scratch where all of the remaining distfiles/packages land if they do not fit elsewhere. The second column can be either a 1 or 0, where 1 says that it is okay to place packages on this disc. The third column works the same way, but it controls whether distfiles are placed on this disc. The last column denotes the number of bytes of free space on a disc. doit.sh This is the workhorse. Once you have all the files in place and things properly configured this script directs the process of splitting packages. Beware it is interactive so you need to keep an eye on it as it runs. More details on what happens in this script will follow. checkdeps.pl Makes sure all packages dependencies are satisfied given an INDEX file and a directory of packages. oneshot.pl This is where all the magic (and I use that term loosely as it is mostly just a brute force approach) happens. Given a list of required packages for each disc and a set of packages/distfiles this is the script that places a package or distfile on a disc along with all of its dependencies. print-cdrom-packages.sh This file is a copy of src/release/scripts/print-cdrom-packages.sh from the release you are working on. scrubindex.pl This script removes lines from an INDEX file for packages that are not present. - It also removes the XFree86 dependencies. NOTE: you will need to + It also removes the &xfree86; dependencies. NOTE: you will need to tweak the value of the xdep variable to make sure the version number is correct. setup.sh This is a helper script that I use on the bento cluster to grab a copy of the ports tree and the matching set of the packages/distfiles. Here is a checklist of things you will need to check or configure before going any further. Edit config to denote the number of discs you have, their sizes, and whether you want them want to contain packages, distfiles, both, or neither. Make sure you remove the gen directory if there is an old one laying around. This directory contains working files that will only be valid for the current split. On your first pass through a split it is best to fake the copying of packages and distfiles. This will save both time and diskspace while you do a couple of trial runs to make sure things fit, etc. In the oneshot.pl set the fake variable to 1 and instead of actually copying the files it will &man.touch.1; them. Be sure you turn this off or set fake to 0 before you give the resultant discs to the person that will be mastering the discs otherwise they will get a directory full of zero-sized files. Make sure you have a recent copy of the print-cdrom-packages.sh and that it is from the correct release. - Check to make sure the XFree86 dependency in + Check to make sure the &xfree86; dependency in scrubindex.pl has the correct version number. You will also need to make sure this value is correct in doit.sh as well. Next you will need to get a copy of the ports tree, packages, and distfiles from a recent build on the package cluster. See the setup.sh for a working example but essentially here is what needs to be done. Grab a copy of ports.tar.gz and extract it into the ports directory alongside doit.sh and the scripts directory. Remove the packages/distfiles directories or symlinks. Bento has these as symlinks and you will have mixed results if you do not get rid of them before proceeding. Create a new ports/packages directory and copy the package set from the package building cluster. Create a new ports/distfiles directory and copy the distfiles from the package building cluster. NOTE: if you do not want any distfiles simply create the directory and leave it empty. This directory must be present even if it does not contain anything. Now we are finally ready for the fun task of actually splitting the packages. You start the processing by running ./doit.sh. Here is what it does the first time you run it. Create a list of the restricted (can not be on the master FTP site) ports. Asks you if you would like to remove the restricted ports. Most of the time you will want to answer (y)es here. Create a list of the packages/distfiles that can not be put on the discs. Asks you if you would like to remove the non-cdromable packages/distfiles. Most of the time you will want to answer (y)es here. Copies the INDEX from the ports directory to the gen directory. In doing so it removes the lines for ports where the packages do not exist. It also checks to make sure that all of the required dependency packages are present. Create a list of packages that are required on each disc. Asks you if you would like to populate the discs. After populating each disc it will check for missing dependencies, scrub the INDEX file, and create the CHECKSUM.MD5 file. Check to make sure the required packages made it on each disc and gives you a summary of the sizes of each disc. After going through this the first time if you are lucky enough that all of the required packages built and fit on each disc. All you need to do is set fake to 0 in oneshot.pl and re-run ./doit.sh. The second and subsequent times around it will skip steps 1-5 above. If you want to re-run any of those steps refer to doit.sh for which files need to be removed to not short-circuit those steps. If you want to repeat all of these steps then the easiest way is to rm -rf gen. Upon successful completion the packages/distfiles will be in the disc* directories and the leftover will be in the scratch directory. What to do if things go wrong? Here is some common gotchas and workarounds. Missing required packages This is a pretty common occurrence. You will either need to wait for a new set of packages where the missing packages were built or get someone to re-start the package build for you. Do not attempt to build the missing packages on your own machine and add them into the fray. While you might be able to get away with this if you are extremely careful the vast majority of the time you will miss some little detail and the simple process of adding a package could make hundreds of others come up mysteriously broken. Required packages will not fit This happens on occasion too and is relatively easy to fix. Simply edit print-cdrom-packages.sh to move packages around until they fit. Yes this is an iterative process and one of the reasons why you should enable fake in oneshot.pl until you have gotten things the way you want them. Re-run ./doit.sh after you made your adjustments. Required packages not on the right (or any) disc This usually means you did not add them to print-cdrom-packages.sh or you put them on the wrong disc. This script is the gospel by which this whole process determines where a package must be. If you want to force a package to land on a particular disc this is the only way to ensure that it will happen. If you get completely stuck and can not figure out why things are borked or how to fix them then email &a.steve; for assistance.
diff --git a/en_US.ISO8859-1/articles/releng/article.sgml b/en_US.ISO8859-1/articles/releng/article.sgml index ed51f7b78c..c96abec313 100644 --- a/en_US.ISO8859-1/articles/releng/article.sgml +++ b/en_US.ISO8859-1/articles/releng/article.sgml @@ -1,1018 +1,1028 @@ %authors; %teams; %mailing-lists; %man; %freebsd; + +%trademarks; The Release Engineering of Third Party Packages'> ]>
FreeBSD Release Engineering November 2001 BSDCon Europe Murray Stokely I've been involved in the development of FreeBSD based products since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems. FreeBSD 4.4 was the first official release of FreeBSD that I played a significant part in.
murray@FreeBSD.org
$FreeBSD$ + + + &tm-attrib.freebsd; + &tm-attrib.intel; + &tm-attrib.xfree86; + &tm-attrib.general; + + This paper describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It details the methodology used for the official FreeBSD releases and describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization. Introduction The development of FreeBSD is a very open process. FreeBSD is comprised of contributions from thousands of people around the world. The FreeBSD Project provides anonymous CVS[1] access to the general public so that others can have access to log messages, diffs (patches) between development branches, and other productivity enhancements that formal source code management provides. This has been a huge help in attracting more talented developers to FreeBSD. However, I think everyone would agree that chaos would soon manifest if write access was opened up to everyone on the Internet. Therefore only a select group of nearly 300 people are given write access to the CVS repository. These committers[6] are responsible for the bulk of FreeBSD development. An elected core-team[7] of very senior developers provides some level of direction over the project. The rapid pace of FreeBSD development leaves little time for polishing the development system into a production quality release. To solve this dilemma, development continues on two parallel tracks. The main development branch is the HEAD or trunk of our CVS tree, known as FreeBSD-CURRENT or -CURRENT for short. A more stable branch is maintained, known as FreeBSD-STABLE or -STABLE for short. Both branches live in a master CVS repository in California and are replicated via CVSup[2] to mirrors all over the world. FreeBSD-CURRENT[8] is the bleeding-edge of FreeBSD development where all new changes first enter the system. FreeBSD-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and with general assumption that they have first gone into FreeBSD-CURRENT and have been thoroughly tested by our user community. In the interim period between releases, nightly snapshots are built automatically by the FreeBSD Project build machines and made available for download from ftp://stable.FreeBSD.org/. The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with CVSup and make world[8] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. Bug reports and feature requests are continuously submitted by users throughout the release cycle. Problems reports are entered into our GNATS[9] database through email, the &man.send-pr.1; application, or via the web interface provided at . In addition to the multitude of different technical mailing lists about FreeBSD, the &a.qa; provides a forum for discussing the finer points of release-polishing. To service our most conservative users, individual release branches were introduced with FreeBSD 4.3. These release branches are created shortly before a final release is made. After the release goes out, only the most critical security fixes and additions are merged onto the release branch. In addition to source updates via CVS, binary patchkits are available to keep systems on the RELENG_X_Y branches updated. discusses the different phases of the release engineering process leading up to the actual system build and describes the actual build process. describes how the base release may be extended by third parties and details some of the lessons learned through the release of FreeBSD 4.4. Finally, presents future directions of development. Release Process New releases of FreeBSD are released from the -STABLE branch at approximately four month intervals. The FreeBSD release process begins to ramp up 45 days before the anticipated release date when the release engineer sends an email to the development mailing lists to remind developers that they only have 15 days to integrate new changes before the code freeze. During this time, many developers perform what have become known as MFC sweeps. MFC stands for Merge From CURRENT and it describes the process of merging a tested change from our -CURRENT development branch to our -STABLE branch. Code Review Thirty days before the anticipated release, the source repository enters a code slush. During this time, all commits to the -STABLE branch must be approved by the &a.re;. The kinds of changes that are allowed during this 15 day period include: Bug fixes. Documentation updates. Security-related fixes of any kind. Minor changes to device drivers, such as adding new Device IDs. Any additional change that the release engineering team feels is justified, given the potential risk. After the first 15 days of the code slush, a release candidate is released for widespread testing and the code enters a code freeze where it becomes much harder to justify new changes to the system unless a serious bug-fix or security issue is involved. During the code freeze, at least one release candidate is released per week, until the final release is ready. During the days leading to the final release, the release engineering team is in constant communication with the security-officer team, the documentation maintainers, and the port maintainers, to ensure that all of the different components required for a successful release are available. Final Release Checklist When several release candidates have been made available for widespread testing and all major issues have been resolved, the final release polishing can begin. Creating the Release Branch As described in the introduction, the RELENG_X_Y release branch is a relatively new addition to our release engineering methodology. The first step in creating this branch is to ensure that you are working with the newest version of the RELENG_X sources that you want to branch from. /usr/src&prompt.root; cvs update -rRELENG_4 -P -d The next step is to create a branch point tag, so that diffs against the start of the branch are easier with CVS: /usr/src&prompt.root; cvs rtag -rRELENG_4 RELENG_4_8_BP src And then a new branch tag is created with: /usr/src&prompt.root; cvs rtag -b -rRELENG_4_8_BP RELENG_4_8 src The RELENG_* tags are restricted for use by the CVS-meisters and release engineers. A tag is CVS vernacular for a label that identifies the source at a specific point in time. By tagging the tree, we ensure that future release builders will always be able to use the same source we used to create the official FreeBSD Project releases. &branches.ascii; FreeBSD Development Branches Bumping up the Version Number Before the final release can be tagged, built, and released, the following files need to be modified to reflect the correct version of FreeBSD: doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml doc/en_US.ISO8859-1/books/porters-handbook/book.sgml doc/share/sgml/freebsd.ent src/Makefile.inc1 src/UPDATING src/gnu/usr.bin/groff/tmac/mdoc.local src/release/Makefile src/release/doc/en_US.ISO8859-1/share/sgml/release.dsl src/release/doc/share/examples/Makefile.relnotesng src/release/doc/share/sgml/release.ent src/share/examples/cvsup/standard-supfile src/sys/conf/newvers.sh src/sys/sys/param.h src/usr.sbin/pkg_install/add/main.c www/en/docs.sgml www/en/cgi/ports.cgi ports/Tools/scripts/release/config The release notes and errata files also need to be adjusted for the new release (on the release branch) and truncated appropriately (on the stable/current branch): src/release/doc/en_US.ISO8859-1/relnotes/common/new.sgml src/release/doc/en_US.ISO8859-1/errata/article.sgml Sysinstall should be updated to note the number of available ports and the amount of disk space required for the Ports Collection. This information is currently kept in src/release/sysinstall/dist.c. After the release has been built, a number of file should be updated to announce the release to the world. www/en/includes.xsl www/en/includes.sgml www/es/includes.sgml www/en/releases/* src/share/misc/bsd-family-tree Creating Release Tags When the final release is ready, the following command will create the RELENG_4_8_0_RELEASE tag. /usr/src&prompt.root; cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src The Documentation and Ports managers are responsible for tagging the respective trees with the RELEASE_4_8_0 tag. Occasionally, a last minute fix may be required after the final tags have been created. In practice this isn't a problem, since CVS allows tags to be manipulated with cvs tag -d tagname filename. It is very important that any last minute changes be tagged appropriately as part of the release. FreeBSD releases must always be reproduceable. Local hacks in the release engineer's environment are not acceptable. Release Building FreeBSD releases can be built by anyone with a fast machine and access to a source repository. (That should be everyone, since we offer anonymous CVS! See The Handbook for details.) The only special requirement is that the &man.vn.4; device must be available. (On -CURRENT, this device has been replaced by the new &man.md.4; memory disk driver.) If the device is not loaded into your kernel, then the kernel module should be automatically loaded when &man.vnconfig.8; is executed during the boot media creation phase. All of the tools necessary to build a release are available from the CVS repository in src/release. These tools aim to provide a consistent way to build FreeBSD releases. A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CDROM, installation floppies, and an FTP install directory. This command is aptly named make release. <command>make release</command> To successfully build a release, you must first populate /usr/obj by running make world or simply make buildworld. The release target requires several variables be set properly to build a release: CHROOTDIR - The directory to be used as the chroot environment for the entire release build. BUILDNAME - The name of the release to be built. CVSROOT - The location of a CVS Repository. RELEASETAG - The CVS tag corresponding to the release you would like to build. If you do not already have access to a local CVS repository, then you may mirror one with CVSup. The supplied supfile, /usr/share/examples/cvsup/cvs-supfile, is a useful starting point for mirroring the CVS repository. If RELEASETAG is omitted, then the release will be built from the HEAD (a.k.a. -CURRENT) branch. Releases built from this branch are normally referred to as -CURRENT snapshots. There are many other variables available to customize the release build. Most of these variables are documented at the top of src/release/Makefile. The exact command used to build the official FreeBSD 4.7 (x86) release was: make release CHROOTDIR=/local3/release \ BUILDNAME=4.7-RELEASE \ CVSROOT=/host/cvs/usr/home/ncvs \ RELEASETAG=RELENG_4_7_0_RELEASE The release Makefile can be broken down into several distinct steps. Creation of a sanitized system environment in a separate directory hierarchy with make installworld. Checkout from CVS of a clean version of the system source, documentation, and ports into the release build hierarchy. Population of /etc and /dev in the chrooted environment. chroot into the release build hierarchy, to make it harder for the outside environment to taint this build. make world in the chrooted environment. Build of Kerberos-related binaries. Build GENERIC kernel. Creation of a staging directory tree where the binary distributions will be built and packaged. Build and installation of the documentation toolchain needed to convert the documentation source (SGML) into HTML and text documents that will accompany the release. Build and installation of the actual documentation (user manuals, tutorials, release notes, hardware compatibility lists, and so on.) Build of the crunched binaries used for installation floppies. Package up distribution tarballs of the binaries and sources. Create the boot media and a fixit floppy. Create FTP installation hierarchy. (optionally) Create ISO images for CDROM/DVD media. For more information about the release build infrastructure, please see &man.release.7;. - Building <application>XFree86</application> + Building <application>&xfree86;</application> - XFree86 is an important component for many desktop users. - Prior to FreeBSD 4.6-RELEASE, releases used XFree86 + &xfree86; is an important component for many desktop users. + Prior to FreeBSD 4.6-RELEASE, releases used &xfree86; 3.X by default. The easiest way to build these versions is to use the src/release/scripts/X11/build_x.sh script. - This script requires that XFree86 and Tcl/Tk already be + This script requires that &xfree86; and Tcl/Tk already be installed on the build host. After compiling the necessary X servers, the script will package all of the files into tarballs that &man.sysinstall.8; expects to find in the XF86336 directory of the installation media. Beginning with FreeBSD 4.6-RELEASE, &man.sysinstall.8; - installs XFree86 4.X by default, as a + installs &xfree86; 4.X by default, as a set of normal packages. These can either be the packages generated by the package-building cluster or packages built from an appropriately tagged ports tree. It is important to remove any site-specific settings from /etc/make.conf. For example, it would be unwise to distribute binaries that were built on a system with CPUTYPE set to a specific processor. Contributed Software (<quote>ports</quote>) The FreeBSD Ports collection is a collection of over &os.numports; third-party software packages available for FreeBSD. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany official FreeBSD releases. The release engineering activities for our collection of third-party packages is beyond the scope of this document. A separate article, &art.re.pkgs;, covers this topic in depth. Release ISOs Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four ISO images that were previously sold on the BSDi/Wind River Systems/FreeBSD Mall official CDROM distributions. Each of the four discs must contain a README.TXT file that explains the contents of the disc, a CDROM.INF file that provides meta-data for the disc so that &man.sysinstall.8; can validate and use the contents, and a filename.txt file that provides a manifest for the disc. This manifest can be created with a simple command: /stage/cdrom&prompt.root; find . -type f | sed -e 's/^\.\///' | sort > filename.txt The specific requirements of each CD are outlined below. Disc 1 The first disc is almost completely created by make release. The only changes that should be made to the disc1 directory are the addition of a tools directory, XFree86, and as many popular + class="software">&xfree86;, and as many popular third party software packages as will fit on the disc. The tools directory contains software that allow users to create installation floppies from other operating systems. This disc should be made bootable so that users of modern PCs do not need to create installation floppy disks. - If an alternate version of XFree86 is to be provided, then + If an alternate version of &xfree86; is to be provided, then &man.sysinstall.8; must be updated to reflect the new location and installation instructions. The relevant code is contained in src/release/sysinstall on -STABLE or src/usr.sbin/sysinstall on -CURRENT. Specifically, the files dist.c, menus.c, and config.c will need to be updated. Disc 2 The second disc is also largely created by make release. This disc contains a live filesystem that can be used from &man.sysinstall.8; to troubleshoot a FreeBSD installation. This disc should be bootable and should also contain a compressed copy of the CVS repository in the CVSROOT directory and commercial software demos in the commerce directory. Discs 3 and 4 The remaining two discs contain additional software packages for FreeBSD. The packages should be clustered so that a package and all of its dependencies are included on the same disc. More information about the creation of these discs is provided in the &art.re.pkgs; article. Distribution FTP Sites When the release has been thoroughly tested and packaged for distribution, the master FTP site must be updated. The official FreeBSD public FTP sites are all mirrors of a master server that is open only to other FTP sites. This site is known as ftp-master. When the release is ready, the following files must be modified on ftp-master: /pub/FreeBSD/index.html A simple web page that points to the various important FTP directories for the current FreeBSD release. /pub/FreeBSD/releases/arch/X.Y-RELEASE/ The installable FTP directory as output from make release. /pub/FreeBSD/ports/arch/packages/packages-X.Y-release/ The complete package build for this release. /pub/FreeBSD/releases/arch/X.Y-RELEASE/tools A symlink to ../../../tools. /pub/FreeBSD/releases/arch/X.Y-RELEASE/packages A symlink to ../../../ports/i386/packages-X.Y-release. /pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-*.iso The ISO images. For more information about the distribution mirror architecture of the FreeBSD FTP sites, please see the Mirroring FreeBSD article. It may take many hours after updating ftp-master before a majority of the Tier-1 FTP sites have the new software. It is imperative that the release engineers coordinate with the &a.hubs; before announcing the general availability of new software on the FTP sites. CD-ROM Replication Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality assurance measures to be taken. Extensibility Although FreeBSD forms a complete operating system, there is nothing that forces you to use the system exactly as we have packaged it up for distribution. We have tried to design the system to be as extensible as possible so that it can serve as a platform that other commercial products can be built on top of. The only rule we have about this is that if you are going to distribute FreeBSD with non-trivial changes, we encourage you to document your enhancements! The FreeBSD community can only help support users of the software we provide. We certainly encourage innovation in the form of advanced installation and administration tools, for example, but we can't be expected to answer questions about it. Creating Customized Boot floppies Many sites have complex requirements that may require additional kernel modules or userland tools be added to the installation floppies. The quick and dirty way to accomplish this would be to modify the staging directory of an existing make release build hierarchy: Apply patches or add additional files inside the chroot release build directory. rm ${CHROOTDIR}/usr/obj/usr/src/release/release.[59] rebuild &man.sysinstall.8;, the kernel, or whatever parts of the system your change affected. chroot ${CHROOTDIR} ./mk floppies New release floppies will be located in ${CHROOTDIR}/R/stage/floppies. Alternatively, the boot.flp make target can be called, or the filesystem creating script, src/release/scripts/doFS.sh, may be invoked directly. Local patches may also be supplied to the release build by defining the LOCAL_PATCH variable in make release. Scripting <command>sysinstall</command> The FreeBSD system installation and configuration tool, &man.sysinstall.8;, can be scripted to provide automated installs for large sites. This functionality can be used in conjunction - with Intel's PXE[13] to bootstrap systems from the network, or + with &intel; PXE[13] to bootstrap systems from the network, or via custom boot floppies with a sysinstall script. An example sysinstall script is available in the CVS tree as src/release/sysinstall/install.cfg. Lessons Learned from FreeBSD 4.4 The release engineering process for 4.4 formally began on August 1st, 2001. After that date all commits to the RELENG_4 branch of FreeBSD had to be explicitly approved by the &a.re;. The first release candidate for the x86 architecture was released on August 16, followed by 4 more release candidates leading up to the final release on September 18th. The security officer was very involved in the last week of the process as several security issues were found in the earlier release candidates. A total of over 500 emails were sent to the &a.re; in little over a month. Our user community has made it very clear that the security and stability of a FreeBSD release should not be sacrificed for any self-imposed deadlines or target release dates. The FreeBSD Project has grown tremendously over its lifetime and the need for standardized release engineering procedures has never been more apparent. This will become even more important as FreeBSD is ported to new platforms. Future Directions It is imperative for our release engineering activities to scale with our growing userbase. Along these lines we are working very hard to document the procedures involved in producing FreeBSD releases. Parallelism - Certain portions of the release build are actually embarrassingly parallel. Most of the tasks are very I/O intensive, so having multiple high-speed disk drives is actually more important than using multiple processors in speeding up the make release process. If multiple disks are used for different hierarchies in the &man.chroot.2; environment, then the CVS checkout of the ports and doc trees can be happening simultaneously as the make world on another disk. Using a RAID solution (hardware or software) can significantly decrease the overall build time. Cross-building releases - Building IA-64 or Alpha release on x86 hardware? make TARGET=ia64 release. Regression Testing - We need better automated correctness testing for FreeBSD. Installation Tools - Our installation program has long since outlived its intended life span. Several projects are under development to provide a more advanced installation mechanism. One of the most promising is the libh project[5] which aims to provided an intelligent new package framework and GUI installation program. Acknowledgements I would like to thank Jordan Hubbard for giving me the opportunity to take on some of the release engineering responsibilities for FreeBSD 4.4 and also for all of his work throughout the years making FreeBSD what it is today. Of course the release wouldn't have been possible without all of the release-related work done by &a.asami;, &a.steve;, &a.bmah;, &a.nik;, &a.obrien;, &a.kris;, &a.jhb; and the rest of the FreeBSD development community. I would also like to thank &a.rgrimes;, &a.phk;, and others who worked on the release engineering tools in the very early days of FreeBSD. This article was influenced by release engineering documents from the CSRG[14], the NetBSD Project[11], and John Baldwin's proposed release engineering process notes[12]. References [1] CVS - Concurrent Versions System [2] CVSup - The CVS-Optimized General Purpose Network File Distribution System [3] [4] FreeBSD Ports Collection [5] The libh Project [6] FreeBSD Committers [7] FreeBSD Core-Team [8] FreeBSD Handbook [9] GNATS: The GNU Bug Tracking System [10] FreeBSD PR Statistics [11] NetBSD Developer Documentation: Release Engineering [12] John Baldwin's FreeBSD Release Engineering Proposal [13] PXE Jumpstart Guide [14] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: The Release Engineering of 4.3BSD
diff --git a/en_US.ISO8859-1/articles/serial-uart/article.sgml b/en_US.ISO8859-1/articles/serial-uart/article.sgml index 2d41e5d1e9..21df56f77f 100644 --- a/en_US.ISO8859-1/articles/serial-uart/article.sgml +++ b/en_US.ISO8859-1/articles/serial-uart/article.sgml @@ -1,2435 +1,2443 @@ %man; %authors; + +%trademarks; ]>
Serial and UART Tutorial Frank Durda
uhclem@FreeBSD.org
 $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.microsoft; + &tm-attrib.general; + + This article talks about using serial hardware with FreeBSD. The UART: What it is and how it works Copyright © 1996 &a.uhclem;, All Rights Reserved. 13 January 1996. The Universal Asynchronous Receiver/Transmitter (UART) controller is the key component of the serial communications subsystem of a computer. The UART takes bytes of data and transmits the individual bits in a sequential fashion. At the destination, a second UART re-assembles the bits into complete bytes. Serial transmission is commonly used with modems and for non-networked communication between computers, terminals and other devices. There are two primary forms of serial transmission: Synchronous and Asynchronous. Depending on the modes that are supported by the hardware, the name of the communication sub-system will usually include a A if it supports Asynchronous communications, and a S if it supports Synchronous communications. Both forms are described below. Some common acronyms are:
UART Universal Asynchronous Receiver/Transmitter
USART Universal Synchronous-Asynchronous Receiver/Transmitter
Synchronous Serial Transmission Synchronous serial transmission requires that the sender and receiver share a clock with one another, or that the sender provide a strobe or other timing signal so that the receiver knows when to read the next bit of the data. In most forms of serial Synchronous communication, if there is no data available at a given instant to transmit, a fill character must be sent instead so that data is always being transmitted. Synchronous communication is usually more efficient because only data bits are transmitted between sender and receiver, and synchronous communication can be more costly if extra wiring and circuits are required to share a clock signal between the sender and receiver. A form of Synchronous transmission is used with printers and fixed disk devices in that the data is sent on one set of wires while a clock or strobe is sent on a different wire. Printers and fixed disk devices are not normally serial devices because most fixed disk interface standards send an entire word of data for each clock or strobe signal by using a separate wire for each bit of the word. In the PC industry, these are known as Parallel devices. The standard serial communications hardware in the PC does not support Synchronous operations. This mode is described here for comparison purposes only. Asynchronous Serial Transmission Asynchronous transmission allows data to be transmitted without the sender having to send a clock signal to the receiver. Instead, the sender and receiver must agree on timing parameters in advance and special bits are added to each word which are used to synchronize the sending and receiving units. When a word is given to the UART for Asynchronous transmissions, a bit called the "Start Bit" is added to the beginning of each word that is to be transmitted. The Start Bit is used to alert the receiver that a word of data is about to be sent, and to force the clock in the receiver into synchronization with the clock in the transmitter. These two clocks must be accurate enough to not have the frequency drift by more than 10% during the transmission of the remaining bits in the word. (This requirement was set in the days of mechanical teleprinters and is easily met by modern electronic equipment.) After the Start Bit, the individual bits of the word of data are sent, with the Least Significant Bit (LSB) being sent first. Each bit in the transmission is transmitted for exactly the same amount of time as all of the other bits, and the receiver looks at the wire at approximately halfway through the period assigned to each bit to determine if the bit is a 1 or a 0. For example, if it takes two seconds to send each bit, the receiver will examine the signal to determine if it is a 1 or a 0 after one second has passed, then it will wait two seconds and then examine the value of the next bit, and so on. The sender does not know when the receiver has looked at the value of the bit. The sender only knows when the clock says to begin transmitting the next bit of the word. When the entire data word has been sent, the transmitter may add a Parity Bit that the transmitter generates. The Parity Bit may be used by the receiver to perform simple error checking. Then at least one Stop Bit is sent by the transmitter. When the receiver has received all of the bits in the data word, it may check for the Parity Bits (both sender and receiver must agree on whether a Parity Bit is to be used), and then the receiver looks for a Stop Bit. If the Stop Bit does not appear when it is supposed to, the UART considers the entire word to be garbled and will report a Framing Error to the host processor when the data word is read. The usual cause of a Framing Error is that the sender and receiver clocks were not running at the same speed, or that the signal was interrupted. Regardless of whether the data was received correctly or not, the UART automatically discards the Start, Parity and Stop bits. If the sender and receiver are configured identically, these bits are not passed to the host. If another word is ready for transmission, the Start Bit for the new word can be sent as soon as the Stop Bit for the previous word has been sent. Because asynchronous data is self synchronizing, if there is no data to transmit, the transmission line can be idle. Other UART Functions In addition to the basic job of converting data from parallel to serial for transmission and from serial to parallel on reception, a UART will usually provide additional circuits for signals that can be used to indicate the state of the transmission media, and to regulate the flow of data in the event that the remote device is not prepared to accept more data. For example, when the device connected to the UART is a modem, the modem may report the presence of a carrier on the phone line while the computer may be able to instruct the modem to reset itself or to not take calls by raising or lowering one more of these extra signals. The function of each of these additional signals is defined in the EIA RS232-C standard. The RS232-C and V.24 Standards In most computer systems, the UART is connected to circuitry that generates signals that comply with the EIA RS232-C specification. There is also a CCITT standard named V.24 that mirrors the specifications included in RS232-C. RS232-C Bit Assignments (Marks and Spaces) In RS232-C, a value of 1 is called a Mark and a value of 0 is called a Space. When a communication line is idle, the line is said to be Marking, or transmitting continuous 1 values. The Start bit always has a value of 0 (a Space). The Stop Bit always has a value of 1 (a Mark). This means that there will always be a Mark (1) to Space (0) transition on the line at the start of every word, even when multiple word are transmitted back to back. This guarantees that sender and receiver can resynchronize their clocks regardless of the content of the data bits that are being transmitted. The idle time between Stop and Start bits does not have to be an exact multiple (including zero) of the bit rate of the communication link, but most UARTs are designed this way for simplicity. In RS232-C, the "Marking" signal (a 1) is represented by a voltage between -2 VDC and -12 VDC, and a "Spacing" signal (a 0) is represented by a voltage between 0 and +12 VDC. The transmitter is supposed to send +12 VDC or -12 VDC, and the receiver is supposed to allow for some voltage loss in long cables. Some transmitters in low power devices (like portable computers) sometimes use only +5 VDC and -5 VDC, but these values are still acceptable to a RS232-C receiver, provided that the cable lengths are short. RS232-C Break Signal RS232-C also specifies a signal called a Break, which is caused by sending continuous Spacing values (no Start or Stop bits). When there is no electricity present on the data circuit, the line is considered to be sending Break. The Break signal must be of a duration longer than the time it takes to send a complete byte plus Start, Stop and Parity bits. Most UARTs can distinguish between a Framing Error and a Break, but if the UART cannot do this, the Framing Error detection can be used to identify Breaks. In the days of teleprinters, when numerous printers around the country were wired in series (such as news services), any unit could cause a Break by temporarily opening the entire circuit so that no current flowed. This was used to allow a location with urgent news to interrupt some other location that was currently sending information. In modern systems there are two types of Break signals. If the Break is longer than 1.6 seconds, it is considered a "Modem Break", and some modems can be programmed to terminate the conversation and go on-hook or enter the modems' command mode when the modem detects this signal. If the Break is smaller than 1.6 seconds, it signifies a Data Break and it is up to the remote computer to respond to this signal. Sometimes this form of Break is used as an Attention or Interrupt signal and sometimes is accepted as a substitute for the ASCII CONTROL-C character. Marks and Spaces are also equivalent to Holes and No Holes in paper tape systems. Breaks cannot be generated from paper tape or from any other byte value, since bytes are always sent with Start and Stop bit. The UART is usually capable of generating the continuous Spacing signal in response to a special command from the host processor. RS232-C DTE and DCE Devices The RS232-C specification defines two types of equipment: the Data Terminal Equipment (DTE) and the Data Carrier Equipment (DCE). Usually, the DTE device is the terminal (or computer), and the DCE is a modem. Across the phone line at the other end of a conversation, the receiving modem is also a DCE device and the computer that is connected to that modem is a DTE device. The DCE device receives signals on the pins that the DTE device transmits on, and vice versa. When two devices that are both DTE or both DCE must be connected together without a modem or a similar media translater between them, a NULL modem must be used. The NULL modem electrically re-arranges the cabling so that the transmitter output is connected to the receiver input on the other device, and vice versa. Similar translations are performed on all of the control signals so that each device will see what it thinks are DCE (or DTE) signals from the other device. The number of signals generated by the DTE and DCE devices are not symmetrical. The DTE device generates fewer signals for the DCE device than the DTE device receives from the DCE. RS232-C Pin Assignments The EIA RS232-C specification (and the ITU equivalent, V.24) calls for a twenty-five pin connector (usually a DB25) and defines the purpose of most of the pins in that connector. In the IBM Personal Computer and similar systems, a subset of RS232-C signals are provided via nine pin connectors (DB9). The signals that are not included on the PC connector deal mainly with synchronous operation, and this transmission mode is not supported by the UART that IBM selected for use in the IBM PC. Depending on the computer manufacturer, a DB25, a DB9, or both types of connector may be used for RS232-C communications. (The IBM PC also uses a DB25 connector for the parallel printer interface which causes some confusion.) Below is a table of the RS232-C signal assignments in the DB25 and DB9 connectors. DB25 RS232-C Pin DB9 IBM PC Pin EIA Circuit Symbol CCITT Circuit Symbol Common Name Signal Source Description 1 - AA 101 PG/FG - Frame/Protective Ground 2 3 BA 103 TD DTE Transmit Data 3 2 BB 104 RD DCE Receive Data 4 7 CA 105 RTS DTE Request to Send 5 8 CB 106 CTS DCE Clear to Send 6 6 CC 107 DSR DCE Data Set Ready 7 5 AV 102 SG/GND - Signal Ground 8 1 CF 109 DCD/CD DCE Data Carrier Detect 9 - - - - - Reserved for Test 10 - - - - - Reserved for Test 11 - - - - - Reserved for Test 12 - CI 122 SRLSD DCE Sec. Recv. Line Signal Detector 13 - SCB 121 SCTS DCE Secondary Clear to Send 14 - SBA 118 STD DTE Secondary Transmit Data 15 - DB 114 TSET DCE Trans. Sig. Element Timing 16 - SBB 119 SRD DCE Secondary Received Data 17 - DD 115 RSET DCE Receiver Signal Element Timing 18 - - 141 LOOP DTE Local Loopback 19 - SCA 120 SRS DTE Secondary Request to Send 20 4 CD 108.2 DTR DTE Data Terminal Ready 21 - - - RDL DTE Remote Digital Loopback 22 9 CE 125 RI DCE Ring Indicator 23 - CH 111 DSRS DTE Data Signal Rate Selector 24 - DA 113 TSET DTE Trans. Sig. Element Timing 25 - - 142 - DCE Test Mode Bits, Baud and Symbols Baud is a measurement of transmission speed in asynchronous communication. Because of advances in modem communication technology, this term is frequently misused when describing the data rates in newer devices. Traditionally, a Baud Rate represents the number of bits that are actually being sent over the media, not the amount of data that is actually moved from one DTE device to the other. The Baud count includes the overhead bits Start, Stop and Parity that are generated by the sending UART and removed by the receiving UART. This means that seven-bit words of data actually take 10 bits to be completely transmitted. Therefore, a modem capable of moving 300 bits per second from one place to another can normally only move 30 7-bit words if Parity is used and one Start and Stop bit are present. If 8-bit data words are used and Parity bits are also used, the data rate falls to 27.27 words per second, because it now takes 11 bits to send the eight-bit words, and the modem still only sends 300 bits per second. The formula for converting bytes per second into a baud rate and vice versa was simple until error-correcting modems came along. These modems receive the serial stream of bits from the UART in the host computer (even when internal modems are used the data is still frequently serialized) and converts the bits back into bytes. These bytes are then combined into packets and sent over the phone line using a Synchronous transmission method. This means that the Stop, Start, and Parity bits added by the UART in the DTE (the computer) were removed by the modem before transmission by the sending modem. When these bytes are received by the remote modem, the remote modem adds Start, Stop and Parity bits to the words, converts them to a serial format and then sends them to the receiving UART in the remote computer, who then strips the Start, Stop and Parity bits. The reason all these extra conversions are done is so that the two modems can perform error correction, which means that the receiving modem is able to ask the sending modem to resend a block of data that was not received with the correct checksum. This checking is handled by the modems, and the DTE devices are usually unaware that the process is occurring. By striping the Start, Stop and Parity bits, the additional bits of data that the two modems must share between themselves to perform error-correction are mostly concealed from the effective transmission rate seen by the sending and receiving DTE equipment. For example, if a modem sends ten 7-bit words to another modem without including the Start, Stop and Parity bits, the sending modem will be able to add 30 bits of its own information that the receiving modem can use to do error-correction without impacting the transmission speed of the real data. The use of the term Baud is further confused by modems that perform compression. A single 8-bit word passed over the telephone line might represent a dozen words that were transmitted to the sending modem. The receiving modem will expand the data back to its original content and pass that data to the receiving DTE. Modern modems also include buffers that allow the rate that bits move across the phone line (DCE to DCE) to be a different speed than the speed that the bits move between the DTE and DCE on both ends of the conversation. Normally the speed between the DTE and DCE is higher than the DCE to DCE speed because of the use of compression by the modems. Because the number of bits needed to describe a byte varied during the trip between the two machines plus the differing bits-per-seconds speeds that are used present on the DTE-DCE and DCE-DCE links, the usage of the term Baud to describe the overall communication speed causes problems and can misrepresent the true transmission speed. So Bits Per Second (bps) is the correct term to use to describe the transmission rate seen at the DCE to DCE interface and Baud or Bits Per Second are acceptable terms to use when a connection is made between two systems with a wired connection, or if a modem is in use that is not performing error-correction or compression. Modern high speed modems (2400, 9600, 14,400, and 19,200bps) in reality still operate at or below 2400 baud, or more accurately, 2400 Symbols per second. High speed modem are able to encode more bits of data into each Symbol using a technique called Constellation Stuffing, which is why the effective bits per second rate of the modem is higher, but the modem continues to operate within the limited audio bandwidth that the telephone system provides. Modems operating at 28,800 and higher speeds have variable Symbol rates, but the technique is the same. The IBM Personal Computer UART Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. Subsequent generations of compatible computers from IBM and other vendors continued to use the INS8250 or improved versions of the National Semiconductor UART family. National Semiconductor UART Family Tree There have been several versions and subsequent generations of the INS8250 UART. Each major version is described below. INS8250 -> INS8250B \ \ \-> INS8250A -> INS82C50A \ \ \-> NS16450 -> NS16C450 \ \ \-> NS16550 -> NS16550A -> PC16550D INS8250 This part was used in the original IBM PC and IBM PC/XT. The original name for this part was the INS8250 ACE (Asynchronous Communications Element) and it is made from NMOS technology. The 8250 uses eight I/O ports and has a one-byte send and a one-byte receive buffer. This original UART has several race conditions and other flaws. The original IBM BIOS includes code to work around these flaws, but this made the BIOS dependent on the flaws being present, so subsequent parts like the 8250A, 16450 or 16550 could not be used in the original IBM PC or IBM PC/XT. INS8250-B This is the slower speed of the INS8250 made from NMOS technology. It contains the same problems as the original INS8250. INS8250A An improved version of the INS8250 using XMOS technology with various functional flaws corrected. The INS8250A was used initially in PC clone computers by vendors who used clean BIOS designs. Because of the corrections in the chip, this part could not be used with a BIOS compatible with the INS8250 or INS8250B. INS82C50A This is a CMOS version (low power consumption) of the INS8250A and has similar functional characteristics. NS16450 Same as NS8250A with improvements so it can be used with faster CPU bus designs. IBM used this part in the IBM AT and updated the IBM BIOS to no longer rely on the bugs in the INS8250. NS16C450 This is a CMOS version (low power consumption) of the NS16450. NS16550 Same as NS16450 with a 16-byte send and receive buffer but the buffer design was flawed and could not be reliably be used. NS16550A Same as NS16550 with the buffer flaws corrected. The 16550A and its successors have become the most popular UART design in the PC industry, mainly due it its ability to reliably handle higher data rates on operating systems with sluggish interrupt response times. NS16C552 This component consists of two NS16C550A CMOS UARTs in a single package. PC16550D Same as NS16550A with subtle flaws corrected. This is revision D of the 16550 family and is the latest design available from National Semiconductor. The NS16550AF and the PC16550D are the same thing National reorganized their part numbering system a few years ago, and the NS16550AFN no longer exists by that name. (If you have a NS16550AFN, look at the date code on the part, which is a four digit number that usually starts with a nine. The first two digits of the number are the year, and the last two digits are the week in that year when the part was packaged. If you have a NS16550AFN, it is probably a few years old.) The new numbers are like PC16550DV, with minor differences in the suffix letters depending on the package material and its shape. (A description of the numbering system can be found below.) It is important to understand that in some stores, you may pay $15(US) for a NS16550AFN made in 1990 and in the next bin are the new PC16550DN parts with minor fixes that National has made since the AFN part was in production, the PC16550DN was probably made in the past six months and it costs half (as low as $5(US) in volume) as much as the NS16550AFN because they are readily available. As the supply of NS16550AFN chips continues to shrink, the price will probably continue to increase until more people discover and accept that the PC16550DN really has the same function as the old part number. National Semiconductor Part Numbering System The older NSnnnnnrqp part numbers are now of the format PCnnnnnrgp. The r is the revision field. The current revision of the 16550 from National Semiconductor is D. The p is the package-type field. The types are: "F" QFP (quad flat pack) L lead type "N" DIP (dual inline package) through hole straight lead type "V" LPCC (lead plastic chip carrier) J lead type The g is the product grade field. If an I precedes the package-type letter, it indicates an industrial grade part, which has higher specs than a standard part but not as high as Military Specification (Milspec) component. This is an optional field. So what we used to call a NS16550AFN (DIP Package) is now called a PC16550DN or PC16550DIN. Other Vendors and Similar UARTs Over the years, the 8250, 8250A, 16450 and 16550 have been licensed or copied by other chip vendors. In the case of the 8250, 8250A and 16450, the exact circuit (the megacell) was licensed to many vendors, including Western Digital and Intel. Other vendors reverse-engineered the part or produced emulations that had similar behavior. In internal modems, the modem designer will frequently emulate the 8250A/16450 with the modem microprocessor, and the emulated UART will frequently have a hidden buffer consisting of several hundred bytes. Because of the size of the buffer, these emulations can be as reliable as a 16550A in their ability to handle high speed data. However, most operating systems will still report that the UART is only a 8250A or 16450, and may not make effective use of the extra buffering present in the emulated UART unless special drivers are used. Some modem makers are driven by market forces to abandon a design that has hundreds of bytes of buffer and instead use a 16550A UART so that the product will compare favorably in market comparisons even though the effective performance may be lowered by this action. A common misconception is that all parts with 16550A written on them are identical in performance. There are differences, and in some cases, outright flaws in most of these 16550A clones. When the NS16550 was developed, the National Semiconductor obtained several patents on the design and they also limited licensing, making it harder for other vendors to provide a chip with similar features. Because of the patents, reverse-engineered designs and emulations had to avoid infringing the claims covered by the patents. Subsequently, these copies almost never perform exactly the same as the NS16550A or PC16550D, which are the parts most computer and modem makers want to buy but are sometimes unwilling to pay the price required to get the genuine part. Some of the differences in the clone 16550A parts are unimportant, while others can prevent the device from being used at all with a given operating system or driver. These differences may show up when using other drivers, or when particular combinations of events occur that were not well - tested or considered in the Windows driver. This is because + tested or considered in the &windows; driver. This is because most modem vendors and 16550-clone makers use the Microsoft - drivers from Windows for Workgroups 3.11 and the Microsoft - MS-DOS utility as the primary tests for compatibility with + drivers from &windows; for Workgroups 3.11 and the µsoft; + &ms-dos; utility as the primary tests for compatibility with the NS16550A. This over-simplistic criteria means that if a different operating system is used, problems could appear due to subtle differences between the clones and genuine components. National Semiconductor has made available a program named COMTEST that performs compatibility tests independent of any OS drivers. It should be remembered that the purpose of this type of program is to demonstrate the flaws in the products of the competition, so the program will report major as well as extremely subtle differences in behavior in the part being tested. In a series of tests performed by the author of this document in 1994, components made by National Semiconductor, TI, StarTech, and CMD as well as megacells and emulations embedded in internal modems were tested with COMTEST. A difference count for some of these components is listed below. Because these tests were performed in 1994, they may not reflect the current performance of the given product from a vendor. It should be noted that COMTEST normally aborts when an excessive number or certain types of problems have been detected. As part of this testing, COMTEST was modified so that it would not abort no matter how many differences were encountered. Vendor Part Number Errors (aka "differences" reported) National (PC16550DV) 0 National (NS16550AFN) 0 National (NS16C552V) 0 TI (TL16550AFN) 3 CMD (16C550PE) 19 StarTech (ST16C550J) 23 Rockwell Reference modem with internal 16550 or an emulation (RC144DPi/C3000-25) 117 Sierra Modem with an internal 16550 (SC11951/SC11351) 91 To date, the author of this document has not found any non-National parts that report zero differences using the COMTEST program. It should also be noted that National has had five versions of the 16550 over the years and the newest parts behave a bit differently than the classic NS16550AFN that is considered the benchmark for functionality. COMTEST appears to turn a blind eye to the differences within the National product line and reports no errors on the National parts (except for the original 16550) even when there are official erratas that describe bugs in the A, B and C revisions of the parts, so this bias in COMTEST must be taken into account. It is important to understand that a simple count of differences from COMTEST does not reveal a lot about what differences are important and which are not. For example, about half of the differences reported in the two modems listed above that have internal UARTs were caused by the clone UARTs not supporting five- and six-bit character modes. The real 16550, 16450, and 8250 UARTs all support these modes and COMTEST checks the functionality of these modes so over fifty differences are reported. However, almost no modern modem supports five- or six-bit characters, particularly those with error-correction and compression capabilities. This means that the differences related to five- and six-bit character modes can be discounted. Many of the differences COMTEST reports have to do with timing. In many of the clone designs, when the host reads from one port, the status bits in some other port may not update in the same amount of time (some faster, some slower) as a real NS16550AFN and COMTEST looks for these differences. This means that the number of differences can be misleading in that one device may only have one or two differences but they are extremely serious, and some other device that updates the status registers faster or slower than the reference part (that would probably never affect the operation of a properly written driver) could have dozens of differences reported. COMTEST can be used as a screening tool to alert the administrator to the presence of potentially incompatible components that might cause problems or have to be handled as a special case. If you run COMTEST on a 16550 that is in a modem or a modem is attached to the serial port, you need to first issue a ATE0&W command to the modem so that the modem will not echo any of the test characters. If you forget to do this, COMTEST will report at least this one difference: Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61 8250/16450/16550 Registers The 8250/16450/16550 UART occupies eight contiguous I/O port addresses. In the IBM PC, there are two defined locations for these eight ports and they are known collectively as COM1 and COM2. The makers of PC-clones and add-on cards have created two additional areas known as COM3 and COM4, but these extra COM ports conflict with other hardware on some systems. The most common conflict is with video adapters that provide IBM 8514 emulation. COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4 COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3 COM3 is located from 0x3e8 to 0x3ef and has no standardized IRQ COM4 is located from 0x2e8 to 0x2ef and has no standardized IRQ. A description of the I/O ports of the 8250/16450/16550 UART is provided below. I/O Port Access Allowed Description +0x00 write (DLAB==0) Transmit Holding Register (THR).Information written to this port are treated as data words and will be transmitted by the UART. +0x00 read (DLAB==0) Receive Buffer Register (RBR).Any data words received by the UART form the serial link are accessed by the host by reading this port. +0x00 write/read (DLAB==1) Divisor Latch LSB (DLL)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 0 thru 7 of the divisor. +0x01 write/read (DLAB==1) Divisor Latch MSB (DLH)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 8 thru 15 of the divisor. +0x01 write/read (DLAB==0) Interrupt Enable Register (IER)The 8250/16450/16550 UART classifies events into one of four categories. Each category can be configured to generate an interrupt when any of the events occurs. The 8250/16450/16550 UART generates a single external interrupt signal regardless of how many events in the enabled categories have occurred. It is up to the host processor to respond to the interrupt and then poll the enabled interrupt categories (usually all categories have interrupts enabled) to determine the true cause(s) of the interrupt. Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Enable Modem Status Interrupt (EDSSI). Setting this bit to "1" allows the UART to generate an interrupt when a change occurs on one or more of the status lines. Bit 2 Enable Receiver Line Status Interrupt (ELSI) Setting this bit to "1" causes the UART to generate an interrupt when the an error (or a BREAK signal) has been detected in the incoming data. Bit 1 Enable Transmitter Holding Register Empty Interrupt (ETBEI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has room for one or more additional characters that are to be transmitted. Bit 0 Enable Received Data Available Interrupt (ERBFI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has received enough characters to exceed the trigger level of the FIFO, or the FIFO timer has expired (stale data), or a single character has been received when the FIFO is disabled. +0x02 write FIFO Control Register (FCR) (This port does not exist on the 8250 and 16450 UART.) Bit 7 Receiver Trigger Bit #1 Bit 6 Receiver Trigger Bit #0These two bits control at what point the receiver is to generate an interrupt when the FIFO is active. 7 6 How many words are received before an interrupt is generated 0 0 1 0 1 4 1 0 8 1 1 14 Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 DMA Mode Select. If Bit 0 is set to "1" (FIFOs enabled), setting this bit changes the operation of the -RXRDY and -TXRDY signals from Mode 0 to Mode 1. Bit 2 Transmit FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being transmitted will be sent intact. This function is useful in aborting transfers. Bit 1 Receiver FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being assembled in the shift register will be received intact. Bit 0 16550 FIFO Enable. When set, both the transmit and receive FIFOs are enabled. Any contents in the holding register, shift registers or FIFOs are lost when FIFOs are enabled or disabled. +0x02 read Interrupt Identification Register Bit 7 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 6 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Interrupt ID Bit #2. On the 8250/16450 UART, this bit is zero. Bit 2 Interrupt ID Bit #1 Bit 1 Interrupt ID Bit #0.These three bits combine to report the category of event that caused the interrupt that is in progress. These categories have priorities, so if multiple categories of events occur at the same time, the UART will report the more important events first and the host must resolve the events in the order they are reported. All events that caused the current interrupt must be resolved before any new interrupts will be generated. (This is a limitation of the PC architecture.) 2 1 0 Priority Description 0 1 1 First Received Error (OE, PE, BI, or FE) 0 1 0 Second Received Data Available 1 1 0 Second Trigger level identification (Stale data in receive buffer) 0 0 1 Third Transmitter has room for more words (THRE) 0 0 0 Fourth Modem Status Change (-CTS, -DSR, -RI, or -DCD) Bit 0 Interrupt Pending Bit. If this bit is set to "0", then at least one interrupt is pending. +0x03 write/read Line Control Register (LCR) Bit 7 Divisor Latch Access Bit (DLAB). When set, access to the data transmit/receive register (THR/RBR) and the Interrupt Enable Register (IER) is disabled. Any access to these ports is now redirected to the Divisor Latch Registers. Setting this bit, loading the Divisor Registers, and clearing DLAB should be done with interrupts disabled. Bit 6 Set Break. When set to "1", the transmitter begins to transmit continuous Spacing until this bit is set to "0". This overrides any bits of characters that are being transmitted. Bit 5 Stick Parity. When parity is enabled, setting this bit causes parity to always be "1" or "0", based on the value of Bit 4. Bit 4 Even Parity Select (EPS). When parity is enabled and Bit 5 is "0", setting this bit causes even parity to be transmitted and expected. Otherwise, odd parity is used. Bit 3 Parity Enable (PEN). When set to "1", a parity bit is inserted between the last bit of the data and the Stop Bit. The UART will also expect parity to be present in the received data. Bit 2 Number of Stop Bits (STB). If set to "1" and using 5-bit data words, 1.5 Stop Bits are transmitted and expected in each data word. For 6, 7 and 8-bit data words, 2 Stop Bits are transmitted and expected. When this bit is set to "0", one Stop Bit is used on each data word. Bit 1 Word Length Select Bit #1 (WLSB1) Bit 0 Word Length Select Bit #0 (WLSB0) Together these bits specify the number of bits in each data word. 1 0 Word Length 0 0 5 Data Bits 0 1 6 Data Bits 1 0 7 Data Bits 1 1 8 Data Bits +0x04 write/read Modem Control Register (MCR) Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Loop-Back Enable. When set to "1", the UART transmitter and receiver are internally connected together to allow diagnostic operations. In addition, the UART modem control outputs are connected to the UART modem control inputs. CTS is connected to RTS, DTR is connected to DSR, OUT1 is connected to RI, and OUT 2 is connected to DCD. Bit 3 OUT 2. An auxiliary output that the host processor may set high or low. In the IBM PC serial adapter (and most clones), OUT 2 is used to tri-state (disable) the interrupt signal from the 8250/16450/16550 UART. Bit 2 OUT 1. An auxiliary output that the host processor may set high or low. This output is not used on the IBM PC serial adapter. Bit 1 Request to Send (RTS). When set to "1", the output of the UART -RTS line is Low (Active). Bit 0 Data Terminal Ready (DTR). When set to "1", the output of the UART -DTR line is Low (Active). +0x05 write/read Line Status Register (LSR) Bit 7 Error in Receiver FIFO. On the 8250/16450 UART, this bit is zero. This bit is set to "1" when any of the bytes in the FIFO have one or more of the following error conditions: PE, FE, or BI. Bit 6 Transmitter Empty (TEMT). When set to "1", there are no words remaining in the transmit FIFO or the transmit shift register. The transmitter is completely idle. Bit 5 Transmitter Holding Register Empty (THRE). When set to "1", the FIFO (or holding register) now has room for at least one additional word to transmit. The transmitter may still be transmitting when this bit is set to "1". Bit 4 Break Interrupt (BI). The receiver has detected a Break signal. Bit 3 Framing Error (FE). A Start Bit was detected but the Stop Bit did not appear at the expected time. The received word is probably garbled. Bit 2 Parity Error (PE). The parity bit was incorrect for the word received. Bit 1 Overrun Error (OE). A new word was received and there was no room in the receive buffer. The newly-arrived word in the shift register is discarded. On 8250/16450 UARTs, the word in the holding register is discarded and the newly- arrived word is put in the holding register. Bit 0 Data Ready (DR) One or more words are in the receive FIFO that the host may read. A word must be completely received and moved from the shift register into the FIFO (or holding register for 8250/16450 designs) before this bit is set. +0x06 write/read Modem Status Register (MSR) Bit 7 Data Carrier Detect (DCD). Reflects the state of the DCD line on the UART. Bit 6 Ring Indicator (RI). Reflects the state of the RI line on the UART. Bit 5 Data Set Ready (DSR). Reflects the state of the DSR line on the UART. Bit 4 Clear To Send (CTS). Reflects the state of the CTS line on the UART. Bit 3 Delta Data Carrier Detect (DDCD). Set to "1" if the -DCD line has changed state one more time since the last time the MSR was read by the host. Bit 2 Trailing Edge Ring Indicator (TERI). Set to "1" if the -RI line has had a low to high transition since the last time the MSR was read by the host. Bit 1 Delta Data Set Ready (DDSR). Set to "1" if the -DSR line has changed state one more time since the last time the MSR was read by the host. Bit 0 Delta Clear To Send (DCTS). Set to "1" if the -CTS line has changed state one more time since the last time the MSR was read by the host. +0x07 write/read Scratch Register (SCR). This register performs no function in the UART. Any value can be written by the host to this location and read by the host later on. Beyond the 16550A UART Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. Some of these components are described below. It should be understood that to effectively utilize these improvements, drivers may have to be provided by the chip vendor since most of the popular operating systems do not support features beyond those provided by the 16550. ST16650 By default this part is similar to the NS16550A, but an extended 32-byte send and receive buffer can be optionally enabled. Made by StarTech. TIL16660 By default this part behaves similar to the NS16550A, but an extended 64-byte send and receive buffer can be optionally enabled. Made by Texas Instruments. Hayes ESP This proprietary plug-in card contains a 2048-byte send and receive buffer, and supports data rates to 230.4Kbit/sec. Made by Hayes. In addition to these dumb UARTs, many vendors produce intelligent serial communication boards. This type of design usually provides a microprocessor that interfaces with several UARTs, processes and buffers the data, and then alerts the main PC processor when necessary. Because the UARTs are not directly accessed by the PC processor in this type of communication system, it is not necessary for the vendor to use UARTs that are compatible with the 8250, 16450, or the 16550 UART. This leaves the designer free to components that may have better performance characteristics. Configuring the <devicename>sio</devicename> driver The sio driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the &man.sio.4; manual page for detailed technical documentation. Digi International (DigiBoard) PC/8 Contributed by &a.awebster;. 26 August 1995. Here is a config snippet from a machine with a Digi International PC/8 with 16550. It has 8 modems connected to these 8 lines, and they work just great. Do not forget to add options COM_MULTIPORT or it will not work very well! device sio4 at isa? port 0x100 flags 0xb05 device sio5 at isa? port 0x108 flags 0xb05 device sio6 at isa? port 0x110 flags 0xb05 device sio7 at isa? port 0x118 flags 0xb05 device sio8 at isa? port 0x120 flags 0xb05 device sio9 at isa? port 0x128 flags 0xb05 device sio10 at isa? port 0x130 flags 0xb05 device sio11 at isa? port 0x138 flags 0xb05 irq 9 The trick in setting this up is that the MSB of the flags represent the last SIO port, in this case 11 so flags are 0xb05. Boca 16 Contributed by &a.whiteside;. 26 August 1995. The procedures to make a Boca 16 port board with FreeBSD are pretty straightforward, but you will need a couple things to make it work: You either need the kernel sources installed so you can recompile the necessary options or you will need someone else to compile it for you. The 2.0.5 default kernel does not come with multiport support enabled and you will need to add a device entry for each port anyways. Two, you will need to know the interrupt and IO setting for your Boca Board so you can set these options properly in the kernel. One important note — the actual UART chips for the Boca 16 are in the connector box, not on the internal board itself. So if you have it unplugged, probes of those ports will fail. I have never tested booting with the box unplugged and plugging it back in, and I suggest you do not either. If you do not already have a custom kernel configuration file set up, refer to Kernel Configuration chapter of the FreeBSD Handbook for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi. Add the line options COM_MULTIPORT to the config file. Where the current device sion lines are, you will need to add 16 more devices. The following example is for a Boca Board with an interrupt of 3, and a base IO address 100h. The IO address for Each port is +8 hexadecimal from the previous port, thus the 100h, 108h, 110h... addresses. device sio1 at isa? port 0x100 flags 0x1005 device sio2 at isa? port 0x108 flags 0x1005 device sio3 at isa? port 0x110 flags 0x1005 device sio4 at isa? port 0x118 flags 0x1005 … device sio15 at isa? port 0x170 flags 0x1005 device sio16 at isa? port 0x178 flags 0x1005 irq 3 The flags entry must be changed from this example unless you are using the exact same sio assignments. Flags are set according to 0xMYY where M indicates the minor number of the master port (the last port on a Boca 16) and YY indicates if FIFO is enabled or disabled(enabled), IRQ sharing is used(yes) and if there is an AST/4 compatible IRQ control register(no). In this example, flags 0x1005 indicates that the master port is sio16. If I added another board and assigned sio17 through sio28, the flags for all 16 ports on that board would be 0x1C05, where 1C indicates the minor number of the master port. Do not change the 05 setting. Save and complete the kernel configuration, recompile, install and reboot. Presuming you have successfully installed the recompiled kernel and have it set to the correct address and IRQ, your boot message should indicate the successful probe of the Boca ports as follows: (obviously the sio numbers, IO and IRQ could be different) sio1 at 0x100-0x107 flags 0x1005 on isa sio1: type 16550A (multiport) sio2 at 0x108-0x10f flags 0x1005 on isa sio2: type 16550A (multiport) sio3 at 0x110-0x117 flags 0x1005 on isa sio3: type 16550A (multiport) sio4 at 0x118-0x11f flags 0x1005 on isa sio4: type 16550A (multiport) sio5 at 0x120-0x127 flags 0x1005 on isa sio5: type 16550A (multiport) sio6 at 0x128-0x12f flags 0x1005 on isa sio6: type 16550A (multiport) sio7 at 0x130-0x137 flags 0x1005 on isa sio7: type 16550A (multiport) sio8 at 0x138-0x13f flags 0x1005 on isa sio8: type 16550A (multiport) sio9 at 0x140-0x147 flags 0x1005 on isa sio9: type 16550A (multiport) sio10 at 0x148-0x14f flags 0x1005 on isa sio10: type 16550A (multiport) sio11 at 0x150-0x157 flags 0x1005 on isa sio11: type 16550A (multiport) sio12 at 0x158-0x15f flags 0x1005 on isa sio12: type 16550A (multiport) sio13 at 0x160-0x167 flags 0x1005 on isa sio13: type 16550A (multiport) sio14 at 0x168-0x16f flags 0x1005 on isa sio14: type 16550A (multiport) sio15 at 0x170-0x177 flags 0x1005 on isa sio15: type 16550A (multiport) sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) If the messages go by too fast to see, &prompt.root; dmesg | more will show you the boot messages. Next, appropriate entries in /dev for the devices must be made using the /dev/MAKEDEV script. This step can be omitted if you are running FreeBSD 5.X with a kernel that has &man.devfs.5; support compiled in. If you do need to create the /dev entries, run the following as root: &prompt.root; cd /dev &prompt.root; ./MAKEDEV tty1 &prompt.root; ./MAKEDEV cua1 (everything in between) &prompt.root; ./MAKEDEV ttyg &prompt.root; ./MAKEDEV cuag If you do not want or need call-out devices for some reason, you can dispense with making the cua* devices. If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) &prompt.root; echo at > ttyd* for each device you have made. You should see the RX lights flash for each working port. Support for Cheap Multi-UART Cards Contributed by Helge Oldach hmo@sep.hamburg.com, September 1999 Ever wondered about FreeBSD support for your 20$ multi-I/O card with two (or more) COM ports, sharing IRQs? Here is how: Usually the only option to support these kind of boards is to use a distinct IRQ for each port. For example, if your CPU board has an on-board COM1 port (aka sio0–I/O address 0x3F8 and IRQ 4) and you have an extension board with two UARTs, you will commonly need to configure them as COM2 (aka sio1–I/O address 0x2F8 and IRQ 3), and the third port (aka sio2) as I/O 0x3E8 and IRQ 5. Obviously this is a waste of IRQ resources, as it should be basically possible to run both extension board ports using a single IRQ with the COM_MULTIPORT configuration described in the previous sections. Such cheap I/O boards commonly have a 4 by 3 jumper matrix for the COM ports, similar to the following: o o o * Port A | o * o * Port B | o * o o IRQ 2 3 4 5 Shown here is port A wired for IRQ 5 and port B wired for IRQ 3. The IRQ columns on your specific board may vary—other boards may supply jumpers for IRQs 3, 4, 5, and 7 instead. One could conclude that wiring both ports for IRQ 3 using a handcrafted wire-made jumper covering all three connection points in the IRQ 3 column would solve the issue, but no. You cannot duplicate IRQ 3 because the output drivers of each UART are wired in a totem pole fashion, so if one of the UARTs drives IRQ 3, the output signal will not be what you would expect. Depending on the implementation of the extension board or your motherboard, the IRQ 3 line will continuously stay up, or always stay low. You need to decouple the IRQ drivers for the two UARTs, so that the IRQ line of the board only goes up if (and only if) one of the UARTs asserts a IRQ, and stays low otherwise. The solution was proposed by Joerg Wunsch j@ida.interface-business.de: To solder up a wired-or consisting of two diodes (Germanium or Schottky-types strongly preferred) and a 1 kOhm resistor. Here is the schematic, starting from the 4 by 3 jumper field above: Diode +---------->|-------+ / | o * o o | 1 kOhm Port A +----|######|-------+ o * o o | | Port B `-------------------+ ==+== o * o o | Ground \ | +--------->|-------+ IRQ 2 3 4 5 Diode The cathodes of the diodes are connected to a common point, together with a 1 kOhm pull-down resistor. It is essential to connect the resistor to ground to avoid floating of the IRQ line on the bus. Now we are ready to configure a kernel. Staying with this example, we would configure: # standard on-board COM1 port device sio0 at isa? port "IO_COM1" flags 0x10 # patched-up multi-I/O extension board options COM_MULTIPORT device sio1 at isa? port "IO_COM2" flags 0x205 device sio2 at isa? port "IO_COM3" flags 0x205 irq 3 Note that the flags setting for sio1 and sio2 is truly essential; refer to &man.sio.4; for details. (Generally, the 2 in the "flags" attribute refers to sio2 which holds the IRQ, and you surely want a 5 low nibble.) With kernel verbose mode turned on this should yield something similar to this: sio0: irq maps: 0x1 0x11 0x1 0x1 sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa sio0: type 16550A sio1: irq maps: 0x1 0x9 0x1 0x1 sio1 at 0x2f8-0x2ff flags 0x205 on isa sio1: type 16550A (multiport) sio2: irq maps: 0x1 0x9 0x1 0x1 sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa sio2: type 16550A (multiport master) Though /sys/i386/isa/sio.c is somewhat cryptic with its use of the irq maps array above, the basic idea is that you observe 0x1 in the first, third, and fourth place. This means that the corresponding IRQ was set upon output and cleared after, which is just what we would expect. If your kernel does not display this behavior, most likely there is something wrong with your wiring. Configuring the <devicename>cy</devicename> driver Contributed by Alex Nash. 6 June 1996. The Cyclades multiport cards are based on the cy driver instead of the usual sio driver used by other multiport cards. Configuration is a simple matter of: Add the cy device to your kernel configuration (note that your irq and iomem settings may differ). device cy0 at isa? irq 10 iomem 0xd4000 iosiz 0x2000 Rebuild and install the new kernel. Make the device nodes by typing (the following example assumes an 8-port board) You can omit this part if you are running FreeBSD 5.X with &man.devfs.5;. : &prompt.root; cd /dev &prompt.root; for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done If appropriate, add dialup entries to /etc/ttys by duplicating serial device (ttyd) entries and using ttyc in place of ttyd. For example: ttyc0 "/usr/libexec/getty std.38400" unknown on insecure ttyc1 "/usr/libexec/getty std.38400" unknown on insecure ttyc2 "/usr/libexec/getty std.38400" unknown on insecure … ttyc7 "/usr/libexec/getty std.38400" unknown on insecure Reboot with the new kernel. Configuring the <devicename>si</devicename> driver Contributed by &a.nsayer;. 25 March 1998. The Specialix SI/XIO and SX multiport cards use the si driver. A single machine can have up to 4 host cards. The following host cards are supported: ISA SI/XIO host card (2 versions) EISA SI/XIO host card PCI SI/XIO host card ISA SX host card PCI SX host card Although the SX and SI/XIO host cards look markedly different, their functionality are basically the same. The host cards do not use I/O locations, but instead require a 32K chunk of memory. The factory configuration for ISA cards places this at 0xd0000-0xd7fff. They also require an IRQ. PCI cards will, of course, auto-configure themselves. You can attach up to 4 external modules to each host card. The external modules contain either 4 or 8 serial ports. They come in the following varieties: SI 4 or 8 port modules. Up to 57600 bps on each port supported. XIO 8 port modules. Up to 115200 bps on each port supported. One type of XIO module has 7 serial and 1 parallel port. SXDC 8 port modules. Up to 921600 bps on each port supported. Like XIO, a module is available with one parallel port as well. To configure an ISA host card, add the following line to your kernel configuration file, changing the numbers as appropriate: device si0 at isa? iomem 0xd0000 irq 11 Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards and 11, 12 and 15 for SI/XIO ISA host cards. To configure an EISA or PCI host card, use this line: device si0 After adding the configuration entry, rebuild and install your new kernel. The following step, is not necessary if you are using &man.devfs.5; in FreeBSD 5.X. After rebooting with the new kernel, you need to make the device nodes in /dev. The MAKEDEV script will take care of this for you. Count how many total ports you have and type: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ttyAnn cuaAnn (where nn is the number of ports) If you want login prompts to appear on these ports, you will need to add lines like this to /etc/ttys: ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure Change the terminal type as appropriate. For modems, dialup or unknown is fine.