Index: head/share/doc/handbook/Makefile =================================================================== --- head/share/doc/handbook/Makefile (revision 17325) +++ head/share/doc/handbook/Makefile (revision 17326) @@ -1,16 +1,16 @@ -# $Id: Makefile,v 1.14 1996/06/30 18:01:23 phk Exp $ +# $Id: Makefile,v 1.15 1996/07/02 23:16:14 wosch Exp $ SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml SRCS+= cyclades.sgml dialup.sgml SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml SRCS+= firewalls.sgml glossary.sgml goals.sgml SRCS+= handbook.sgml history.sgml hw.sgml install.sgml isdn.sgml kerberos.sgml SRCS+= kernelconfig.sgml kerneldebug.sgml memoryuse.sgml SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml quotas.sgml relnotes.sgml -SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml -SRCS+= skey.sgml slipc.sgml slips.sgml stable.sgml submitters.sgml sup.sgml -SRCS+= synching.sgml troubleshooting.sgml userppp.sgml uart.sgml linuxemu.sgml +SRCS+= routing.sgml scsi.sgml sections.sgml sio.sgml skey.sgml slipc.sgml +SRCS+= slips.sgml stable.sgml submitters.sgml sup.sgml synching.sgml +SRCS+= term.sgml troubleshooting.sgml userppp.sgml uart.sgml linuxemu.sgml .include Index: head/share/doc/handbook/eresources.sgml =================================================================== --- head/share/doc/handbook/eresources.sgml (revision 17325) +++ head/share/doc/handbook/eresources.sgml (revision 17326) @@ -1,368 +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

World Wide Web servers

- Central Server. - Australia. - Brazil. - Canada. - Czech Republic. - Denmark. - Estonia. - Finland. - Germany. - Ireland. - Japan. - Korea. - Netherlands. - Portugal. - Sweden. - Taiwan. Index: head/share/doc/handbook/handbook.sgml =================================================================== --- head/share/doc/handbook/handbook.sgml (revision 17325) +++ head/share/doc/handbook/handbook.sgml (revision 17326) @@ -1,168 +1,168 @@ - + %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 2.1.5</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.4 BSD 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> <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> - <sect><heading>* Hardwired Terminals</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> Index: head/share/doc/handbook/sections.sgml =================================================================== --- head/share/doc/handbook/sections.sgml (revision 17325) +++ head/share/doc/handbook/sections.sgml (revision 17326) @@ -1,55 +1,56 @@ -<!-- $Id: sections.sgml,v 1.14 1996/06/30 18:01:25 phk Exp $ --> +<!-- $Id: sections.sgml,v 1.15 1996/07/02 23:16:17 wosch Exp $ --> <!-- The FreeBSD Documentation Project --> <!-- Entities containing all the pieces of the handbook are --> <!-- defined here --> <!ENTITY bibliography SYSTEM "bibliography.sgml"> <!ENTITY basics SYSTEM "basics.sgml"> <!ENTITY booting SYSTEM "booting.sgml"> <!ENTITY contrib SYSTEM "contrib.sgml"> <!ENTITY ctm SYSTEM "ctm.sgml"> <!ENTITY current SYSTEM "current.sgml"> <!ENTITY stable SYSTEM "stable.sgml"> <!ENTITY crypt SYSTEM "crypt.sgml"> <!ENTITY dialup SYSTEM "dialup.sgml"> <!ENTITY diskless SYSTEM "diskless.sgml"> <!ENTITY dma SYSTEM "dma.sgml"> <!ENTITY eresources SYSTEM "eresources.sgml"> <!ENTITY esdi SYSTEM "esdi.sgml"> <!ENTITY firewalls SYSTEM "firewalls.sgml"> <!ENTITY goals SYSTEM "goals.sgml"> <!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY history SYSTEM "history.sgml"> <!ENTITY hw SYSTEM "hw.sgml"> <!ENTITY install SYSTEM "install.sgml"> +<!ENTITY term SYSTEM "term.sgml"> <!ENTITY isdn SYSTEM "isdn.sgml"> <!ENTITY kerberos SYSTEM "kerberos.sgml"> <!ENTITY kernelconfig SYSTEM "kernelconfig.sgml"> <!ENTITY kerneldebug SYSTEM "kerneldebug.sgml"> <!ENTITY linuxemu SYSTEM "linuxemu.sgml"> <!ENTITY memoryuse SYSTEM "memoryuse.sgml"> <!ENTITY mirrors SYSTEM "mirrors.sgml"> <!ENTITY nfs SYSTEM "nfs.sgml"> <!ENTITY nutshell SYSTEM "nutshell.sgml"> <!ENTITY pgpkeys SYSTEM "pgpkeys.sgml"> <!ENTITY policies SYSTEM "policies.sgml"> <!ENTITY porting SYSTEM "porting.sgml"> <!ENTITY ports SYSTEM "ports.sgml"> <!ENTITY ppp SYSTEM "ppp.sgml"> <!ENTITY printing SYSTEM "printing.sgml"> <!ENTITY quotas SYSTEM "quotas.sgml"> <!ENTITY relnotes SYSTEM "relnotes.sgml"> <!ENTITY routing SYSTEM "routing.sgml"> <!ENTITY scsi SYSTEM "scsi.sgml"> <!ENTITY sio SYSTEM "sio.sgml"> <!ENTITY cy SYSTEM "cyclades.sgml"> <!ENTITY skey SYSTEM "skey.sgml"> <!ENTITY slipc SYSTEM "slipc.sgml"> <!ENTITY slips SYSTEM "slips.sgml"> <!ENTITY submitters SYSTEM "submitters.sgml"> <!ENTITY sup SYSTEM "sup.sgml"> <!ENTITY synching SYSTEM "synching.sgml"> <!ENTITY troubleshooting SYSTEM "troubleshooting.sgml"> <!ENTITY uart SYSTEM "uart.sgml"> <!ENTITY userppp SYSTEM "userppp.sgml"> Index: head/share/doc/handbook/term.sgml =================================================================== --- head/share/doc/handbook/term.sgml (nonexistent) +++ head/share/doc/handbook/term.sgml (revision 17326) @@ -0,0 +1,539 @@ +<!-- This is an SGML document in the linuxdoc DTD describing + hardwired terminals with FreeBSD. By Sean Kelly, (c) 1996. + + $Id$ + + 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. + + 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. + + <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> + + + Property changes on: head/share/doc/handbook/term.sgml ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property