diff --git a/handbook/eresources.sgml b/handbook/eresources.sgml index da5042ded3..718d45da34 100644 --- a/handbook/eresources.sgml +++ b/handbook/eresources.sgml @@ -1,371 +1,371 @@ - + Resources on the Internet

Contributed by &a.jkh;.

The rapid pace of FreeBSD progress makes print media impractical as a means for following the latest developments. Electronic resources are the best, if not often the only way stay informed of the latest advances. Since FreeBSD is a volunteer effort, the user community itself also generally serves as a `technical support department' of sorts, with electronic mail and Usenet news being the most effective way of reaching that community. The most important points of contact with the FreeBSD user community are outlined below. If you are aware of other resources not mentioned here, please send them to the &a.doc so that they may also be included. Mailing lists

Though many of the FreeBSD development members read USENET, we cannot always guarantee that we will get to your questions in a timely fashion (or at all) if you post them only to one of the comp.unix.bsd.freebsd.* groups. By addressing your questions to the appropriate mailing list you will reach both us and a concentrated FreeBSD audience, invariably assuring a better (or at least faster) response.

The charters for the various lists are given at the bottom of this document. Please read the charter before joining a list since we must strive to keep the signal to noise ratio of the lists high, especially in the technical ones. Archives are kept for all of the mailing lists and can be searched using the the . The keyword searchable archive offers an excellent way of finding answers to frequently asked questions and should be consulted before posting a question. List summary

General lists: The following are general lists which anyone is free to join: List Purpose ---------------------------------------------------------------------- freebsd-announce Important events and project milestones freebsd-bugs Bug reports freebsd-chat Non-technical items related to the FreeBSD community freebsd-current Discussion concerning the use of FreeBSD-current freebsd-stable Discussion concerning the use of FreeBSD-stable freebsd-isp Issues for Internet Service Providers using FreeBSD freebsd-questions User questions Technical lists: The following lists are for technical discussion. You should read the charter carefully before joining one, keeping any messages sent to a list within the scope of the guidelines. List Purpose ---------------------------------------------------------------------- freebsd-doc The FreeBSD Documentation project freebsd-emulation Emulation of other systems such as Linux/DOS/Windows freebsd-fs Filesystems freebsd-hackers General technical discussion freebsd-hardware General discussion of hardware for running FreeBSD freebsd-mobile Discussions about mobile computing freebsd-multimedia Multimedia discussion freebsd-platforms Concerning ports to non-Intel architecture platforms freebsd-ports Discussion of the ports collection freebsd-security Security issues freebsd-scsi The SCSI subsystem freebsd-smp Design discussions for [A]Symmetric MultiProcessing Limited lists: The following lists require approval to join, though anyone is free to send suggestions and comments to them. It is a good idea establish a presence in the technical lists before asking to join one of these limited lists. List Purpose ---------------------------------------------------------------------- freebsd-admin Administrative issues freebsd-arch Architecture and design discussions freebsd-core FreeBSD core team freebsd-hubs People running mirror sites (infrastructural support) freebsd-install Installation development freebsd-user-groups User group coordination CVS lists: The following lists are for people interested in seeing the log messages for changes to various areas of the source tree. List name Source area Area Description (source for) ---------------------------------------------------------------------- cvs-CVSROOT /usr/src/[A-Z]* Top level /usr/src file changes cvs-all /usr/src All changes to the tree (superset) cvs-bin /usr/src/bin System binaries cvs-etc /usr/src/etc System files cvs-games /usr/src/games Games cvs-gnu /usr/src/gnu GPL'd utilities cvs-include /usr/src/include Include files cvs-kerberosIV /usr/src/kerberosIV Kerberos encryption code cvs-lib /usr/src/lib System libraries cvs-libexec /usr/src/libexec System binaries cvs-ports /usr/ports Ported software cvs-sbin /usr/src/sbin System binaries cvs-share /usr/src/share System shared files cvs-sys /usr/src/sys Kernel cvs-usrbin /usr/src/usr.bin Use binaries cvs-usrsbin /usr/src/usr.sbin System binaries How to subscribe

All mailing lists live on FreeBSD.ORG, so to post to a given list you simply mail to listname@FreeBSD.ORG. It will then be redistributed to mailing list members world-wide. To subscribe to a list, send mail to &a.majordomo and include subscribe [] In the body of your message. For example, to subscribe yourself to freebsd-announce, you'd do: % mail majordomo@FreeBSD.ORG subscribe freebsd-announce ^D If you want to subscribe yourself under a different name, or submit a subscription request for a local mailing list (note: this is more efficient if you have several interested parties at one site, and highly appreciated by us!), you would do something like: % mail majordomo@FreeBSD.ORG subscribe freebsd-announce local-announce@somesite.com ^D Finally, it is also possible to unsubscribe yourself from a list, get a list of other list members or see the list of mailing lists again by sending other types of control messages to majordomo. For a complete list of available commands, do this: % mail majordomo@FreeBSD.ORG help ^D Again, we would like to request that you keep discussion in the technical mailing lists on a technical track. If you are only interested in the "high points" then it is suggested that you join freebsd-announce, which is intended only for infrequent traffic. List charters

Administrative issues Important events / milestones This is the mailing list for people interested only in occasional announcements of significant freebsd events. This includes announcements about snapshots and other releases. It contains announcements of new FreeBSD capabilities. It may contain calls for volunteers etc. This is a low volume list. Architecture and design discussions This is the mailing list for people discussing FreeBSD architectural issues. It is a closed list, and not for general subscription. Bug reports This is the mailing list for reporting bugs in FreeBSD Whenever possible, bugs should be submitted using "send-pr". Non technical items related to the community This list contains the overflow from the other lists about non-technical, social information. It includes discussion about whether Jordan looks like a toon ferret or not, whether or not to type in capitals, who is drinking too much coffee, where the best beer is brewed, who is brewing beer in their basement, and so on. Occasional announcements of important events (such as upcoming parties, weddings, births, new jobs, etc) can be made to the technical lists, but the follow ups should be directed to this -chat list. FreeBSD core team This is an internal mailing list for use by the core members. Discussions about the use of FreeBSD-current This is the mailing list for users of freebsd-current. It includes warnings about new features coming out in -current that will affect the users, and instructions on steps that must be taken to remain -current. Anyone running "current" must subscribe to this list. Discussions about the use of FreeBSD-current This is the digest version of the freebsd-current mailing list. The digest consists of all messages sent to freebsd-current bundled together and mailed out as a single message. The average digest size is about 40kB. Discussions about the use of FreeBSD-stable This is the mailing list for users of freebsd-stable. It includes warnings about new features coming out in -stable that will affect the users, and instructions on steps that must be taken to remain -stable. Anyone running ``stable'' should subscribe to this list. Documentation project This mailing list belongs to the FreeBSD Doc Project and is for the discussion of documentation related issues and projects. Filesystems Discussions concerning FreeBSD filesystems. Technical discussions This is a forum for technical discussions related to FreeBSD. This is the primary technical mailing list. It is for individuals actively working on FreeBSD, to bring up problems or discuss alternative solutions. Individuals interested in following the technical discussion are also welcome. Technical discussions This is the digest version of the freebsd-hackers mailing list. The digest consists of all messages sent to freebsd-hackers bundled together and mailed out as a single message. The average digest size is about 40kB. General discussion of FreeBSD hardware General discussion about the types of hardware that FreeBSD runs on, various problems and suggestions concerning what to buy or avoid. Installation discussion This mailing list is for discussing FreeBSD installation development for the future releases. Issues for Internet Service Providers This mailing list is for discussing topics relevant to Internet Service Providers (ISPs) using FreeBSD. Multimedia discussions This is a forum about multimedia applications using FreeBSD. Discussion center around multimedia applications, their installation, their development and their support within FreeBSD Porting to Non-Intel platforms Cross-platform freebsd issues, general discussion and proposals for non-Intel FreeBSD ports. Discussion of "ports" Discussions concerning FreeBSD's "ports collection" (/usr/ports), proposed ports, modifications to ports collection infrastructure and general coordination efforts. User questions This is the mailing list for questions about FreeBSD. You should not send "how to" questions to the technical lists unless you consider the question to be pretty technical. User questions This is the digest version of the freebsd-questions mailing list. The digest consists of all messages sent to freebsd-questions bundled together and mailed out as a single message. The average digest size is about 40kB. SCSI subsystem This is the mailing list for people working on the scsi subsystem for FreeBSD. Security issues FreeBSD computer security issues (DES, Kerberos, known security holes and fixes, etc). User Group Coordination List This is the mailing list for the coordinators from each of the local area Users Groups to discuss matters with each other and a designated individual from the Core Team. This mail list should be limited to meeting synopsis and coordination of projects that span User Groups. Usenet newsgroups

In addition to two FreeBSD specific newsgroups, there are many others in which FreeBSD is discussed or are otherwise relevant to FreeBSD users. are available for some of these newsgroups from courtesy of Warren Toomey <wkt@cs.adfa.oz.au>. BSD specific newsgroups

Other Unix newsgroups of interest

- X-Window system + X Window System

World Wide Web servers

- Central Server. - Australia. - Brazil. - Canada. - Czech Republic. - Denmark. - Estonia. - Finland. - Germany. - Ireland. - Japan. - Korea. - Netherlands. - Portugal. - Sweden. - Taiwan. diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml index 549ce67a5d..0c1ed20d84 100644 --- a/handbook/handbook.sgml +++ b/handbook/handbook.sgml @@ -1,171 +1,171 @@ - + %authors; %lists; %sections; ]> FreeBSD Handbook <author> <name>The FreeBSD Documentation Project</name> </author> <date>July 1996</date> <abstract>Welcome to FreeBSD! This handbook covers the installation and day to day use of <bf>FreeBSD Release &rel.current;</bf>. This manual is a <bf>work in progress</bf> and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc The latest version of this document is always available from the <url url="http://www.FreeBSD.ORG/" name="FreeBSD World Wide Web server">. It may also be downloaded in ascii, LaTeX, postscript or HTML from the <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs" name="FreeBSD FTP server"> or one of the numerous <ref id="mirrors" name="mirror sites">. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <chapt><heading>Introduction</heading> <p>FreeBSD is a 4.4BSD-Lite based operating system for Intel architecture (x86) based PCs. For an overview of FreeBSD, see <ref id="nutshell" name="FreeBSD in a nutshell">. For a history of the project, read <ref id="history" name="a brief history of FreeBSD">. To see a description of the latest release, read <ref id="relnotes" name="about the current release">. If you're interested in contributing something to the FreeBSD project (code, equipment, sacks of unmarked bills), please see about <ref id="submitters" name="contributing to FreeBSD">. &nutshell; &history; &goals; &relnotes; &install; &basics; <chapt><heading>Installing applications</heading> <sect><heading>* Installing packages</heading> &ports; <!-- ************************************************************ --> <part><heading>System Administration</heading> &kernelconfig; <chapt><heading>Users, groups and security</heading> &crypt; &skey; &kerberos; &firewalls; &printing; "as; - <chapt><heading>The X-Window System</heading> + <chapt><heading>The X Window System</heading> <p>Pending the completion of this section, please refer to documentation supplied by the <url url="http://www.xfree86.org/" name="The XFree86 Project, Inc">. &hw; <!-- ************************************************************ --> <part><heading>Network Communications</heading> <chapt><heading>Basic Networking</heading> <sect><heading>* Ethernet basics</heading> <sect><heading>* Serial basics</heading> &term; &dialup; <chapt><heading>PPP and SLIP</heading> <p>If your connection to the Internet is through a modem, or you wish to provide other people with dialup connections to the Internet using FreeBSD, you have the option of using PPP or SLIP. Furthermore, two varieties of PPP are provided: <em>user</em> (sometimes referred to as iijppp) and <em>kernel</em>. The procedures for configuring both types of PPP, and for setting up SLIP are described in this chapter. &userppp; &ppp; &slipc; &slips; <chapt><heading>Advanced networking</heading> &routing; &nfs; &diskless; <sect><heading>* Yellow Pages/NIS</heading> &isdn; <chapt><heading>* Mail</heading> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> ¤t; &stable; &synching; &submitters; &troubleshooting; &kerneldebug; &linuxemu; <chapt><heading>FreeBSD internals</heading> &booting; &memoryuse; &dma; <!-- ************************************************************ --> <part><heading>Appendices</heading> &mirrors; &bibliography; &eresources; &contrib; &policies; &pgpkeys; <!-- &glossary; --> </book> </linuxdoc> diff --git a/handbook/install.sgml b/handbook/install.sgml index 5ebd985292..03fb94b4e7 100644 --- a/handbook/install.sgml +++ b/handbook/install.sgml @@ -1,816 +1,816 @@ -<!-- $Id: install.sgml,v 1.33 1996-08-09 15:33:31 jfieber Exp $ --> +<!-- $Id: install.sgml,v 1.34 1996-08-28 00:43:57 asami Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> --> <chapt><heading>Installing FreeBSD<label id="install"></heading> <p>So, you would like to try out FreeBSD on your system? This section is a quick-start guide for what you need to do. FreeBSD can be installed from a variety of media including CD-ROM, floppy disk, magnetic tape, an MS-DOS partition, and if you have a network connection, via anonymous ftp or NFS. Regardless of the installation media you choose, you can get started by downloading the <bf>installation disk</bf> as described below. Booting your computer with disk will provide important information about compatibility between FreeBSD and your hardware which could dictate which installation options are possible. It can also provide early clues to compatibility problems that could prevent FreeBSD running on your system at all. If you plan on installing via anonymous FTP, then this installation disk is all you need to download. For more information on obtaining the FreeBSD distribution itself, please see <ref id="mirrors" name="Obtaining FreeBSD"> in the Appendix. So, to get the show on the road, follow these steps: <enum> <item>Review the <ref id="install:hw" name="supported configurations"> section of this installation guide to be sure that your hardware is supported by FreeBSD. It may be helpful to make a list of any special cards you have installed, such as SCSI controllers, Ethernet adapters or sound cards. This list should include relevant configuration parameters such as interrupts (IRQ) and IO port addresses. </item> <item>Download the <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/&rel.current;-RELEASE/floppies/boot.flp" name="installation boot disk image"> file to your hard drive, and be sure to tell your browser to <em>save</em> rather than <em>display</em>. <bf>Note:</bf> This disk image can be used for <em>both</em> 1.44 megabyte 3.5 inch floppy disks and 1.2 megabyte 5.25 inch floppy disks.</item> <item>Make the installation boot disk from the image file: <itemize> <item>If you are using MS-DOS download <url url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/tools/dos-tools/rawrite.exe" name="rawrite.exe">, then run it: <tscreen><verb> C:\> rawrite </verb></tscreen> The program will prompt you for the floppy drive containing the disk you want to write to (A: or B:) and the name of the file to put on disk (boot.flp). </item> <item>If you are using a UNIX system: <tscreen> % dd if=boot.flp of=<em>disk_device</em> </tscreen> where <em>disk_device</em> is the <tt>/dev</tt> entry for the floppy drive. On FreeBSD systems, this is <tt>/dev/fd0</tt> for the A: drive and <tt>/dev/fd1</tt> for the B: drive. </item> </itemize> </item> <item>With the installation disk in the A: drive, reboot your computer. You should get a boot prompt something like this: <tscreen> >> FreeBSD BOOT ...<newline> Usage: [[[0:][wd](0,a)]/kernel][-abcCdhrsv]<newline> Use 1:sd(0,a)kernel to boot sd0 if it is BIOS drive 1<newline> Use ? for file list or press Enter for defaults<newline> Boot: </tscreen> If you do <em>not</em> type anything, FreeBSD will automatically boot with its default configuration after a delay of about five seconds. As FreeBSD boots, it probes your computer to determine what hardware is installed. The results of this probing is displayed on the screen. </item> <item>When the booting process is finished, The main FreeBSD installation menu will be displayed.</item> </enum> <p><bf>If something goes wrong...</bf> <p>Due to limitations of the PC architecture, it is impossible for probing to be 100 percent reliable. In the event that your hardware is incorrectly identified, or that the probing causes your computer to lock up, first check the <ref id="install:hw" name="supported configurations"> section of this installation guide to be sure that your hardware is indeed supported by FreeBSD. <p>If your hardware is supported, reset the computer and when the <tt>Boot:</tt> prompt comes up, type <bf>-c</bf>. This puts FreeBSD into a configuration mode where you can supply hints about your hardware. The FreeBSD kernel on the installation disk is configured assuming that most hardware devices are in their factory default configuration in terms of IRQs, IO addresses and DMA channels. If your hardware has been reconfigured, you will most likely need to use the <bf>-c</bf> option at boot to tell FreeBSD where things are. <p>It is also possible that a probe for a device not present will cause a later probe for another device that is present to fail. In that case, the probes for the conflicting driver(s) should be disabled. <p>In the configuration mode, you can: <itemize> <item>List the device drivers installed in the kernel.</item> <item>Disable device drivers for hardware not present in your system.</item> <item>Change the IRQ, DRQ, and IO port addresses used by a device driver.</item> </itemize> <p>While at the <tt>config></tt> prompt, type <tt>help</tt> for more information on the available commands. After adjusting the kernel to match how you have your hardware configured, type <tt>quit</tt> at the <tt>config></tt> prompt to continue booting with the new settings. After FreeBSD has been installed, changes made in the configuration mode will be permanent so you do not have to reconfigure every time you boot. Even so, it is likely that you will want to build a custom kernel to optimize the performance of your system. See <ref id="kernelconfig" name="Kernel configuration"> for more information on creating custom kernels. <sect><heading>Supported Configurations<label id="install:hw"></heading> <p>FreeBSD currently runs on a wide variety of ISA, VLB, EISA and PCI bus based PC's, ranging from 386sx to Pentium class machines (though the 386sx is not recommended). Support for generic IDE or ESDI drive configurations, various SCSI controller, network and serial cards is also provided. A minimum of four megabytes of RAM is required to run FreeBSD. - To run the X-window system, eight megabytes of RAM is the + To run the X Window System, eight megabytes of RAM is the recommended minimum. Following is a list of all disk controllers and Ethernet cards currently known to work with FreeBSD. Other configurations may very well work, and we have simply not received any indication of this. <sect1><heading>Disk Controllers</heading> <p> <itemize> <item>WD1003 (any generic MFM/RLL) <item>WD1007 (any generic IDE/ESDI) <item>IDE <item>ATA <item>Adaptec 152x series ISA SCSI controllers <item>Adaptec 154x series ISA SCSI controllers <item>Adaptec 174x series EISA SCSI controller in standard and enhanced mode. <item>Adaptec 274x/284x/2940/3940 (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers <item>Adaptec AIC7850 on-board SCSI controllers <item>Adaptec <!-- AIC-6260 and - actually not working, joerg --> AIC-6360 based boards, which includes the AHA-152x and SoundBlaster SCSI cards. <bf>Note:</bf> You cannot boot from the SoundBlaster cards as they have no on-board BIOS, which is necessary for mapping the boot device into the system BIOS I/O vectors. They are perfectly usable for external tapes, CDROMs, etc, however. The same goes for any other AIC-6x60 based card without a boot ROM. Some systems DO have a boot ROM, which is generally indicated by some sort of message when the system is first powered up or reset. Check your system/board documentation for more details. <item>Buslogic 545S & 545c <bf>Note:</bf> that Buslogic was formerly known as "Bustek". <item>Buslogic 445S/445c VLB SCSI controller <item>Buslogic 742A/747S/747c EISA SCSI controller. <item>Buslogic 946c PCI SCSI controller <item>Buslogic 956c PCI SCSI controller <item>NCR 53C810/53C815/53C825/53C860/53C875 PCI SCSI controller. <item>NCR5380/NCR53400 (``ProAudio Spectrum'') SCSI controller. <item>DTC 3290 EISA SCSI controller in 1542 emulation mode. <item>UltraStor 14F/24F/34F SCSI controllers. <item>Seagate ST01/02 SCSI controllers. <item>Future Domain 8xx/950 series SCSI controllers. <item>WD7000 SCSI controllers. </itemize> With all supported SCSI controllers, full support is provided for SCSI-I & SCSI-II peripherals, including Disks, tape drives (including DAT) and CD ROM drives. The following CD-ROM type systems are supported at this time: <itemize> <item>SoundBlaster SCSI and ProAudio Spectrum SCSI (<tt>cd</tt>) <item>Mitsumi (all models) proprietary interface (<tt>mcd</tt>) <item>Matsushita/Panasonic (Creative) CR-562/CR-563 proprietary interface (<tt>matcd</tt>) <item>Sony proprietary interface (<tt>scd</tt>) <item>ATAPI IDE interface (experimental and should be considered ALPHA quality!) (<tt>wcd</tt>) </itemize> <sect1><heading>Ethernet cards</heading> <p> <itemize> <item>Allied-Telesis AT1700 and RE2000 cards <item>SMC Elite 16 WD8013 Ethernet interface, and most other WD8003E, WD8003EBT, WD8003W, WD8013W, WD8003S, WD8003SBT and WD8013EBT based clones. SMC Elite Ultra is also supported. <item>DEC EtherWORKS III NICs (DE203, DE204, and DE205) <item>DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422) <item>DEC DC21040/DC21041/DC21140 based NICs: <itemize> <item>ASUS PCI-L101-TB <item>Accton ENI1203 <item>Cogent EM960PCI <item>Compex CPXPCI/32C <item>D-Link DE-530 <item>DEC DE435 <item>Danpex EN-9400P3 <item>JCIS Condor JC1260 <item>Linksys EtherPCI <item>Mylex LNP101 <item>SMC EtherPower 10/100 (Model 9332) <item>SMC EtherPower (Model 8432) <item>Zynx ZX342 </itemize> <item>DEC FDDI (DEFPA/DEFEA) NICs <item>Fujitsu FMV-181 and FMV-182 <item>Fujitsu MB86960A/MB86965A <item>Intel EtherExpress <item>Intel EtherExpress Pro/100B 100Mbit. <item>Isolan AT 4141-0 (16 bit) <item>Isolink 4110 (8 bit) <item>Novell NE1000, NE2000, and NE2100 ethernet interface. <item>3Com 3C501 cards <item>3Com 3C503 Etherlink II <item>3Com 3c505 Etherlink/+ <item>3Com 3C507 Etherlink 16/TP <item>3Com 3C509, 3C579, 3C589 (PCMCIA) Etherlink III <item>3Com 3C590, 3C595 Etherlink III <item>Toshiba ethernet cards <item>PCMCIA ethernet cards from IBM and National Semiconductor are also supported. </itemize> <p><em>Note:</em> FreeBSD does not currently support PnP (plug-n-play) features present on some ethernet cards. If your card has PnP and is giving you problems, try disabling its PnP features. <sect1><heading>Miscellaneous devices</heading> <p> <itemize> <item>AST 4 port serial card using shared IRQ. <item>ARNET 8 port serial card using shared IRQ. <item>BOCA IOAT66 6 port serial card using shared IRQ. <item>BOCA 2016 16 port serial card using shared IRQ. <item>Cyclades Cyclom-y Serial Board. <item>STB 4 port card using shared IRQ. <item>SDL Communications Riscom/8 Serial Board. <item>Digiboard Sync/570i high-speed sync serial card. <item>Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum, Gravis UltraSound, Gravis UltraSound MAX and Roland MPU-401 sound cards. </itemize> FreeBSD does not currently support IBM's microchannel (MCA) bus. <sect><heading>Preparing for the installation</heading> <p>There are a number of different methods by which FreeBSD can be installed. The following describes what preparation needs to be done for each type. <sect1><heading>Before installing from CDROM</heading> <p>If your CDROM is of an unsupported type, then please skip to <ref id="install:msdos" name="MS-DOS Preparation">. There is not a lot of preparatory work that needs to be done to successfully install from one of Walnut Creek's FreeBSD CDROMs (other CDROM distributions may work as well, though we cannot say for certain as we have no hand or say in how they are created). You can either boot into the CD installation directly from DOS using Walnut Creek's supplied ``install.bat'' batch file or you can make a boot floppy with the ``makeflp.bat'' command. [NOTE: If you are running FreeBSD 2.1-RELEASE and have an IDE CDROM, use the inst_ide.bat or atapiflp.bat batch files instead]. For the easiest interface of all (from DOS), type ``view''. This will bring up a DOS menu utility that leads you through all the available options. If you are creating the boot floppy from a UNIX machine, see <ref id="install" name="the beginning of this guide"> for examples. of how to create the boot floppy. Once you have booted from DOS or floppy, you should then be able to select CDROM as the media type in the Media menu and load the entire distribution from CDROM. No other types of installation media should be required. After your system is fully installed and you have rebooted from the hard disk, you can mount the cdrom at any time by typing: <tt>mount /cdrom</tt> Before removing the CD again, also note that it is necessary to first type: <tt>umount /cdrom</tt>. Do not just remove it from the drive! <quote><bf>Special note:</bf> Before invoking the installation, be sure that the CDROM is in the drive so that the install probe can find it. This is also true if you wish the CDROM to be added to the default system configuration automatically during the install (whether or not you actually use it as the installation media). </quote> Finally, if you would like people to be able to FTP install FreeBSD directly from the CDROM in your machine, you will find it quite easy. After the machine is fully installed, you simply need to add the following line to the password file (using the vipw command): <tscreen><verb> ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent </verb></tscreen> Anyone with network connectivity to your machine (and permission to log into it) can now chose a Media type of FTP and type in: <tt>ftp://<em>your machine</em></tt> after picking ``Other'' in the ftp sites menu. <sect1><heading>Before installing from Floppy</heading> <p>If you must install from floppy disks, either due to unsupported hardware or simply because you enjoy doing things the hard way, you must first prepare some floppies for the install. The first floppy that you will need in addition to the boot.flp image is ``floppies/root.flp'', which is somewhat special in that it is not a DOS filesystem floppy at all, but rather a floppy "image" (it's actually a gzip'd cpio file). You can create this floppy in the same way that you created the boot floppy <ref id="install" name="the beginning of this guide">. Once this floppy is made, you can go on to make the distribution set floppies using ordinary DOS or UFS (if you are preparing the floppies on another FreeBSD machine) formatted diskettes. You will need, at minimum, as many 1.44MB or 1.2MB floppies as it takes to hold all files in the bin (binary distribution) directory. If you are preparing these floppies under DOS, then THESE floppies *must* be formatted using the MS-DOS FORMAT command. If you are using Windows, use the Windows File Manager format command. Do <em>not</em> trust Factory Preformatted floppies! Format them again yourself, just to make sure. Many problems reported by our users in the past have resulted from the use of improperly formatted media, which is why I am taking such special care to mention it here! If you are creating the floppies from another FreeBSD machine, a format is still not a bad idea though you do nott need to put a DOS filesystem on each floppy. You can use the `disklabel' and `newfs' commands to put a UFS filesystem on them instead, as the following sequence of commands (for a 3.5" 1.44MB floppy disk) illustrates: <tscreen><verb> fdformat -f 1440 fd0.1440 disklabel -w -r fd0.1440 floppy3 newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0 (Use "fd0.1200" and "floppy5" for 5.25" 1.2MB disks). </verb></tscreen> Then you can mount and write to them like any other file system. After you have formatted the floppies, you will need to copy the files onto them. The distribution files are split into chunks conveniently sized so that 5 of them will fit on a conventional 1.44MB floppy. Go through all your floppies, packing as many files as will fit on each one, until you have got all the distributions you want packed up in this fashion. Each distribution should go into a subdirectory on the floppy, e.g.: <bf>a:\bin\bin.aa</bf>, <bf>a:\bin\bin.ab</bf>, and so on. Once you come to the Media screen of the install, select ``Floppy'' and you will be prompted for the rest. <sect1><heading>Before installing from a MS-DOS partition<label id="install:msdos"></heading> <p>To prepare for installation from an MS-DOS partition, copy the files from the distribution into a directory called <tt>C:\FREEBSD</tt>. The directory tree structure of the CDROM must be partially reproduced within this directory so we suggest using the DOS <tt>xcopy</tt> command. For example, to prepare for a minimal installation of FreeBSD: <tscreen><verb> C> MD C:\FREEBSD C> XCOPY /S E:\DISTS\BIN C:\FREEBSD\BIN\ C> XCOPY /S E:\FLOPPIES C:\FREEBSD\FLOPPIES\ </verb></tscreen> assuming that <tt>C:</tt> is where you have free space and <tt>E:</tt> is where your CDROM is mounted. Note that you need the <tt>FLOPPIES</tt> directory because the <tt>root.flp</tt> image is needed during an MS-DOS installation. For as many `DISTS' you wish to install from MS-DOS (and you have free space for), install each one under <tt>C:\FREEBSD</tt> - the <tt>BIN</tt> dist is only the minimal requirement. If you have room on your MS-DOS partition for all the distributions, you could replace the last line above with: <tscreen><verb> C> XCOPY /S E:\DISTS C:\FREEBSD\ </verb></tscreen> which would copy all the subdirectories of <tt>E:\DISTS</tt> to <tt>C:\FREEBSD</tt>. <sect1><heading>Before installing from QIC/SCSI Tape</heading> <p>Installing from tape is probably the easiest method, short of an on-line install using FTP or a CDROM install. The installation program expects the files to be simply tar'ed onto the tape, so after getting all of the files for distribution you are interested in, simply tar them onto the tape with a command like: <tscreen> cd /freebsd/distdir<newline> tar cvf /dev/rwt0 (or /dev/rst0) dist1 .. dist2 </tscreen> Make sure that the `floppies/' directory is one of the ``dists'' given above, since the installation will look for `floppies/root.flp' on the tape. When you go to do the installation, you should also make sure that you leave enough room in some temporary directory (which you will be allowed to choose) to accommodate the <bf>full</bf> contents of the tape you have created. Due to the non-random access nature of tapes, this method of installation requires quite a bit of temporary storage. You should expect to require as much temporary storage as you have stuff written on tape. <quote><bf>Note:</bf> When going to do the installation, the tape must be in the drive <em>before</em> booting from the boot floppy. The installation probe may otherwise fail to find it.</quote> <sect1><heading>Before installing over a network</heading> <p>You can do network installations over 3 types of communications links: <descrip> <tag>Serial port</tag> SLIP or PPP <tag>Parallel port</tag> PLIP (laplink cable) <tag>Ethernet</tag> A standard ethernet controller (includes some PCMCIA). </descrip> SLIP support is rather primitive, and limited primarily to hard-wired links, such as a serial cable running between a laptop computer and another computer. The link should be hard-wired as the SLIP installation does not currently offer a dialing capability; that facility is provided with the PPP utility, which should be used in preference to SLIP whenever possible. If you are using a modem, then PPP is almost certainly your only choice. Make sure that you have your service provider's information handy as you will need to know it fairly soon in the installation process. You will need to know, at the minimum, your service provider's IP address and possibly your own (though you can also leave it blank and allow PPP to negotiate it with your ISP). You also need to know how to use the various ``AT commands'' to dial the ISP with your particular modem as the PPP dialer provides only a very simple terminal emulator. If a hard-wired connection to another FreeBSD (2.0R or later) machine is available, you might also consider installing over a ``laplink'' parallel port cable. The data rate over the parallel port is much higher than what is typically possible over a serial line (up to 50k/sec), thus resulting in a quicker installation. Finally, for the fastest possible network installation, an ethernet adaptor is always a good choice! FreeBSD supports most common PC ethernet cards, a table of supported cards (and their required settings) is provided in <ref id="install:hw" name="Supported Hardware">. If you are using one of the supported PCMCIA ethernet cards, also be sure that it is plugged in <em>before</em> the laptop is powered on! FreeBSD does not, unfortunately, currently support hot insertion of PCMCIA cards during installation. You will also need to know your IP address on the network, the netmask value for your address class, and the name of your machine. Your system administrator can tell you which values to use for your particular network setup. If you will be referring to other hosts by name rather than IP address, you will also need a name server and possibly the address of a gateway (if you are using PPP, it is your provider's IP address) to use in talking to it. If you do not know the answers to all or most of these questions, then you should really probably talk to your system administrator <em>first</em> before trying this type of installation. Once you have a network link of some sort working, the installation can continue over NFS or FTP. <sect2><heading>Preparing for NFS installation</heading> <p>NFS installation is fairly straight-forward: Simply copy the FreeBSD distribution files you want onto a server somewhere and then point the NFS media selection at it. If this server supports only ``privileged port'' access (as is generally the default for Sun workstations), you will need to set this option in the Options menu before installation can proceed. If you have a poor quality ethernet card which suffers from very slow transfer rates, you may also wish to toggle the appropriate Options flag. In order for NFS installation to work, the server must support subdir mounts, e.g., if your FreeBSD &rel.current; distribution directory lives on: <bf>ziggy:/usr/archive/stuff/FreeBSD</bf> Then ziggy will have to allow the direct mounting of <bf>/usr/archive/stuff/FreeBSD</bf>, not just <bf>/usr</bf> or <bf>/usr/archive/stuff</bf>. In FreeBSD's <bf>/etc/exports</bf> file, this is controlled by the ``<tt>-alldirs</tt>'' option. Other NFS servers may have different conventions. If you are getting `Permission Denied' messages from the server then it is likely that you do not have this enabled properly. <sect2><heading>Preparing for FTP Installation</heading> <p>FTP installation may be done from any mirror site containing a reasonably up-to-date version of FreeBSD &rel.current;. A full menu of reasonable choices from almost anywhere in the world is provided by the FTP site menu. If you are installing from some other FTP site not listed in this menu, or you are having troubles getting your name server configured properly, you can also specify your own URL by selecting the ``Other'' choice in that menu. A URL can also be a direct IP address, so the following would work in the absence of a name server: <tscreen><verb> ftp://192.216.222.4/pub/FreeBSD/&rel.current;-RELEASE </verb></tscreen> There are two FTP installation modes you can use: <descrip> <tag>FTP Active</tag> For all FTP transfers, use ``Active'' mode. This will not work through firewalls, but will often work with older ftp servers that do not support passive mode. If your connection hangs with passive mode (the default), try active! <tag>FTP Passive</tag> For all FTP transfers, use ``Passive'' mode. This allows the user to pass through firewalls that do not allow incoming connections on random port addresses. </descrip> <quote><bf>Note:</bf> Active and passive modes are not the same as a `proxy' connection, where a proxy ftp server is listening on a different port!</quote> In such instances, you should specify the URL as something like: <tscreen><verb> ftp://foo.bar.com:1234/pub/FreeBSD </verb></tscreen> Where ``1234'' is the port number of the proxy ftp server. <sect><heading>Installing FreeBSD</heading> <p>Once you have taken note of the appropriate preinstallation steps, you should be able to install FreeBSD without any further trouble. Should this not be true, then you may wish to go back and re-read the relevant preparation section above for the installation media type you are trying to use, perhaps there is a helpful hint there that you missed the first time? If you are having hardware trouble, or FreeBSD refuses to boot at all, read the Hardware Guide provided on the boot floppy for a list of possible solutions. The FreeBSD boot floppy contains all the on-line documentation you should need to be able to navigate through an installation and if it does not then we would like to know what you found most confusing. Send your comments to the &a.doc;. It is the objective of the FreeBSD installation program (sysinstall) to be self-documenting enough that painful ``step-by-step'' guides are no longer necessary. It may take us a little while to reach that objective, but that is the objective! Meanwhile, you may also find the following ``typical installation sequence'' to be helpful: <enum> <item>Boot the boot floppy. After a boot sequence which can take anywhere from from 30 seconds to 3 minutes, depending on your hardware, you should be presented with a menu of initial choices. If the floppy does not boot at all, or the boot hangs at some stage, go read the Q&A section of the Hardware Guide for possible causes. <item>Press F1. You should see some basic usage instructions on the menu system and general navigation. If you have not used this menu system before then PLEASE read this thoroughly! <item>Select the Options item and set any special preferences you may have. <item>Select a Novice, Custom or Express install, depending on whether or not you would like the installation to help you through a typical installation, give you a high degree of control over each step of the installation or simply whizz through it (using reasonable defaults when possible) as fast as possible. If you've never used FreeBSD before then the Novice installation method is most recommended. <item>The final configuration menu choice allows you to further configure your FreeBSD installation by giving you menu-driven access to various system defaults. Some items, like networking, may be especially important if you did a CDROM/Tape/Floppy installation and have not yet configured your network interfaces (assuming you have any). Properly configuring such interfaces here will allow FreeBSD to come up on the network when you first reboot from the hard disk. </enum> <sect><heading>MS-DOS user's Questions and Answers</heading> <p>Many FreeBSD users wish to install FreeBSD on PCs inhabited by MS-DOS. Here are some commonly asked questions about installing FreeBSD on such systems. <p><bf>Help! I have no space! Do I need to delete everything first?</bf> If your machine is already running MS-DOS and has little or no free space available for FreeBSD's installation, all is not lost! You may find the FIPS utility, provided in the <tt>tools</tt> directory on the FreeBSD CDROM or on the various FreeBSD ftp sites, to be quite useful. FIPS allows you to split an existing MS-DOS partition into two pieces, preserving the original partition and allowing you to install onto the second free piece. You first defragment your MS-DOS partition, using the DOS 6.xx DEFRAG utility or the Norton Disk tools, then run FIPS. It will prompt you for the rest of the information it needs. Afterwards, you can reboot and install FreeBSD on the new free slice. See the <em>Distributions</em> menu for an estimation of how much free space you will need for the kind of installation you want. <bf>Can I use compressed MS-DOS filesystems from FreeBSD?</bf> No. If you are using a utility such as Stacker(tm) or DoubleSpace(tm), FreeBSD will only be able to use whatever portion of the filesystem you leave uncompressed. The rest of the filesystem will show up as one large file (the stacked/dblspaced file!). <bf>Do not remove that file!</bf> You will probably regret it greatly! It is probably better to create another uncompressed MS-DOS primary partition and use this for communications between MS-DOS and FreeBSD. <bf>Can I mount my MS-DOS extended partitions?</bf> Yes. DOS extended partitions are mapped in at the end of the other ``slices'' in FreeBSD, e.g. your D: drive might be /dev/sd0s5, your E: drive /dev/sd0s6, and so on. This example assumes, of course, that your extended partition is on SCSI drive 0. For IDE drives, substitute ``wd'' for ``sd'' appropriately. You otherwise mount extended partitions exactly like you would mount any other DOS drive, e.g.: <tscreen><verb> mount -t msdos /dev/sd0s5 /dos_d </verb></tscreen> <bf>Can I run MS-DOS binaries under FreeBSD?</bf> Not yet! We would like to add support for this someday, but are still lacking anyone to actually do the work. BSDI has also donated their DOS emulator to the BSD world and this is slowly being ported to FreeBSD-current. Send mail to the &a.emulation if you're interested in joining this effort! In the interim, there is a nice application available in the <ref id="ports" name="The Ports Collection"> called pcemu which allows you to run many basic MS-DOS text-mode binaries by entirely emulating an 8088 CPU. diff --git a/handbook/kernelconfig.sgml b/handbook/kernelconfig.sgml index 11de584a35..907bd8980f 100644 --- a/handbook/kernelconfig.sgml +++ b/handbook/kernelconfig.sgml @@ -1,1278 +1,1278 @@ -<!-- $Id: kernelconfig.sgml,v 1.16 1996-08-27 12:00:18 wosch Exp $ --> +<!-- $Id: kernelconfig.sgml,v 1.17 1996-08-28 00:43:58 asami Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> --> <chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading> <p><em>Contributed by &a.jehamby;.<newline>6 October 1995.</em> This large section of the handbook discusses the basics of building your own custom kernel for FreeBSD. This section is appropriate for both novice system administrators and those with advanced Unix experience. <sect><heading>Why build a custom kernel?</heading> <p>Building a custom kernel is one of the most important rites of passage every Unix system administrator must learn. This process, while time-consuming, will provide many benefits to your FreeBSD system. Unlike the GENERIC kernel, which must support every possible SCSI and network card, along with tons of other rarely used hardware support, a custom kernel only contains support for <em>your</em> PC's hardware. This has a number of benefits: <itemize> <item>It will take less time to boot because it does not have to spend time probing for hardware which you do not have. <item>A custom kernel often uses less memory, which is important because the kernel is the one process which must always be present in memory, and so all of that unused code ties up pages of RAM that your programs would otherwise be able to use. Therefore, on a system with limited RAM, building a custom kernel is of critical importance. <item>Finally, there are several kernel options which you can tune to fit your needs, and device driver support for things like sound cards which you can include in your kernel but are <em>not</em> present in the GENERIC kernel. </itemize></p> <sect><heading>Building and Installing a Custom Kernel<label id="kernelconfig:building"></heading> <p>First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main <tt>/usr/src/sys</tt> directory, which is also accessible through <tt>/sys</tt>. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, are <tt>i386/conf</tt>, where you will edit your custom kernel configuration, and <tt>compile</tt>, which is the staging area where your kernel will be built. Notice the logical organization of the directory tree, with each supported device, filesystem, and option in its own subdirectory. Also, anything inside the <tt>i386</tt> directory deals with PC hardware only, while everything outside the <tt>i386</tt> directory is common to all platforms which FreeBSD could potentially be ported to. <quote><em/Note:/ If there is <em>not</em> a <tt>/usr/src/sys</tt> directory on your system, then the kernel source has not been been installed. Follow the instructions for installing packages to add this package to your system.</quote> Next, move to the <tt>i386/conf</tt> directory and copy the GENERIC configuration file to the name you want to give your kernel. For example: <tscreen><verb> # cd /usr/src/sys/i386/conf # cp GENERIC MYKERNEL </verb></tscreen> Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it MYKERNEL for the purpose of this example. <quote><em/Note:/ You must execute these and all of the following commands under the root account or you will get ``permission denied'' errors.</quote> Now, edit MYKERNEL with your favorite text editor. If you're just starting out, the only editor available will probably be <tt>vi</tt>, which is too complex to explain here, but is covered well in many books in the <ref id="bibliography" name="bibliography">. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. If you have build a kernel under SunOS or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the <ref id="kernelconfig:config" name="Configuration File"> section slowly and carefully. <quote><em/Note:/ If you are trying to upgrade your kernel from an older version of FreeBSD, you will probably have to get a new version of <tt>config(8)</tt> from the same place you got the new kernel sources. It is located in <tt>/usr/src/usr.sbin</tt>, so you will need to download those sources as well. Re-build and install it before running the next commands.</quote> When you are finished, type the following to compile and install your kernel: <tscreen><verb> # /usr/sbin/config MYKERNEL # cd ../../compile/MYKERNEL # make depend # make # make install </verb></tscreen> The new kernel will be copied to the root directory as <tt>/kernel</tt> and the old kernel will be moved to <tt>/kernel.old</tt>. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some <ref id="kernelconfig:trouble" name= "troubleshooting"> instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel <ref id="kernelconfig:noboot" name="does not boot">. <quote><em/Note:/ If you have added any new devices (such as sound cards) you may have to add some <ref id="kernelconfig:nodes" name="device nodes"> to your <tt>/dev</tt> directory before you can use them.</quote> <sect><heading>The Configuration File<label id="kernelconfig:config"></heading> <p>The general format of a configuration file is quite simple. Each line contains a keyword and one or more arguments. For simplicity, most lines only contain one argument. Anything following a <tt>#</tt> is considered a comment and ignored. The following sections describe each keyword, generally in the order they are listed in GENERIC, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the GENERIC file. An exhaustive list of options and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. <p>The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file was simply converted into a <tt>-D</tt> switch for the <tt>CFLAGS</tt> line of the kernel Makefile. Naturally, this caused a creaping optionism, with nobody really knowing which option has been referenced in what files. <p>In the new scheme, every <tt>#ifdef</tt> that is intended to be dependant upon an option gets this option out of an <tt>opt_<em>foo</em>.h</tt> declaration file created in the compile directory by <tt>config</tt>. The list of valid options for <tt>config</tt> lives in two files: options that do not depend on the architecture are listed in <tt>/sys/conf/options</tt>, architecture-dependant ones in <tt>/sys/<em>arch</em>/conf/options.<em>arch</em></tt>, with <em>arch</em> being for example <tt>i386</tt>. <sect1><heading>Mandatory Keywords</heading> <p>These keywords are required in every kernel you build. <descrip> <tag>machine ``i386''</tag> <p>The first keyword is <tt>machine</tt>, which, since FreeBSD only runs on Intel 386 and compatible chips, is i386. <quote><em>Note:</em> that any keyword which contains numbers used as text must be enclosed in quotation marks, otherwise <tt>config</tt> gets confused and thinks you mean the actual number 386.</quote> <tag>cpu ``<em>cpu_type</em>''</tag> <p>The next keyword is <tt>cpu</tt>, which includes support for each CPU supported by FreeBSD. The possible values of <tt><em>cpu_type</em></tt> include: <itemize> <item>I386_CPU <item>I486_CPU <item>I586_CPU <item>I686_CPU </itemize> and multiple instances of the <tt>cpu</tt> line may be present with different values of <tt><em>cpu_type</em></tt> as are present in the GENERIC kernel. For a custom kernel, it is best to specify only the cpu you have. If, for example, you have an Intel Pentium, use <tt>I586_CPU</tt> for <tt><em>cpu_type</em></tt>. <tag>ident <em>machine_name</em></tag> <p>Next, we have <tt>ident</tt>, which is the identification of the kernel. You should change this from GENERIC to whatever you named your kernel, in this example, MYKERNEL. The value you put in <tt>ident</tt> will print when you boot up the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your usual kernel (if you want to build an experimental kernel, for example). Note that, as with <tt>machine</tt> and <tt> cpu</tt>, enclose your kernel's name in quotation marks if it contains any numbers. Since this name is passed to the C compiler as a <tt>-D</tt> switch, do not use names like <tt> DEBUG</tt>, or something that could be confused with another machine or CPU name, like <tt>vax</tt>. <tag>maxusers <em>number</em></tag> <p>This file sets the size of a number of important system tables. This number is supposed to be roughly equal to the number of simultaneous users you expect to have on your machine. However, under normal circumstances, you will want to set <tt>maxusers</tt> to at least four, especially if - you are using X Windows or compiling software. The + you are using the X Window System or compiling software. The reason is that the most important table set by <tt>maxusers</tt> is the maximum number of processes, which is set to <bf><tt>20 + 16 * maxusers</tt></bf>, so if you set <tt>maxusers</tt> to one, then you can only have 36 simultaneous processes, including the 18 or so that the system starts up at boot time, and the 15 or so you will - probably create when you start X Windows. Even a + probably create when you start the X Window System. Even a simple task like reading a <tt>man</tt> page will start up nine processes to filter, decompress, and view it. Setting <tt>maxusers</tt> to 4 will allow you to have up to 84 simultaneous processes, which should be enough for anyone. If, however, you see the dreaded ``proc table full'' error when trying to start another program, or are running a server with a large number of simultaneous users (like Walnut Creek CDROM's FTP site), you can always increase this number and rebuild. <quote><em/Note:/ <tt>maxuser</tt> does <em>not</em> limit the number of users which can log into your machine. It simply sets various table sizes to reasonable values considering the maximum number of users you will likely have on your system and how many processes each of them will be running. One keyword which <em>does</em> limit the number of simultaneous <em>remote logins</em> is <ref id="kernelconfig:ptys" name="pseudo-device pty 16">.</quote> <tag>config <em>kernel_name</em> root on <em>root_device</em></tag> <p>This line specifies the location and name of the kernel. Traditionally the kernel is called <tt>vmunix</tt> but in FreeBSD, it is aptly named <tt>kernel</tt>. You should always use <tt>kernel</tt> for <em>kernel_name</em> because changing it will render numerous system utilities inoperative. The second part of the line specifies the disk and partition where the root filesystem and kernel can be found. Typically this will be <tt>wd0</tt> for systems with non-SCSI drives, or <tt>sd0</tt> for systems with SCSI drives. </descrip> <sect1><heading>General Options</heading> <p>These lines provide kernel support for various filesystems and other options. <descrip> <label id="kernelconfig:mathemu"> <tag>options MATH_EMULATE</tag> <p>This line allows the kernel to simulate a math co-processor if your computer does not have one (386 or 486SX). If you have a Pentium, a 486DX, or a 386 or 486SX with a separate 387 or 487 chip, you can comment this line out. <quote><em>Note:</em> The normal math co-processor emulation routines that come with FreeBSD are <em>not</em> very accurate. If you do not have a math co-processor, and you need the best accuracy, I recommend that you change this option to <tt>GPL_MATH_EMULATE</tt> to use the superior GNU math support, which is not included by default for licensing reasons.</quote> <tag>options ``COMPAT_43''</tag> <p>Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. <tag>options BOUNCE_BUFFERS</tag> <p>ISA devices and EISA devices operating in an ISA compatibility mode can only perform DMA (Direct Memory Access) to memory below 16 megabytes. This option enables such devices to work in systems with more than 16 megabytes of memory. <tag>options UCONSOLE</tag> <p>Allow users to grab the console, useful for X Windows. For example, you can create a console xterm by typing <tt>xterm -C</tt>, which will display any `write', `talk', and other messages you receive, as well as any console messages sent by the kernel. <tag>options SYSVSHM</tag> <p>This option provides for System V shared memory. The most common use of this is the XSHM extension in X Windows, which many graphics-intensive programs (such as the movie player XAnim, and Linux DOOM) will automatically take advantage of for extra - speed. If you use X Windows, you will definitely + speed. If you use the X Window System, you will definitely want to include this. <tag>options SYSVSEM</tag> <p>Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. <tag>options SYSVMSG</tag> <p>Support for System V messages. Again, only adds a few hundred bytes to the kernel. <quote><em/Note:/ The <tt>ipcs(1)</tt> command will tell will list any processes using using each of these System V facilities.</quote> </descrip> <sect1><heading>Filesystem Options</heading> <p>These options add support for various filesystems. You must include at least one of these to support the device you boot from; typically this will be <tt>FFS</tt> if you boot from a hard drive, or <tt>NFS</tt> if you are booting a diskless workstation from Ethernet. You can include other commonly-used filesystems in the kernel, but feel free to comment out support for filesystems you use less often (perhaps the MS-DOS filesystem?), since they will be dynamically loaded from the Loadable Kernel Module directory <tt>/lkm</tt> the first time you mount a partition of that type. <descrip> <tag>options FFS</tag> <p>The basic hard drive filesystem; leave it in if you boot from the hard disk. <tag>options NFS</tag> <p>Network Filesystem. Unless you plan to mount partitions from a Unix file server over Ethernet, you can comment this out. <tag>options MSDOSFS</tag> <p>MS-DOS Filesystem. Unless you plan to mount a DOS formatted hard drive partition at boot time, you can safely comment this out. It will be automatically loaded the first time you mount a DOS partition, as described above. Also, the excellent <tt>mtools</tt> software (in the ports collection) allows you to access DOS floppies without having to mount and unmount them (and does not require MSDOSFS at all). <tag>options ``CD9660''</tag> <p>ISO 9660 filesystem for CD-ROMs. Comment it out if you do not have a CD-ROM drive or only mount data CD's occasionally (since it will be dynamically loaded the first time you mount a data CD). Audio CD's do not need this filesystem. <tag>options PROCFS</tag> <p>Process filesystem. This is a pretend filesystem mounted on /proc which allows programs like <tt>ps(1)</tt> to give you more information on what processes are running. <tag>options MFS</tag> <p>Memory-mapped file system. This is basically a RAM disk for fast storage of temporary files, useful if you have a lot of swap space that you want to take advantage of. A perfect place to mount an MFS partition is on the <tt>/tmp</tt> directory, since many programs store temporary data here. To mount an MFS RAM disk on <tt>/tmp</tt>, add the following line to <tt>/etc/fstab</tt> and then reboot or type <tt>mount /tmp</tt>: <tscreen><verb> /dev/wd1s2b /tmp mfs rw 0 0 </verb></tscreen> <quote><em/Note:/ Replace the <tt>/dev/wd1s2b</tt> with the name of your swap partition, which will be listed in your <tt>/etc/fstab</tt> as follows: <tscreen><verb> /dev/wd1s2b none swap sw 0 0 </verb></tscreen> </quote> <quote><em/Note:/ <!-- MFS is currently a bit limited (for example, I noticed that two programs ca not access the <tt>/tmp</tt> device simultaneously). As such, you may want to avoid it for now. --> Also, the <tt>MFS</tt> filesystem can <em>not</em> be dynamically loaded, so you <em>must</em> compile it into your kernel if you want to experiment with it.</quote> <tag>options QUOTA</tag> <p>Enable disk quotas. If you have a public access system, and do not want users to be able to overflow the <tt>/home</tt> partition, you can establish disk quotas for each user. This code is a little buggy, so do not enable it unless you have to. View the manual page for <tt>quota(1)</tt> to learn more about disk quotas. </descrip> <sect1><heading>Basic Controllers and Devices</heading> <p>These sections describe the basic disk, tape, and CD-ROM controllers supported by FreeBSD. There are separate sections for <ref id="kernelconfig:scsi" name="SCSI"> controllers and <ref id="kernelconfig:network" name="network"> cards. <descrip> <tag>controller isa0</tag> <p>All PC's supported by FreeBSD have one of these. If you have an IBM PS/2 (Micro Channel Architecture), then you cannot run FreeBSD at this time. <tag>controller pci0</tag> <p>Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to the ISA bus. <tag>controller fdc0</tag> <p>Floppy drive controller: <tt>fd0</tt> is the ``A:'' floppy drive, and <tt>fd1</tt> is the ``B:'' drive. <tt>ft0</tt> is a QIC-80 tape drive attached to the floppy controller. Comment out any lines corresponding to devices you do not have. <quote><em/Note:/ QIC-80 tape support requires a separate filter program called <tt>ft(8)</tt>, see the manual page for details.</quote> <tag>controller wdc0</tag> <p>This is the primary IDE controller. <tt>wd0</tt> and <tt>wd1</tt> are the master and slave hard drive, respectively. <tt>wdc1</tt> is a secondary IDE controller where you might have a third or fourth hard drive, or an IDE CD-ROM. Comment out the lines which do not apply (if you have a SCSI hard drive, you will probably want to comment out all six lines, for example). <tag>controller wcd0<label id="kernelconfig:atapi"></tag> <p>This device provides IDE CD-ROM support. Be sure to leave <tt>wdc1</tt> uncommented if your CD-ROM is on its own controller card. To use this, you must also include the line <tt>options ATAPI</tt>. <tag>device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr</tag> <p><tt>npx0</tt> is the interface to the floating point math unit in FreeBSD, either the hardware co-processor or the software math emulator. It is <em/NOT/ optional. <tag>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr</tag> <p>Wangtek and Archive QIC-02/QIC-36 tape drive support <tag>Proprietary CD-ROM support</tag> <p>The following drivers are for the so-called <em>proprietary</em> CD-ROM drives. These drives have their own controller card or might plug into a sound card such as the SoundBlaster 16. They are <em>not</em> IDE or SCSI. Most older single-speed and double-speed CD-ROMs use these interfaces, while newer quad-speeds are likely to be <ref id="kernelconfig:atapi" name="IDE"> or <ref id="kernelconfig:scsi" name="SCSI">. <descrip> <tag>device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr</tag> <p>Mitsumi CD-ROM (LU002, LU005, FX001D). <tag>device scd0 at isa? port 0x230 bio</tag> <p>Sony CD-ROM (CDU31, CDU33A). <tag>controller matcd0 at isa? port ? bio</tag> <p>Matsushita/Panasonic CD-ROM (sold by Creative Labs for SoundBlaster). </descrip> </descrip> <sect1><heading>SCSI Device Support<label id="kernelconfig:scsi"></heading> <p>This section describes the various SCSI controllers and devices supported by FreeBSD. <descrip> <tag>SCSI Controllers</tag> <p>The next ten or so lines include support for different kinds of SCSI controllers. Comment out all except for the one(s) you have: <descrip> <tag>controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr</tag> <p>Most Buslogic controllers <tag>controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr</tag> <p>UltraStor 14F and 34F <tag>controller ahc0</tag> <p>Adaptec 274x/284x/294x <tag>controller ahb0 at isa? bio irq ? vector ahbintr</tag> <p>Adaptec 174x <tag>controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr</tag> <p>Adaptec 154x <tag>controller aic0 at isa? port 0x340 bio irq 11 vector aicintr </tag> <p>Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!) <tag>controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr </tag> <p>ProAudioSpectrum cards using NCR 5380 or Trantor T130 <tag>controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr</tag> <p>Seagate ST01/02 8 bit controller (slow!) <tag>controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr</tag> <p>Western Digital WD7000 controller <tag>controller ncr0</tag> <p>NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI controller </descrip> <tag>options ``SCSI_DELAY=15''</tag> <p>This causes the kernel to pause 15 seconds before probing each SCSI device in your system. If you only have IDE hard drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to 5 seconds, to speed up booting. Of course if you do this, and FreeBSD has trouble recognizing your SCSI devices, you will have to raise it back up. <tag>controller scbus0</tag> <p>If you have any SCSI controllers, this line provides generic SCSI support. If you do not have SCSI, you can comment this, and the following three lines, out. <tag>device sd0</tag> <p>Support for SCSI hard drives. <tag>device st0</tag> <p>Support for SCSI tape drives. <tag>device cd0</tag> <p>Support for SCSI CD-ROM drives. <p>Note that the number <bf>0</bf> in the above entries is slightly misleading: all these devices are automatically configured as they are found, regardless of how many of them are hooked up to the SCSI bus(es), and which target IDs they have. If you want to ``wire down'' specific target IDs to particular devices, refer to the appropriate section of the LINT kernel config file. </descrip> <sect1><heading>Console, Bus Mouse, and X Server Support</heading> <p>You must choose one of these two console types, and, if you plan - to use X Windows, enable the XSERVER option and optionally, a bus + to use the X Window System, enable the XSERVER option and optionally, a bus mouse or PS/2 mouse device. <descrip> <tag>device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr</tag> <p><tt>sc0</tt> is the default console driver, which resembles an SCO console. Since most full-screen programs access the console through a terminal database library like <em>termcap</em>, it should not matter much whether you use this or <tt>vt0</tt>, the VT220 compatible console driver. When you log in, set your TERM variable to ``scoansi'' if full-screen programs have trouble running under this console. <tag>device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint</tag> <p>This is a VT220-compatible console driver, backwards compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with <tt>sc0</tt>. Also, set your TERM variable to ``vt100'' or ``vt220'' when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where the <em>termcap</em> or <em>terminfo</em> entries for the <tt>sc0</tt> device are often not available -- ``vt100'' should be available on virtually any platform. <descrip> <tag>options ``PCVT_FREEBSD=210''</tag> <p>Required with the <tt>vt0</tt> console driver. <tag>options XSERVER</tag> <p>This includes code required to run the <tt>XFree86</tt> X Window Server. </descrip> <tag>device mse0 at isa? port 0x23c tty irq 5 vector ms</tag> <p>Use this device if you have a Logitech or ATI InPort bus mouse card. <quote><em/Note:/ If you have a serial mouse, ignore these two lines, and instead, make sure the appropriate <ref id="kernelconfig:serial" name="serial"> port is enabled (probably COM1).</quote> <tag>device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr</tag> <p>Use this device if your mouse plugs into the PS/2 mouse port. </descrip> <sect1><heading>Serial and Parallel Ports</heading> <p>Nearly all systems have these. If you are attaching a printer to one of these ports, the <ref id="printing" name="Printing"> section of the handbook is very useful. If you are using modem, <ref id="dialup" name="Dialup access"> provides extensive detail on serial port configuration for use with such devices. <descrip> <tag>device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr<label id="kernelconfig:serial"></tag> <p><tt>sio0</tt> through <tt>sio3</tt> are the four serial ports referred to as COM1 through COM4 in the MS-DOS world. Note that if you have an internal modem on COM4 and a serial port at COM2 you will have to change the IRQ of the modem to 2 (for obscure technical reasons IRQ 2 = IRQ 9) in order to access it from FreeBSD. If you have a multiport serial card, check the manual page for <tt>sio(4)</tt> for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses of the form <tt>0x*2e8</tt>, and since many cheap serial cards do not fully decode the 16-bit IO address space, they clash with these cards, making the COM4 port practically unavailable. Each serial port is required to have a unique IRQ (unless you are using one of the multiport cards where shared interrupts are supported), so the default IRQs for COM3 and COM4 cannot be used. <tag>device lpt0 at isa? port? tty irq 7 vector lptintr</tag> <p><tt>lpt0</tt> through <tt>lpt2</tt> are the three printer ports you could conceivably have. Most people just have one, though, so feel free to comment out the other two lines if you do not have them. </descrip> <sect1><heading>Networking<label id="kernelconfig:network"></heading> <p>FreeBSD, as with Unix in general, places a <em>big</em> emphasis on networking. Therefore, even if you do not have an Ethernet card, pay attention to the mandatory options and the dial-up networking support. <descrip> <tag>options INET</tag> Networking support. Leave it in even if you do not plan to be connected to a network. Most programs require at least loopback networking (i.e. making network connections within your PC) so this is essentially mandatory. <tag>Ethernet cards</tag> <p>The next lines enable support for various Ethernet cards. If you do not have a network card, you can comment out all of these lines. Otherwise, you will want to leave in support for your particular Ethernet card(s): <descrip> <tag>device de0</tag> <p>Ethernet adapters based on Digital Equipment DC21040, DC21041 or DC21140 chips <tag>device fxp0</tag> <p>Intel EtherExpress Pro/100B <tag>device vx0</tag> <p>3Com 3C590 and 3C595 (buggy) <tag>device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr</tag> <p>Cronyx/Sigma multiport sync/async (with Cisco or PPP framing) <tag>device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr</tag> <p>Western Digital and SMC 80xx and 8216; Novell NE1000 and NE2000; 3Com 3C503 <tag>device el0 at isa? port 0x300 net irq 9 vector elintr</tag> <p>3Com 3C501 (slow!) <tag>device eg0 at isa? port 0x310 net irq 5 vector egintr</tag> <p>3Com 3C505 <tag>device ep0 at isa? port 0x300 net irq 10 vector epintr</tag> <p>3Com 3C509 (buggy) <tag>device fe0 at isa? port 0x240 net irq ? vector feintr</tag> <p>Fujitsu MB86960A/MB86965A Ethernet <tag>device fea0 at isa? net irq ? vector feaintr</tag> <p>DEC DEFEA EISA FDDI adapter <tag>device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr</tag> <p>AT&T StarLAN 10 and EN100; 3Com 3C507; unknown NI5210 <tag>device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr</tag> <p>Intel EtherExpress 16 <tag>device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr</tag> <p>Digital Equipment EtherWorks 2 and EtherWorks 3 (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, DE205, DE422) <tag>device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr</tag> <p>Lance/PCnet cards (Isolan, Novell NE2100, NE32-VL) <tag>device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr</tag> <p>IBM/National Semiconductor PCMCIA ethernet controller. <tag>device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr</tag> <p>3Com PCMCIA Etherlink III </descrip> <quote><em/Note:/ With certain cards (notably the NE2000) you will have to change the port and/or IRQ since there is no ``standard'' location for these cards.</quote> <tag>pseudo-device loop</tag> <p><tt>loop</tt> is the generic loopback device for TCP/IP. If you telnet or FTP to <em>localhost</em> (a.k.a. <tt>127.0.0.1</tt>) it will come back at you through this pseudo-device. Mandatory. <tag>pseudo-device ether</tag> <p><tt>ether</tt> is only needed if you have an Ethernet card and includes generic Ethernet protocol code. <tag>pseudo-device sl <em>number</em></tag> <p><tt>sl</tt> is for SLIP (Serial Line Internet Protocol) support. This has been almost entirely supplanted by PPP, which is easier to set up, better suited for modem-to-modem connections, as well as more powerful. The <em>number</em> after <tt>sl</tt> specifies how many simultaneous SLIP sessions to support. This handbook has more information on setting up a SLIP <ref id="slipc" name="client"> or <ref id="slips" name="server">. <tag>pseudo-device ppp <em>number</em></tag> <p><tt>ppp</tt> is for kernel-mode PPP (Point-to-Point Protocol) support for dial-up Internet connections. There is also version of PPP implemented as a user application that uses the <tt>tun</tt> and offers more flexibility and features such as demand dialing. If you still want to use this PPP driver, read the <ref id="ppp" name="kernel-mode PPP"> section of the handbook. As with the <tt>sl</tt> device, <em>number</em> specifies how many simultaneous PPP connections to support. <tag>pseudo-device tun <em>number</em></tag> <p><tt>tun</tt> is used by the user-mode PPP software. This program is easy to set up and very fast. It also has special features such as automatic dial-on-demand. The number after <tt>tun</tt> specifies the number of simultaneous PPP sessions to support. See the <ref id="userppp" name="user-mode PPP"> section of the handbook for more information. <tag>pseudo-device bpfilter <em>number</em></tag> <p>Berkeley packet filter. This pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network (e.g. an ethernet). These packets can be captured to disk and/or examined with the <tt>tcpdump(1)</tt> program. Note that implementation of this capability can seriously compromise your overall network security. The <em>number</em> after bpfilter is the number of interfaces that can be examined simultaneously. Optional, not recommended except for those who are fully aware of the potential pitfalls. Not all network cards support this capability. </descrip> <sect1><heading>Sound cards</heading> <p>This is the first section containing lines that are not in the GENERIC kernel. To include sound card support, you will have to copy the appropriate lines from the LINT kernel (which contains support for <em>every</em> device) as follows: <descrip> <tag>controller snd0</tag> <p>Generic sound driver code. Required for all of the following sound cards except <tt>pca</tt>. <tag>device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr</tag> <p>ProAudioSpectrum digital audio and MIDI. <tag>device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr</tag> <p>SoundBlaster digital audio. <quote><em/Note:/ If your SoundBlaster is on a different IRQ (such as 5), change <tt>irq 7</tt> to, for example, <tt>irq 5</tt> and remove the <tt>conflicts</tt> keyword. Also, you must add the line: <tt>options ``SBC_IRQ=5''</tt></quote> <tag>device sbxvi0 at isa? drq 5</tag> <p>SoundBlaster 16 digital 16-bit audio. <quote><em/Note:/ If your SB16 is on a different 16-bit DMA channel (such as 6 or 7), change the <tt>drq 5</tt> keyword appropriately, and then add the line: <tt>options "SB16_DMA=6"</tt></quote> <tag>device sbmidi0 at isa? port 0x330</tag> <p>SoundBlaster 16 MIDI interface. If you have a SoundBlaster 16, you must include this line, or the kernel will not compile. <tag>device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr</tag> <p>Gravis Ultrasound. <tag>device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr</tag> <p>Microsoft Sound System. <tag>device opl0 at isa? port 0x388 conflicts</tag> <p>AdLib FM-synthesis audio. Include this line for AdLib, SoundBlaster, and ProAudioSpectrum users, if you want to play MIDI songs with a program such as <tt>playmidi</tt> (in the ports collection). <tag>device mpu0 at isa? port 0x330 irq 6 drq 0</tag> <p>Roland MPU-401 stand-alone card. <tag>device uart0 at isa? port 0x330 irq 5 vector ``m6850intr''</tag> <p>Stand-alone 6850 UART for MIDI. <tag>device pca0 at isa? port ``IO_TIMER1'' tty<label id="kernelconfig:pcaudio"></tag> <p>Digital audio through PC speaker. This is going to be very poor sound quality and quite CPU-intensive, so you have been warned (but it does not require a sound card). </descrip> <quote><em/Note:/ There is some additional documentation in <tt>/usr/src/sys/i386/isa/sound/sound.doc</tt>. Also, if you add any of these devices, be sure to create the sound <ref id="kernelconfig:nodes" name="device nodes">.</quote> <sect1><heading>Pseudo-devices</heading> <p>Pseudo-device drivers are parts of the kernel that act like device drivers but do not correspond to any actual hardware in the machine. The <ref id="kernelconfig:network" name="network-related"> pseudo-devices are in that section, while the remainder are here. <descrip> <tag>pseudo-device gzip</tag> <p><tt>gzip</tt> allows you to run FreeBSD programs that have been compressed with <tt>gzip</tt>. The programs in <tt>/stand</tt> are compressed so it is a good idea to have this option in your kernel.</p> <tag>pseudo-device log</tag> <p><tt>log</tt> is used for logging of kernel error messages. Mandatory. <tag>pseudo-device pty <em>number</em><label id="kernelconfig:ptys"></tag> <p><tt>pty</tt> is a ``pseudo-terminal'' or simulated login port. It is used by incoming <bf>telnet</bf> and <bf>rlogin</bf> sessions, xterm, and some other applications such as emacs. The <em>number</em> indicates the number of <tt>pty</tt>s to create. If you need more than GENERIC default of 16 simultaneous xterm windows and/or remote logins, be sure to increase this number accordingly, up to a maximum of 64. <tag>pseudo-device snp <em>number</em></tag> <p>Snoop device. This pseudo-device allows one terminal session to watch another using the <tt>watch(8)</tt> command. Note that implementation of this capability has important security and privacy implications. The <em>number</em> after snp is the total number of simultaneous snoop sessions. Optional. <tag>pseudo-device vn</tag> <p>Vnode driver. Allows a file to be treated as a device after being set up with the <tt>vnconfig(8)</tt> command. This driver can be useful for manipulating floppy disk images and using a file as a swap device (e.g. an MS Windows swap file). Optional. <tag>pseudo-device ccd <em>number</em></tag> <p>Concatenated disks. This pseudo-device allows you to concatenate multiple disk partitions into one large ``meta''-disk. The <em>number</em> after ccd is the total number of concatenated disks (not total number of disks that can be concatenated) that can be created. (See <tt>ccd(4)</tt> and <tt>ccdconfig(8)</tt> man pages for more details.) Optional. </descrip> <sect1><heading>Joystick, PC Speaker, Miscellaneous</heading> <p>This section describes some miscellaneous hardware devices supported by FreeBSD. Note that none of these lines are included in the GENERIC kernel, you will have to copy them from this handbook or the LINT kernel (which contains support for <em>every</em> device): <descrip> <tag>device joy0 at isa? port ``IO_GAME''</tag> <p>PC joystick device. <tag>pseudo-device speaker</tag> <p>Supports IBM BASIC-style noises through the PC speaker. Some fun programs which use this are <tt>/usr/sbin/spkrtest</tt>, which is a shell script that plays some simple songs, and <tt>/usr/games/piano</tt> which lets you play songs using the keyboard as a simple piano (this file only exists if you have installed the <em>games</em> package). Also, the excellent text role-playing game NetHack (in the ports collection) can be configured to use this device to play songs when you play musical instruments in the game. <p>See also the <ref id="kernelconfig:pcaudio" name="pca0"> device. </descrip> <sect><heading>Making Device Nodes<label id="kernelconfig:nodes"></heading> <p>Almost every device in the kernel has a corresponding ``node'' entry in the <tt>/dev</tt> directory. These nodes look like regular files, but are actually special entries into the kernel which programs use to access the device. The shell script <tt>/dev/MAKEDEV</tt>, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create <em>all</em> of them, so when you add support for a new device, it pays to make sure that the appropriate entries are in this directory, and if not, add them. Here is a simple example: Suppose you add the IDE CD-ROM support to the kernel. The line to add is: <tscreen><verb> controller wcd0 </verb></tscreen> This means that you should look for some entries that start with <tt>wcd0</tt> in the <tt>/dev</tt> directory, possibly followed by a letter, such as `c', or preceded by the letter 'r', which means a `raw' device. It turns out that those files are not there, so I must change to the <tt>/dev</tt> directory and type: <tscreen><verb> # sh MAKEDEV wcd0 </verb></tscreen> When this script finishes, you will find that there are now <tt>wcd0c</tt> and <tt>rwcd0c</tt> entries in <tt>/dev</tt> so you know that it executed correctly. For sound cards, the command: <tscreen><verb> # sh MAKEDEV snd0 </verb></tscreen> creates the appropriate entries. Follow this simple procedure for any other non-GENERIC devices which do not have entries. <quote><em/Note:/ All SCSI controllers use the same set of <tt>/dev</tt> entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in <tt>/dev</tt> at all, so you do not have to worry about these either.</quote> <sect><heading>If Something Goes Wrong<label id="kernelconfig:trouble"></heading> <p>There are four categories of trouble that can occur when building a custom kernel. They are: <descrip> <tag>Config command fails</tag> <p>If the <tt>config</tt> command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, <tt>config</tt> will print the line number that it had trouble with, so you can quickly skip to it with <tt>vi</tt>. For example, if you see: <tscreen><verb> config: line 17: syntax error </verb></tscreen> you can skip to the problem in <tt>vi</tt> by typing ``17G'' in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. <tag>Make command fails</tag> <p>If the <tt>make</tt> command fails, it usually signals an error in your kernel description, but not severe enough for <tt>config</tt> to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to the &a.questions with your kernel configuration, and it should be diagnosed very quickly. <tag>Kernel will not boot<label id="kernelconfig:noboot"></tag> <p>If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, BSD has an excellent mechanism for recovering from incompatible kernels. Simply type the name of the kernel you want to boot from (i.e. ``kernel.old'') at the FreeBSD boot prompt instead of pressing return. When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand. After booting with a good kernel you can check over your configuration file and try to build it again. One helpful resource is the <tt>/var/log/messages</tt> file which records, among other things, all of the kernel messages from every successful boot. Also, the <tt>dmesg(8)</tt> command will print the kernel messages from the current boot. <quote><em/Note:/ If you are having trouble building a kernel, make sure to keep a GENERIC, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on <tt>kernel.old</tt> because when installing a new kernel, <tt>kernel.old</tt> is overwritten with the last installed kernel which may be non-functional. Also, as soon as possible, move the working kernel to the proper ``kernel'' location or commands such as <tt>ps(1)</tt> will not work properly. The proper command to ``unlock'' the kernel file that <tt>make</tt> installs (in order to move another kernel back permanently) is: <tscreen><verb> # chflags noschg /kernel </verb></tscreen> And, if you want to ``lock'' your new kernel into place, or any file for that matter, so that it cannot be moved or tampered with: <tscreen><verb> # chflags schg /kernel </verb></tscreen> </quote> <tag>Kernel works, but <tt>ps</tt> does not work any more!</tag> <p>If you have installed a different version of the kernel from the one that the system utilities have been built with, for example, an experimental ``2.2.0'' kernel on a 2.1.0-RELEASE system, many system-status commands like <tt>ps(1)</tt> and <tt>vmstat(8)</tt> will not work any more. You must recompile the <tt>libkvm</tt> library as well as these utilities. This is one reason it is not normally a good idea to use a different version of the kernel from the rest of the operating system. </descrip> diff --git a/handbook/linuxemu.sgml b/handbook/linuxemu.sgml index b4ec73d386..30b05a2441 100644 --- a/handbook/linuxemu.sgml +++ b/handbook/linuxemu.sgml @@ -1,700 +1,700 @@ -<!-- $Id: linuxemu.sgml,v 1.10 1996-08-21 07:28:52 asami Exp $ --> +<!-- $Id: linuxemu.sgml,v 1.11 1996-08-28 00:43:59 asami Exp $ --> <!-- The FreeBSD Documentation Project --> <chapt><heading>Linux Emulation<label id="linuxemu"></heading> <p><em>Contributed by &a.brian and &a.rich;</em> <sect><heading>How to install the Linux emulator</heading> <p>Linux emulation in FreeBSD has reached a point where it is possible to run a large fraction of Linux binaries in both a.out and ELF format. The linux emulation in the -STABLE branch is capable of running Linux DOOM and Mathematica; the version present in FreeBSD-CURRENT is vastly more capable and runs all these as well as Quake, Abuse, IDL, netrek for Linux and a whole host of other programs. There are some Linux-specific operating system features that are not supported on FreeBSD. Linux binaries will not work on FreeBSD if they use the Linux /proc filesystem (which is different from the optional FreeBSD /proc filesystem) or i386-specific calls, such as enabling virtual 8086 mode. <p>To tell whether your kernel is configured for Linux compatibility simply run any Linux binary. If it prints the error message <tscreen> <verb> linux-executable: Exec format error. Wrong Architecture. </verb> </tscreen> then you do not have linux compatibility support and you need to configure and install a new kernel. Depending on which version of FreeBSD you are running, how you get Linux-emulation up will vary slightly: <sect1><heading>Installing Linux Emulation in 2.1-STABLE</heading> <p>The GENERIC kernel in 2.1-stable is not configured for linux compatibility so you you must reconfigure your kernel for it. There are two ways to do this: 1. linking the emulator statically in the kernel itself and 2. configuring your kernel to dynamically load the linux loadable kernel module (LKM). <p>To enable the emulator, add the following to your configuration file (c.f. /sys/i386/conf/LINT): <tscreen> <verb> options COMPAT_LINUX </verb> </tscreen> If you want to run doom or other applications that need shared memory also add the following. <tscreen> <verb> options SYSVSHM </verb> </tscreen> The linux system calls require 4.3BSD system call compatibility. So make sure you have the following. <tscreen> <verb> options "COMPAT_43" </verb> </tscreen> If you prefer to statically link the emulator in the kernel rather than use the loadable kernel module (LKM), then add <tscreen> <verb> options LINUX </verb> </tscreen> Then run config and install the new kernel as described in the <ref id="kernelconfig" name="kernel configuration"> section. If you decide to use the LKM you must also install the loadable module. A mismatch of versions between the kernel and loadable module can cause the kernel to crash, so the safest thing to do is to reinstall the LKM when you install the kernel. <tscreen> <verb> % cd /usr/src/lkm/linux % make all install </verb> </tscreen> Once you have installed the kernel and the LKM, you can invoke `linux' as root to load the LKM. <tscreen> <verb> % linux Linux emulator installed Module loaded as ID 0 % </verb> </tscreen> To see whether the LKM is loaded, run `modstat'. <tscreen> <verb> % modstat Type Id Off Loadaddr Size Info Rev Module Name EXEC 0 3 f0baf000 0018 f0bb4000 1 linux_emulator % </verb> </tscreen> You can cause the LKM to be loaded when the system boots in either of two ways. On FreeBSD-CURRENT and FreeBSD-STABLE enable it in /etc/sysconfig <tscreen> <verb> linux=YES </verb> </tscreen> by changing it from NO to YES. FreeBSD 2.1 RELEASE and earlier do not have such a line and on those you will need to edit /etc/rc.local to add the following line. <tscreen> <verb> linux </verb> </tscreen> <sect1><heading>Installing Linux Emulation in 2.2-CURRENT</heading> <p>In -current it is no longer necessary to specify ``options LINUX'' or ``options COMPAT_LINUX''. Linux emulation is done with an LKM (``Loadable Kernel Module'') so it can be installed on the fly without having to reboot. You will need the following things in your startup files, however: <enum> <item> In /etc/sysconfig, you need the following line: <tscreen> <verb> linux=YES </verb> </tscreen> <item> This, in turn, triggers the following action in /etc/rc.i386: <tscreen> <verb> # Start the Linux binary emulation if requested. if [ "X${linux}" = X"YES" ]; then echo -n ' '; linux # XXX BOGUS - Linux script shouldn't make any output on success fi </verb> </tscreen> </enum> <p>If you want to verify it is running, modstat will do that: <tscreen> <verb> % modstat Type Id Off Loadaddr Size Info Rev Module Name EXEC 0 4 f09e6000 001c f09ec010 1 linux_mod % </verb> </tscreen> However, there have been reports that this fails on some FreeBSD-current systems. If for some reason you cannot load the linux LKM, then statically link the emulator in the kernel by adding <tscreen> <verb> options LINUX </verb> </tscreen> to your kernel config file. Then run config and install the new kernel as described in the <ref id="kernelconfig" name="kernel configuration"> section. <sect1><heading>Installing Linux Runtime Libraries</heading> <sect2><heading>Installing using the linux_lib port</heading> <p>Most linux applications use shared libraries, so you are still not done until you install the shared libraries. It is possible to do this by hand, however, it is vastly simpler to just grab the linux_lib port: <tscreen> <verb> % cd /usr/ports-current/emulators/linux_lib % make all install </verb> </tscreen> and you should have a working linux emulator. Legend (and the mail archives :-) seems to hold that Linux emulation works best with linux binaries linked against the ZMAGIC libraries; QMAGIC libraries (such as those used in Slackware V2.0) may tend to give the Linuxulator heartburn. As of this writing (March 1996) ELF emulation is still in the formulative stages but seems to work pretty well. Also, expect some programs to complain about incorrect minor versions. In general this does not seem to be a problem. <sect2><heading>Installing libraries manually</heading> <p>If you don't have the ``ports'' distribution, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a "shadow root" directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist then it will try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. FreeBSD-current works slightly differently with respect to /compat/linux. On -current, all files, not just libraries, are searched for from the ``shadow root'' /compat/linux. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. <sect2><heading>How to install additional shared libraries</heading> <p>What if you install the linux_lib port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions: you will need to be root on your FreeBSD system to do the necessary installation steps). <p>If you have access to a Linux system, see what shared libraries it needs, and copy them to your FreeBSD system. Example: you have just ftp'ed the Linux binary of Doom. Put it on the Linux system you have access to, and check which shared libraries it needs by running `ldd linuxxdoom': <tscreen> <verb> % ldd linuxxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 </verb> </tscreen> <p>You would need go get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: <tscreen> <verb> /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29 </verb> </tscreen> <p>Note that if you already have a Linux shared library with a matching major revision number to the first column of the 'ldd' output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: <tscreen> <verb> /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 </verb> </tscreen> and you find a new binary that claims to require a later version according to the output of ldd: <tscreen> <verb> libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 </verb> </tscreen> If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like you can decide to replace the libc.so anyway, and that should leave you with: <tscreen> <verb> /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29 </verb> </tscreen> <p>Please note that the symbolic link mechanism is <em>only</em> needed for Linux binaries, the FreeBSD runtime linker takes care of looking for matching major revision numbers itself, you do not need to worry about that. <sect2><heading>Configuring the ld.so -- for FreeBSD-current only</heading> <p>This section applies only to FreeBSD-current only. Those running FreeBSD-stable should skip this section. <p>Finally, if you run FreeBSD-current you must make sure that you have the Linux runtime linker and its config files on your system. You should copy these files from the Linux system to their appropriate place on your FreeBSD system (to the /compat/linux tree): <tscreen> <verb> /compat/linux/lib/ld.so /compat/linux/etc/ld.so.config </verb> </tscreen> <p>If you do not have access to a Linux system, you should get the extra files you need from various ftp sites. Information on where to look for the various files is appended below. For now, let us assume you know where to get the files. <p> Retrieve the following files (all from the same ftp site to avoid any version mismatches), and install them under /compat/linux (i.e. /foo/bar is installed as /compat/linux/foo/bar): <tscreen> <verb> /sbin/ldconfig /usr/bin/ldd /lib/libc.so.x.y.z /lib/ld.so </verb> </tscreen> <p>ldconfig and ldd do not necessarily need to be under /compat/linux, you can install them elsewhere in the system too. Just make sure they do not conflict with their FreeBSD counterparts. A good idea would be to install them in /usr/local/bin as ldconfig-linux and ldd-linux. <p> Create the file /compat/linux/etc/ld.so.conf, containing the directories in which the Linux runtime linker should look for shared libs. It is a plain text file, containing a directory name on each line. /lib and /usr/lib are standard, you could add the following: <tscreen> <verb> /usr/X11/lib /usr/local/lib </verb> </tscreen> <p>When a linux binary opens a library such as /lib/libc.so the emulator maps the name to /compat/linux/lib/libc.so internally. All linux libraries should be installed under /compat/linux (e.g. /compat/linux/lib/libc.so, /compat/linux/usr/X11/lib/libX11.so, etc.) in order for the emulator to find them. <p>Those running FreeBSD-current should run the Linux ldconfig program. <tscreen> <verb> % cd /compat/linux/lib % /compat/linux/sbin/ldconfig </verb> </tscreen> <p>Ldconfig is statically linked, so it does not need any shared libraries to run. It creates the file /compat/linux/etc/ld.so.cache which contains the names of all the shared libraries. It should rerun to recreate this file whenever you install additional shared libraries. On FreeBSD-stable do not install /compat/linux/etc/ld.so.cache or run ldconfig becuase in FreeBSD-stable the syscalls are implemented differently and ldconfig is not needed or used. <p>You should now be set up for Linux binaries which only need a shared libc. You can test this by running the Linux ldd on itself. Suppose that you have it installed as ldd-linux, it should produce something like: <tscreen> <verb> % ldd-linux `which ldd-linux` libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 </verb> </tscreen> <p>This being done, you are ready to install new Linux binaries. Whenever you install a new Linux program, you should check if it needs shared libraries, and if so, whether you have them installed in the /compat/linux tree. To do this, you run the Linux version ldd on the new program, and watch its output. ldd (see also the manual page for ldd(1)) will print a list of shared libraries that the program depends on, in the form majorname (jumpversion) => fullname. <p>If it prints "not found" instead of fullname it means that you need an extra library. Which library this is, is shown in majorname, which will be of the form libXXXX.so.N You will need to find a libXXXX.so.N.mm on a Linux ftp site, and install it on your system. The XXXX (name) and N (major revision number) should match; the minor number(s) mm are less important, though it is advised to take the most recent version. <sect1><heading>Configuring the host name resolver</heading> <p>If DNS does not work or you get the messages <tscreen> <verb> resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword </verb> </tscreen> then you need to configure a /compat/linux/etc/host.conf file containing: <tscreen> <verb> order hosts, bind multi on </verb> </tscreen> where the order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove `bind,' if you have not configured a name-server using the /etc/resolv.conf file. <p>Lastly, those who run FreeBSD-stable need to set an the RESOLV_HOST_CONF environment variable so that applications will know how to search the host tables. If you run FreeBSD-current you can skip this. For the /bin/csh shell use: <tscreen> <verb> setenv RESOLV_HOST_CONF /compat/linux/etc/host.conf </verb> </tscreen> For /bin/sh use: <tscreen> <verb> RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF </verb> </tscreen> <sect1><heading>Finding the necessary files</heading> <p>Note: the information below is valid as of the time this document was written, but certain details such as names of ftp sites, directories and distribution names may have changed by the time you read this. <p>Linux is distributed by several groups that make their own set of binaries that they distribute. Each distribution has its own name, like ``Slackware'' or ``Yggdrasil''. The distributions are available on a lot of ftp sites. Sometimes the files are unpacked, and you can get the individual files you need, but mostly they are stored in distribution sets, usually consisting of subdirectories with gzipped tar files in them. The primary ftp sites for the distributions are: <verb> sunsite.unc.edu:/pub/Linux/distributions tsx-11.mit.edu:/pub/linux/distributions </verb> <p> Some European mirrors: <verb> ftp.luth.se:/pub/linux/distributions ftp.demon.co.uk:/pub/linux/distributions src.doc.ic.ac.uk:/packages/linux/distributions </verb> <p>For simplicity, let us concentrate on Slackware here. This distribution consists of a number of subdirectories, containing separate packages. Normally, they are controlled by an install program, but you can retrieve files "by hand" too. First of all, you will need to look in the "contents" subdir of the distribution. You will find a lot of small text files here describing the contents of the separate packages. The fastest way to look something up is to retrieve all the files in the contents subdirectory, and grep through them for the file you need. Here is an example of a list of files that you might need, and in which contents-file you will find it by grepping through them: <tabular ca=ll> Library <colsep>Package <rowsep> ld.so <colsep>ldso <rowsep> ldconfig <colsep>ldso <rowsep> ldd <colsep>ldso <rowsep> libc.so.4 <colsep>shlibs <rowsep> libX11.so.6.0 <colsep>xf_lib <rowsep> libXt.so.6.0 <colsep>xf_lib <rowsep> libX11.so.3 <colsep>oldlibs <rowsep> libXt.so.3 <colsep>oldlibs <rowsep> </tabular> <p>So, in this case, you will need the packages ldso, shlibs, xf_lib and oldlibs. In each of the contents-files for these packages, look for a line saying ``PACKAGE LOCATION'', it will tell you on which `disk' the package is, in our case it will tell us in which subdirectory we need to look. For our example, we would find the following locations: <tabular ca=ll> Package <colsep>Location <rowsep> ldso <colsep>diska2 <rowsep> shlibs <colsep>diska2 <rowsep> oldlibs <colsep>diskx6 <rowsep> xf_lib <colsep>diskx9 <rowsep> </tabular> <p>The locations called ``diskXX'' refer to the ``slakware/XX'' subdirectories of the distribution, others may be found in the ``contrib'' subdirectory. In this case, we could now retrieve the packages we need by retrieving the following files (relative to the root of the Slackware distribution tree): <tscreen> <verb> slakware/a2/ldso.tgz slakware/a2/shlibs.tgz slakware/x6/oldlibs/tgz slakware/x9/xf_lib.tgz </verb> </tscreen> <p>Extract the files from these gzipped tarfiles in your /compat/linux directory (possibly omitting or afterwards removing files you don't need), and you are done. <p><bf>See also:</bf> <verb> ftp.freebsd.org:pub/FreeBSD/2.0.5-RELEASE/xperimnt/linux-emu/README /usr/src/sys/i386/ibcs2/README.iBCS2 </verb> <sect><heading>How to Install Mathematica on FreeBSD<label id="mathematica"></heading> <p><em>Contributed by &a.rich and &a.chuck</em> This document shows how to install the Linux binary distribution of Mathematica 2.2 on FreeBSD 2.1. <p>Mathematica supports Linux but not FreeBSD as it stands. So once you have configured your system for Linux compatibility you have most of what you need to run Mathematica. <p>For those who already have the student edition of Mathematica for DOS the cost of upgrading to the Linux version at the time this was written, March 1996, was $45.00. It can be ordered directly from Wolfram at (217) 398-6500 and paid for by credit card. <sect1><heading>Unpacking the Mathematica distribution</heading> <p>The binaries are currently distributed by Wolfram on CDROM. The CDROM has about a dozen tar files, each of which is a binary distribution for one of the supported architectures. The one for Linux is named LINUX.TAR. You can, for example, unpack this into /usr/local/Mathematica: <tscreen> <verb> % cd /usr/local % mkdir Mathematica % cd Mathematica % tar -xvf /cdrom/LINUX.TAR </verb> </tscreen> <sect1><heading>Obtaining your Mathematica Password</heading> <p>Before you can run Mathematica you will have to obtain a password from Wolfram that corresponds to your `machine ID.' <p>Once you have installed the linux compatibility runtime libraries and unpacked the mathematica you can obtain the `machine ID' by running the program `mathinfo' in the Install directory. <tscreen> <verb> % cd /usr/local/Mathematica/Install % mathinfo LINUX: 'ioctl' fd=5, typ=0x89(), num=0x27 not implemented richc.isdn.bcm.tmc.edu 9845-03452-90255 % </verb> </tscreen> So, for example, the `machine ID' of `richc' is `9845-03452-90255'. You can ignore the message about the ioctl that is not implemented. It won't prevent Mathematica from running in any way and you can safely ignore it, though you will see the message every time you run Mathematica. <p>When you register with Wolfram, either by email, phone or fax, you'll give them the 'machine ID' and they will respond with a corresponding password consisting of groups of numbers. You need to add them both along with the machine name and license number in your mathpass file. You can do this by invoking: <tscreen> <verb> % cd /usr/local/Mathematica/Install % math.install </verb> </tscreen> It will ask you to enter your license number and the Wolfram supplied password. If you get them mixed up or for some reason the math.install fails, That's OK, because you can simply edit the file 'mathpass' in this same directory to correct the info manually. <p>After getting past the password, math.install will ask you if you accept their canned install defaults, or if you want to use your own. If you are like us and distrust all install programs, you probably want to specify the actual directories. Beware. Although the math.install program asks you to specify directories, it won't create them for you, so you should perhaps have a second window open with another shell so that you can create them before you give them to the install program. Or, if it fails, you can create the directories and then restart the math.install program. The directories we chose to create beforehand and specify to math.install were: <tscreen> <verb> /usr/local/Mathematica/bin for binaries /usr/local/Mathematica/man/man1 for man pages /usr/local/Mathematica/lib/X11 for the XKeysymb file </verb> </tscreen> You can also tell it to use /tmp/math.record for the system record file, where it puts logs of sessions. After this math.install will continue on to unpacking things and placing everything where it should go. <p>The Mathematica Notebook feature is included separately, as the X Front End, and you have to install it separately. To get the X Front End stuff correctly installed, cd into the /usr/local/Mathematica/FrontEnd directory and executed the ./xfe.install shell script. You'll have to tell it where to put things, but you don't have to create any directories because it uses all the same directories that had been created for math.install. When it finished, there should be a new shell script in /usr/local/Mathematica/bin called "mathematica". <p>Lastly, you need to modify each of the shell scripts that Mathematica has installed. At the beginning of every shell script in /usr/local/Mathematica/bin add the following line: <tscreen> <verb> XKEYSYMDB=/usr/local/Mathematica/lib/X11/XKeysymDB; export XKEYSYMDB </verb> </tscreen> This tells Mathematica were to find it's own version of the key mapping file XKeysymDB. Without this you will get pages of error messages about missing key mappings. On FreeBSD-stable you need to add the following as well: <tscreen> <verb> RESOLV_HOST_CONF=/compat/linux/etc/host.conf; export RESOLV_HOST_CONF </verb> </tscreen> This tells Mathematica to use the linux version of host.conf. This file has a different syntax from FreeBSD's host.conf, so you'll get an error message about /etc/host.conf if you leave this out. <p>You might want to also modify your /etc/manpath.config file to read the new man directory, and you may need to edit your ~/.cshrc file to add /usr/local/Mathematica/bin to your path. <p>That's about all it takes, With this you should be able to type "mathematica" and get a really slick looking Mathematica Notebook screen up. Mathematica has included the Motif user interfaces, but it's compiled in statically, so you don't need the Motif libraries. Good luck doing this yourself! <sect1><heading>Bugs</heading> <p>The Notebook front end is known to hang sometimes when reading notebook files with an error messages similar to: <tscreen> <verb> File .../Untitled-1.mb appears to be broken for OMPR.257.0 </verb> </tscreen> We haven't found the cause for this, but it only affects the -Notebook's X window front end, not the mathematica engine itself. So +Notebook's X Window front end, not the mathematica engine itself. So the command line interface invoked by 'math' is unaffected by this bug. <sect1><heading>Acknowledgments</heading> <p>A well-deserved thanks should go to &a.sos; and &a.peter; who made linux emulation what it is today, and Michael Smith who drove these two guys like dogs to get it to the point where it runs Linux binaries better than linux! :-) diff --git a/handbook/term.sgml b/handbook/term.sgml index cab61024a1..48f18c65c1 100644 --- a/handbook/term.sgml +++ b/handbook/term.sgml @@ -1,539 +1,539 @@ <!-- This is an SGML document in the linuxdoc DTD describing hardwired terminals with FreeBSD. By Sean Kelly, (c) 1996. - $Id: term.sgml,v 1.1 1996-07-29 07:15:57 jkh Exp $ + $Id: term.sgml,v 1.2 1996-08-28 00:44:00 asami Exp $ The FreeBSD Documentation Project <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN"> <linuxdoc> <article> <title> Hardwired Terminals <author> Sean Kelly <tt/kelly@fsl.noaa.gov/ <date> 24 June 1996, (c) 1996 <abstract> This document describes using hardwired terminals attached to computers running FreeBSD. It describes how to set up the terminal hardware (including cabling), how to configure FreeBSD to provide login sessions to those terminals, and how to troubleshoot problems with terminals. </abstract> <toc> --> <sect><heading>Terminals<label id="term"></heading> <p><em>Contributed by &a.kelly;<newline>28 July 1996</em> Terminals provide a convenient and low-cost way to access the power of your FreeBSD system when you are not at the computer's console or on a connected network. This section describes how to use terminals with FreeBSD. <sect1><heading>Uses and Types of Terminals<label id="term:uses"></heading> <p>The original Unix systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and some terminal software to dial into a remote system to do text-only work. Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every Unix-style operating system today; FreeBSD is no exception. By using a terminal attached to a unused serial port, you can log in and run any text program that you would normally run on the console or in an - <tt/xterm/ window in the X window system. + <tt/xterm/ window in the X Window System. For the business user, you can attach many terminals to a FreeBSD system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh can be a terminal wired into a more powerful computer running FreeBSD. You can turn what might otherwise be a single-user computer into a powerful multiple user system. For FreeBSD, there are three kinds of terminals: <itemize> <item><ref name="Dumb terminals" id="term:dumb"> <item><ref name="PCs acting as terminals" id="term:pcs"> <item><ref name="X terminals" id="term:x"> </itemize> The remaining subsections describe each kind. <sect2><heading>Dumb Terminals<label id="term:dumb"></heading> <p>Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called ``dumb'' because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them that has all the power to run text editors, compilers, email, games, and so forth. There are hundreds of kinds of dumb terminals made by many manufacturers, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with FreeBSD. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features. Dumb terminals are popular in work environments where workers do not need access to graphic applications such as - those provided by the X window system. + those provided by the X Window System. <sect2><heading>PCs Acting As Terminals<label id="term:pcs"></heading> <p>If a <ref name="dumb terminal" id="term:dumb"> has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some <em/terminal emulation/ software to run on the computer. Such a configuration is popular in homes. For example, if your spouse is busy working on your FreeBSD system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the FreeBSD system. <sect2><heading>X Terminals<label id="term:x"></heading> <p>X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application. We introduce X terminals just for the sake of completeness. However, this chapter does <em/not/ cover setup, configuration, or use of X terminals. <sect1><heading>Cables and Ports<label id="term:cables-ports"></heading> <p>To connect a terminal to your FreeBSD system, you need the right kind of cable and a serial port to which to connect it. This section tells you what to do. If you are already familiar with your terminal and the cable it requires, skip to <ref name="Configuration" id="term:config">. <sect2><heading>Cables<label id="term:cables"></heading> <p>Because terminals use serial ports, you need to use serial---also known as RS-232C---cables to connect the terminal to the FreeBSD system. There are a couple of kinds of serial cables. Which one you'll use depends on the terminal you want to connect: <itemize> <item>If you are connecting a personal computer to act as a terminal, use a <ref name="null-modem" id="term:null"> cable. A null-modem cable connects two computers or terminals together. <item>If you have an actual terminal, your best source of information on what cable to use is the documentation that accompanied the terminal. If you do not have the documentation, then try a <ref name="null-modem" id="term:null"> cable. If that does not work, then try a <ref name="standard" id="term:std"> cable. </itemize> Also, the serial port on <em/both/ the terminal and your FreeBSD system must have connectors that will fit the cable you are using. <sect3><heading>Null-modem cables<label id="term:null"></heading> <p>A null-modem cable passes some signals straight through, like ``signal ground,'' but switches other signals. For example, the ``send data'' pin on one end goes to the ``receive data'' pin on the other end. If you like making your own cables, here is a table showing a recommended way to construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector. <tscreen><verb> Signal Pin# Pin# Signal TxD 2 ----------------------- 3 RxD RxD 3 ----------------------- 2 TxD DTR 20 ----------------------- 6 DSR DSR 6 ----------------------- 20 DTR SG 7 ----------------------- 7 SG DCD 8 ----------------------+ 4 RTS* *RTS 4 + + 5 CTS* *CTS 5 +---------------------- 8 DCD * Connect pins 4 to 5 internally in the connector hood, and then to pin 8 in the remote hood. </verb></tscreen> <sect3><heading>Standard RS-232C Cables<label id="term:std"></heading> <p>A standard serial cable passes all the RS-232C signals straight-through. That is, the ``send data'' pin on one end of the cable goes to the ``send data'' pin on the other end. This is the type of cable to connect a modem to your FreeBSD system, and the type of cable needed for some terminals. <sect2><heading>Ports<label id="term:ports"></heading> <p>Serial ports are the devices through which data is transferred between the FreeBSD host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in FreeBSD. <sect3><heading>Kinds of Ports<label id="term:portkinds"></heading> <p>Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the FreeBSD system. Most terminals will have DB25 ports. Personal computers, including PCs running FreeBSD, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports. See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works, too. <sect3><heading>Port Names<label id="term:portnames"></heading> <p>In FreeBSD, you access each serial port through an entry in the <tt>/dev</tt> directory. There are two different kinds of entries: <itemize> <item>Callin ports are named <tt>/dev/ttyd<it/X/</tt> where <it/X/ is the port number, starting from zero. Generally, you use the callin port for terminals. Callin ports require that the serial line assert the data carrier detect (DCD) signal to work. <item>Callout ports are named <tt>/dev/cuaa<it/X/</tt>. You usually do not use the callout port for terminals, just for modems. You may use the callout port if the serial cable or the terminal does not support the carrier detect signal. </itemize> See the sio(4) manual page for more information. If you have connected a terminal to the first serial port (COM1 in DOS parlance), then you want to use <tt>/dev/ttyd0</tt> to refer to the terminal. If it is on the second serial port (also known as COM2), it is <tt>/dev/ttyd1</tt>, and so forth. Note that you may have to configure your kernel to support each serial port, especially if you have a mutliport serial card. See <ref name="Configuring the FreeBSD Kernel" id="kernelconfig"> for more information. <sect1><heading>Configuration<label id="term:config"></heading> <p>This section describes what you need to configure on your FreeBSD system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected---and that you have connected it. In a nutshell, you need tell the <tt/init/ process, which is responsible for process control and initialization, to start a <tt/getty/ process, which is responsible for reading a login name and starting the <tt/login/ program. To do so, you have to edit the <tt>/etc/ttys</tt> file. First, use the <tt/su/ command to become root. Then, make the following changes to <tt>/etc/ttys</tt>: <enum> <item>Add an line to <tt>/etc/ttys</tt> for the entry in the <tt>/dev</tt> directory for the serial port if it is not already there. <item>Specify that <tt>/usr/libexec/getty</tt> be run on the port, and specify the appropriate <tt/getty/ type from the <tt>/etc/gettytab</tt> file. <item>Specify the default terminal type. <item>Set the port to ``on.'' <item>Specify whether the port should be ``secure.'' <item>Force <tt/init/ to reread the <tt>/etc/ttys</tt> file. </enum> As an optional step, you may wish to create a custom <tt/getty/ type for use in step 2 by making an entry in <tt>/etc/gettytab</tt>. This document does not explain how to do so; you are encouraged to see the gettytab(5) and the getty(8) manual pages for more information. The remaining sections detail how to do these steps. We will use a running example throughout these sections to illustrate what we need to do. In our example, we will connect two terminals to the system: a Wyse-50 and a old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). For more information on the <tt>/etc/ttys</tt> file, see the ttys(5) manual page. <sect2><heading>Adding an Entry to <tt>/etc/ttys</tt><label id="term:etcttys"></heading> <p>First, you need to add an entry to the <tt>/etc/ttys</tt> file, unless one is already there. The <tt>/etc/ttys</tt> file lists all of the ports on your FreeBSD system where you want to allow logins. For example, the first virtual console <tt>ttyv0</tt> has an entry in this file. You can log in on the console using this entry. This file contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's <tt>/dev</tt> entry without the <tt>/dev</tt> part. When you installed your FreeBSD system, the <tt>/etc/ttys</tt> file included entries for the first four serial ports: <tt/ttyd0/ through <tt/ttyd3/. If you are attaching a terminal on one of those ports, you do not need to add an entry. In our example, we attached a Wyse-50 to the second serial port, <tt/ttyd1/, which is already in the file. We need to add an entry for the 286 PC connected to the sixth serial port. Here is an excerpt of the <tt>/etc/ttys</tt> file after we add the new entry: <tscreen><verb> ttyd1 "/usr/libexec/getty std.9600" unknown off secure ttyd5 </verb></tscreen> <sect2><heading>Specifying the <tt/getty/ Type<label id="term:getty"></heading> <p>Next, we need to specify what program will be run to handle the logins on a terminal. For FreeBSD, the standard program to do that is <tt>/usr/libexec/getty</tt>. It is what provides the <tt>login:</tt> prompt. The program <tt/getty/ takes one (optional) parameter on its command line, the <em/<tt/getty/ type/. A <tt/getty/ type tells about characteristics on the terminal line, like bps rate and parity. The <tt/getty/ program reads these characteristics from the file <tt>/etc/gettytab</tt>. The file <tt>/etc/gettytab</tt> contains lots of entries for terminal lines both old and new. In almost all cases, the entries that start with the text <tt/std/ will work for hardwired terminals. These entries ignore parity. There is a <tt/std/ entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The manual page gettytab(5) provides more information. When setting the <tt/getty/ type in the <tt>/etc/ttys</tt> file, make sure that the communications settings on the terminal match. For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps. Here is the <tt>/etc/ttys</tt> file so far (showing just the two terminals in which we are interested): <tscreen><verb> ttyd1 "/usr/libexec/getty std.38400" unknown off secure ttyd5 "/usr/libexec/getty std.19200" </verb></tscreen> Note that the second field---where we specify what program to run---appears in quotes. This is important, otherwise the type argument to <tt/getty/ might be interpreted as the next field. <sect2><heading>Specifying the Default Terminal Type<label id="term:deftermtype"></heading> <p>The third field in the <tt>/etc/ttys</tt> file lists the default terminal type for the port. For dialup ports, you typically put <tt/unknown/ or <tt/dialup/ in this field because users may dial up with practically any kind of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type in this field. Users will usually use the <tt/tset/ program in their <tt/.login/ or <tt/.profile/ files to check the terminal type and prompt for one if necessary. By setting a terminal type in the <tt>/etc/ttys</tt> file, users can forego such prompting. To find out what terminal types FreeBSD supports, see the file <tt>/usr/share/misc/termcap</tt>. It lists about 600 terminal types. You can add more if you wish. See the termcap(5) manual page for information. In our example, the Wyse-50 is a Wyse-50 type of terminal (although it can emulate others, we will leave it in Wyse-50 mode). The 286 PC is running Procomm which will be set to emulate a VT-100. Here are the pertinent yet unfinished entries from the <tt>/etc/ttys</tt> file: <tscreen><verb> ttyd1 "/usr/libexec/getty std.38400" wy50 off secure ttyd5 "/usr/libexec/getty std.19200" vt100 </verb></tscreen> <sect2><heading>Enabling the Port<label id="term:enable"></heading> <p>The next field in <tt>/etc/ttys</tt>, the fourth field, tells whether to enable the port. Putting <tt/on/ here will have the <tt/init/ process start the program in the second field, <tt/getty/, which will prompt for a login. If you put <tt/off/ in the fourth field, there will be no <tt/getty/, and hence no logins on the port. So, naturally, you want an <tt/on/ in this field. Here again is the <tt>/etc/ttys</tt> file. We have turned each port <tt/on/. <tscreen><verb> ttyd1 "/usr/libexec/getty std.38400" wy50 on secure ttyd5 "/usr/libexec/getty std.19200" vt100 on </verb></tscreen> <sect2><heading>Specifying Secure Ports<label id="term:secure"></heading> <p>We have arrived at the last field (well, almost: there is an optional <tt/window/ specifier, but we will ignore that). The last field tells whether the port is secure. What does ``secure'' mean? It means that the root account (or any account with a user ID of 0) may login on the port. Insecure ports do not allow root to login. How do you use secure and insecure ports? By marking a port as insecure, the terminal to which it is connected will not allow root to login. People who know the root password to your FreeBSD system will first have to login using a regular user account. To gain superuser privileges, they will then have to use the <tt/su/ command. Because of this, you will have two records to help track down possible compromises of root privileges: both the login and the <tt/su/ command make records in the system log (and logins are also recorded in the <tt/wtmp/ file). By marking a port as secure, the terminal will allow root in. People who know the root password will just login as root. You will not have the potentially useful login and <tt/su/ command records. Which should you use? Just use ``insecure.'' Use ``insecure'' <em/even/ for terminals <em/not/ in public user areas or behind locked doors. It is quite easy to login and use <tt/su/ if you need superuser privileges. Here finally are the completed entries in the <tt>/etc/ttys</tt> file, with comments added to describe where the terminals are: <tscreen><verb> ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroom </verb></tscreen> <sect2><heading>Force <tt/init/ to Reread <tt>/etc/ttys</tt><label id="term:hup"></heading> <p>When you boot FreeBSD, the first process, <tt/init/, will read the <tt>/etc/ttys</tt> file and start the programs listed for each enabled port to prompt for logins. After you edit <tt>/etc/ttys</tt>, you do not want to have to reboot your system to get <tt/init/ to see the changes. So, <tt/init/ will reread <tt>/etc/ttys</tt> if it receives a SIGHUP (hangup) signal. So, after you have saved your changes to <tt>/etc/ttys</tt>, send SIGHUP to <tt/init/ by typing: <tscreen><verb> kill -HUP 1 </verb></tscreen> (The <tt/init/ process <em/always/ has process ID 1.) If everything is set up correctly, all cables are in place, and the terminals are powered up, you should see login prompts. Your terminals are ready for their first logins! <sect1><heading>Debugging your connection<label id="term:debug"></heading> <p>Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes. <descrip> <tag/No login prompt appears/ Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port. Make sure the cable is connected firmly to both the terminal and the FreeBSD computer. Make sure it is the right kind of cable. Make sure the terminal and FreeBSD agree on the bps rate and parity settings. If you have a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply. Make sure that a <tt/getty/ process is running and serving the terminal. Type <tscreen><verb> ps -axww|grep getty </verb></tscreen> to get a list of running <tt/getty/ processes. You should see an entry for the terminal. For example, the display <tscreen><verb> 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1 </verb></tscreen> shows that a <tt/getty/ is running on the second serial port <tt/ttyd1/ and is using the <tt/std.38400/ entry in <tt>/etc/gettytab</tt>. If no <tt/getty/ process is running, make sure you have enabled the port in <tt>/etc/ttys</tt>. Make sure you have run <tt/kill -HUP 1/. <tag/Garbage appears instead of a login prompt/ Make sure the terminal and FreeBSD agree on the bps rate and parity settings. Check the getty processes to make sure the correct <tt/getty/ type is in use. If not, edit <tt>/etc/ttys</tt> and run <tt/kill -HUP 1/. <tag/Characters appear doubled; the password appears when typed/ Switch the terminal (or the terminal emulation software) from ``half duplex'' or ``local echo'' to ``full duplex.'' </descrip>